SDK APIs

访问 imToken 公开 API 的现代化工具。

介绍

借助于 @consenlabs-fe/webview，我们可以轻松地访问和使用 imToken WebView 环境中的各种接口。无论是将 DApp 迁移到 imToken 应用还是改编自己的 Web 应用程序，都可以用最少的代码和最小的侵入性快速解决。

该 SDK 包括获得语言环境、Native UI、路由导航、扫描二维码等功能。SDK 本身不包含依赖性，只作为绑定宿主环境的工具，不会对你的项目造成任何侵入性的损害。

支持功能

完善的 TypeScript 支持

所有的接口都有完善的类型支持，大部分场景下甚至无需参考文档就能完成开发。

多模块支持

在现代化的前端项目中，esm 是默认模块导入方式，但我们仍旧支持 cjs umd 等模块。

Promise

当前，所有的异步方法都会支持 Promise，并有相应的类型标识。

社区与反馈

现在我们提供开发者社区的支持，你可以在 GitHub 的讨论区 创建一个讨论主题 留下任何有关 WebView 或 DApp 的问题。

快速开始

如果你正在寻找一个完整的项目示例，请查看我们准备好的完整项目示例：

• React 项目示例：examples/react-app

• Vue 项目示例：examples/vue-app

• UMD 项目示例：examples/umd

安装

建议使用包管理工具下载与安装 @consenlabs-fe/webview 。为此，我们的项目需要 NodeJS 环境与 NPM 管理工具。(或是 Yarn)

NPM: (推荐方式)

npm i @consenlabs-fe/webview

Yarn:

yarn add @consenlabs-fe/webview

CDN:

@consenlabs-fe/webview 也支持使用 unpkg 或 jsdelivr 以 CDN 地址的方式在外部加载 (CDN 同步最新的版本可能需要一些时间)

<script src="https://cdn.jsdelivr.net/npm/@consenlabs-fe/webview/dist/index.min.js" />

引入和使用

在使用 SDK 之前，你需要使用 import 引入模块：

import TokenWebView from '@consenlabs-fe/webview'

为了保持兼容性，我们建议你总是在使用前先判断是否处于 imToken 环境中：

if (TokenWebView.isTokenEnv()) {
  TokenWebView.apis.navigator.setTitle('hello world')
}

API 参考

这是所有的 API 和类型参考。事实上如果你正在使用 TypeScript，项目中已经有完善的接口提示。

通用

这是根模块携带的静态 API (纯函数)，通常用于检查环境和通用场景的处理。

isTokenEnv

检查当前是否处于 imToken WebView 环境中，返回布尔值。

类型

type isTokenEnv = () => boolean 

使用示例

console.log('Currently in imToken: ', TokenWebView.isTokenEnv())

getVersion

获取 imToken 应用当前版本。

类型

type getVersion = () => string

使用示例

console.log('Currently version: ', TokenWebView.getVersion())

// output -> 'Currently version: 2.4.0'

isGreaterThanOrEqualVersion

判断 imToken 应用的当前版本是否大于指定值。

类型

type isGreaterThanOrEqualVersion = (version: string) => boolean

使用示例

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 完全一致。

类型

type compareSemver = (versionA: string, versionB: string) => number

使用示例

const state = TokenWebView.compareSemver('2.1.0', '2.2.0')
console.log(state)

// output -> '0'

isCancelError

检查错误是否为用户取消。

类型

type isCancelError = (error: Error) => boolean

使用示例

try {
  // ...
} catch (err) {
  if (TokenWebView.isCancelError(err)) {
    console.log('User cancelled the operation')
  }
}

ERRORS

错误常量的集合。大多数场景下不需要直接引用此常量。

类型

type ERRORS = Record<string, string>

apis

与宿主环境进行通信的 API，详见下文。

device API

getCurrentLanguage

获取当前的语言环境，来源于用户在 imToken 应用内的设定。

类型

type getCurrentLanguage = () => Promise<string>

使用示例

const language = await TokenWebView.apis.device.getCurrentLanguage()
console.log(language)

// output -> 'en-us'

getCurrentCurrency

获取当前的货币编码。

类型

type getCurrentCurrency = () => Promise<string>

使用示例

const currency = await TokenWebView.apis.device.getCurrentCurrency()
console.log(currency)

// output -> 'CNY'

native API

提供原生平台 UI 与交互能力。

alert

在弹窗中显示字符串。

类型

type alert = (content: string) => void

使用示例

