介绍
借助于 @consenlabs-fe/webview
,我们可以轻松地访问和使用 imToken WebView 环境中的各种接口。无论是将 DApp 迁移到 imToken 应用还是改编自己的 Web 应用程序,都可以用最少的代码和最小的侵入性快速解决。
该 SDK 包括获得语言环境、Native UI、路由导航、扫描二维码等功能。SDK 本身不包含依赖性,只作为绑定宿主环境的工具,不会对你的项目造成任何侵入性的损害。
支持功能
完善的 TypeScript 支持
所有的接口都有完善的类型支持,大部分场景下甚至无需参考文档就能完成开发。
多模块支持
在现代化的前端项目中,esm
是默认模块导入方式,但我们仍旧支持 cjs
umd
等模块。
Promise
当前,所有的异步方法都会支持 Promise
,并有相应的类型标识。
社区与反馈
现在我们提供开发者社区的支持,你可以在 GitHub 的讨论区 创建一个讨论主题 留下任何有关 WebView 或 DApp 的问题。
快速开始
如果你正在寻找一个完整的项目示例,请查看我们准备好的完整项目示例:
安装
建议使用包管理工具下载与安装 @consenlabs-fe/webview
。为此,我们的项目需要 NodeJS 环境与 NPM 管理工具。(或是 Yarn )
NPM: (推荐方式)
Copy npm i @consenlabs-fe/webview
Yarn:
Copy yarn add @consenlabs-fe/webview
CDN:
@consenlabs-fe/webview
也支持使用 unpkg 或 jsdelivr 以 CDN 地址的方式在外部加载 (CDN 同步最新的版本可能需要一些时间)
Copy <script src="https://cdn.jsdelivr.net/npm/@consenlabs-fe/webview/dist/index.min.js" />
引入和使用
在使用 SDK 之前,你需要使用 import
引入模块:
Copy import TokenWebView from '@consenlabs-fe/webview'
为了保持兼容性,我们建议你总是在使用前先判断是否处于 imToken 环境中 :
Copy if ( TokenWebView .isTokenEnv ()) {
TokenWebView . apis . navigator .setTitle ( 'hello world' )
}
API 参考
这是所有的 API 和类型参考。事实上如果你正在使用 TypeScript,项目中已经有完善的接口提示。
通用
这是根模块携带的静态 API (纯函数),通常用于检查环境和通用场景的处理。
isTokenEnv
检查当前是否处于 imToken WebView 环境中,返回布尔值。
类型
Copy type isTokenEnv = () => boolean
使用示例
Copy console .log ( 'Currently in imToken: ' , TokenWebView .isTokenEnv ())
getVersion
获取 imToken 应用当前版本。
类型
Copy type getVersion = () => string
使用示例
Copy console .log ( 'Currently version: ' , TokenWebView .getVersion ())
// output -> 'Currently version: 2.4.0'
isGreaterThanOrEqualVersion
判断 imToken 应用的当前版本是否大于指定值。
类型
Copy type isGreaterThanOrEqualVersion = (version : string ) => boolean
使用示例
Copy const state = TokenWebView .isGreaterThanOrEqualVersion ( '2.1.0' )
console .log ( 'Version greater than or equal to 2.1.0: ' , state )
// output -> 'Version greater than or equal to 2.1.0: true'
compareSemver
比较两个版本的值并返回数字。
对比的值必须为语义化版本 的字符串,返回值和对比逻辑与 JavaScript sort function 完全一致。
类型
Copy type compareSemver = (versionA : string , versionB : string ) => number
使用示例
Copy const state = TokenWebView .compareSemver ( '2.1.0' , '2.2.0' )
console .log (state)
// output -> '0'
isCancelError
检查错误是否为用户取消。
类型
Copy type isCancelError = (error : Error ) => boolean
使用示例
Copy try {
// ...
} catch (err) {
if ( TokenWebView .isCancelError (err)) {
console .log ( 'User cancelled the operation' )
}
}
ERRORS
错误常量的集合。大多数场景下不需要直接引用此常量。
类型
Copy type ERRORS = Record < string , string >
apis
与宿主环境进行通信的 API,详见下文。
device API
getCurrentLanguage
获取当前的语言环境,来源于用户在 imToken 应用内的设定。
类型
Copy type getCurrentLanguage = () => Promise < string >
使用示例
Copy const language = await TokenWebView . apis . device .getCurrentLanguage ()
console .log (language)
// output -> 'en-us'
getCurrentCurrency
获取当前的货币编码。
类型
Copy type getCurrentCurrency = () => Promise < string >
使用示例
Copy const currency = await TokenWebView . apis . device .getCurrentCurrency ()
console .log (currency)
// output -> 'CNY'
native API
提供原生平台 UI 与交互能力。
alert
在弹窗中显示字符串。
类型
Copy type alert = (content : string ) => void
使用示例
Copy TokenWebView . apis . native .alert ( 'hello world!' )
confirm
打开一个确认会话窗口。
用户点击确认或取消后会返回布尔值。
类型
Copy type confirm = (content : {
title : string
message : string
cancelText : string
confirmText : string
}) => Promise < boolean >
使用示例
Copy const isConfirmDeletion = await TokenWebView . apis . native .confirm ({
title : 'Second Confirmation' ,
message : 'Remove current connection?' ,
confirmText : 'ok' ,
cancelText : 'NO' ,
})
setLoading
设置当前 WebView 为 Loading 状态。
如果你没有主动取消此状态,用户将无法进行任何操作。Loading 状态将会屏蔽用户的行为事件。
类型
Copy type setLoading = (visible : boolean ) => void
使用示例
Copy if (myTaskLoading) {
TokenWebView . apis . native .setLoading ( true )
}
share
分享链接或是图片。
当分享内容为图片时,需要编码为 base64
格式。
是否能够成功分享取决于用户的确认与是否允许权限。
类型
Copy type ShareParamsDefault = {
title : string
message : string
url : string
}
type ShareParamsImage = {
title : string
image : string
}
type share = (params : ShareParamsDefault & ShareParamsImage ) => Promise < boolean >
使用示例
Copy const isSuccess = await TokenWebView . apis . native .share ({
title : 'Share' ,
message : 'Share this page with others' ,
url : location .href ,
})
scanQRCode
调用摄像头扫描二维码,扫码完成将会返回字符串,失败或取消将抛出错误。
类型
Copy type scanQRCode = () => Promise < string >
使用示例
Copy try {
const text = await TokenWebView . apis . native .scanQRCode ()
} catch (err) {
console .log ( 'scan failed.' )
}
setClipboard
粘贴字符串。
类型
Copy type setClipboard = (text : string ) => void
使用示例
Copy TokenWebView . apis . native .setClipboard ( 'address' )
navigator API
路由与页面设置。
closeDapp
关闭当前 DApp。
类型
Copy type closeDapp = () => void
使用示例
Copy TokenWebView . apis . navigator .closeDapp ()
goBack
返回上一层路由,如果路由栈为空将会关闭 DApp。
类型
Copy type goBack = () => void
使用示例
Copy TokenWebView . apis . navigator .goBack ()
routeTo
跳转至指定页面。
类型
Copy type RouteToParams = {
screen : string
props : {
title : string
url : string
}
}
type routeTo = (params : RouteToParams ) => void
使用示例
Copy // Jump to other DApps
TokenWebView . apis . navigator .routeTo ({
screen : 'DappView' ,
props : {
title : 'DApp API Examples' ,
url : 'https://consenlabs.github.io/' ,
} ,
})
getOrientation
获取当前设备的方向信息。
类型
Copy type Orientation = 'LANDSCAPE' | 'PORTRAIT'
type getOrientation = () => Promise < Orientation >
使用示例
Copy const orientation = await TokenWebView . apis . navigator .getOrientation ()
console .log (orientation)
// output -> 'LANDSCAPE'
setOrientation
设置设备方向。
类型
Copy type Orientation = 'LANDSCAPE' | 'PORTRAIT'
type setOrientation = (orientation : Orientation ) => void
使用示例
Copy TokenWebView . apis . navigator .setOrientation ( 'LANDSCAPE' )
setTitle
动态设置 DApp 的标题,这仅会影响 WebView 的标题,不会更改 Web 的 title
。
类型
Copy type setTitle = (title : string ) => void
使用示例
Copy TokenWebView . apis . navigator .setTitle ( 'MY DAPP' )
user API
showAccountSwitch
展示钱包的切换面板。如果切换成功,新的地址将会被返回。
类型
Copy type ChainType =
| 'ETHEREUM'
| 'BITCOIN'
| 'LITECOIN'
| 'EOS'
| 'COSMOS'
| 'TRON'
| 'BITCOINCASH'
| 'NERVOS'
| 'KUSAMA'
| 'POLKADOT'
| 'FILECOIN'
type showAccountSwitch = (chainType : ChainType | null ) => Promise < string >
使用示例
Copy const address = await TokenWebView . apis . user .showAccountSwitch ( 'ETHEREUM' )
console .log (address)
// output -> '0x...'
layout API
setOptions
设置 WebView 的外部框架样式。
这将同步更新当前 WebView 的布局,并且只能在页面被加载和解析后应用。如果你想在页面加载时对布局进行修改,请参考我们的预加载配置文档。
类型
Copy type HexColor = `# ${ string } `
type StatusBarStyle = 0 | 1 | 2
type WebViewLayoutOptions = {
background ?: HexColor | Array < HexColor >
foreground ?: HexColor
isTitleLeft ?: boolean
titleSize ?: number
isTransparent ?: boolean
transparentScrollY ?: number
loadingBackground ?: HexColor
loadingForeground ?: HexColor
bodyBackground ?: HexColor
bodyForeground ?: HexColor
statusBarStyle ?: StatusBarStyle
}
type setOptions = (options : WebViewLayoutOptions ) => void
使用示例
Copy TokenWebView . apis . layout .setOptions ({
background : '#000000' ,
titleSize : 20 ,
})
internal API
未稳定的 API,主要用于高级用户定制开发和调试。