TokenWebView.apis.native.alert('hello world!')

confirm

打开一个确认会话窗口。

用户点击确认或取消后会返回布尔值。

类型

type confirm = (content: {
  title: string
  message: string
  cancelText: string
  confirmText: string
}) => Promise<boolean>

使用示例

const isConfirmDeletion = await TokenWebView.apis.native.confirm({
  title: 'Second Confirmation',
  message: 'Remove current connection?',
  confirmText: 'ok',
  cancelText: 'NO',
})

setLoading

设置当前 WebView 为 Loading 状态。

如果你没有主动取消此状态，用户将无法进行任何操作。Loading 状态将会屏蔽用户的行为事件。

类型

type setLoading = (visible: boolean) => void

使用示例

if (myTaskLoading) {
  TokenWebView.apis.native.setLoading(true)
}

share

分享链接或是图片。

当分享内容为图片时，需要编码为 base64 格式。

是否能够成功分享取决于用户的确认与是否允许权限。

类型

type ShareParamsDefault = {
  title: string
  message: string
  url: string
}

type ShareParamsImage = {
  title: string
  image: string
}

type share = (params: ShareParamsDefault & ShareParamsImage) => Promise<boolean>

使用示例

const isSuccess = await TokenWebView.apis.native.share({
  title: 'Share',
  message: 'Share this page with others',
  url: location.href,
})

scanQRCode

调用摄像头扫描二维码，扫码完成将会返回字符串，失败或取消将抛出错误。

类型

type scanQRCode = () => Promise<string>

使用示例

try {
  const text = await TokenWebView.apis.native.scanQRCode()
} catch (err) {
  console.log('scan failed.')
}

setClipboard

粘贴字符串。

类型

type setClipboard = (text: string) => void

使用示例

TokenWebView.apis.native.setClipboard('address')

navigator API

路由与页面设置。

closeDapp

关闭当前 DApp。

类型

type closeDapp = () => void

使用示例

TokenWebView.apis.navigator.closeDapp()

goBack

返回上一层路由，如果路由栈为空将会关闭 DApp。

类型

type goBack = () => void

使用示例

TokenWebView.apis.navigator.goBack()

routeTo

跳转至指定页面。

类型

type RouteToParams = {
  screen: string 
  props: {
    title: string
    url: string
  }
}

type routeTo = (params: RouteToParams) => void

使用示例

// Jump to other DApps

TokenWebView.apis.navigator.routeTo({
  screen: 'DappView',
  props: {
    title: 'DApp API Examples',
    url: 'https://consenlabs.github.io/',
  },
})

getOrientation

获取当前设备的方向信息。

类型

type Orientation = 'LANDSCAPE' | 'PORTRAIT'

type getOrientation = () => Promise<Orientation>

使用示例

const orientation = await TokenWebView.apis.navigator.getOrientation()
console.log(orientation)

// output -> 'LANDSCAPE'

setOrientation

设置设备方向。

类型

type Orientation = 'LANDSCAPE' | 'PORTRAIT'

type setOrientation = (orientation: Orientation) => void

使用示例

TokenWebView.apis.navigator.setOrientation('LANDSCAPE')

setTitle

动态设置 DApp 的标题，这仅会影响 WebView 的标题，不会更改 Web 的 title 。

类型

type setTitle = (title: string) => void

使用示例

TokenWebView.apis.navigator.setTitle('MY DAPP')

user API

showAccountSwitch

展示钱包的切换面板。如果切换成功，新的地址将会被返回。

类型

type ChainType =
  | 'ETHEREUM'
  | 'BITCOIN'
  | 'LITECOIN'
  | 'EOS'
  | 'COSMOS'
  | 'TRON'
  | 'BITCOINCASH'
  | 'NERVOS'
  | 'KUSAMA'
  | 'POLKADOT'
  | 'FILECOIN'
  
type showAccountSwitch = (chainType: ChainType | null) => Promise<string>

使用示例

const address = await TokenWebView.apis.user.showAccountSwitch('ETHEREUM')
console.log(address)

// output -> '0x...'

layout API

setOptions

设置 WebView 的外部框架样式。

这将同步更新当前 WebView 的布局，并且只能在页面被加载和解析后应用。如果你想在页面加载时对布局进行修改，请参考我们的预加载配置文档。

类型

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

使用示例

TokenWebView.apis.layout.setOptions({
  background: '#000000',
  titleSize: 20,
})

internal API

未稳定的 API，主要用于高级用户定制开发和调试。