# SDK APIs

## 介绍

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

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

## 支持功能

### 完善的 TypeScript 支持

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

<div align="left"><img src="/files/-MWd2zezzbkwmaqQkf_g" alt=""></div>

### 多模块支持

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

### Promise

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

### 社区与反馈

现在我们提供开发者社区的支持，你可以在 GitHub 的讨论区 [创建一个讨论主题](https://github.com/consenlabs/webview/discussions/new) 留下任何有关 WebView 或 DApp 的问题。

## 快速开始

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

* React 项目示例：[examples/react-app](https://github.com/consenlabs/webview/blob/master/examples/react-app)
* Vue 项目示例：[examples/vue-app](https://github.com/consenlabs/webview/tree/master/examples/vue-app)
* UMD 项目示例：[examples/umd](https://github.com/consenlabs/webview/tree/master/examples/umd)

### 安装

建议使用包管理工具下载与安装 `@consenlabs-fe/webview` 。为此，我们的项目需要 [NodeJS](https://nodejs.org/en/download/) 环境与 [NPM](https://www.npmjs.com/) 管理工具。(或是 [Yarn](https://yarnpkg.com/))

**NPM:** (推荐方式)

```bash
npm i @consenlabs-fe/webview
```

**Yarn:**

```bash
yarn add @consenlabs-fe/webview
```

**CDN:**

&#x20;`@consenlabs-fe/webview` 也支持使用 [unpkg](https://unpkg.com/@consenlabs-fe/webview/dist/index.js) 或 [jsdelivr](https://cdn.jsdelivr.net/npm/@consenlabs-fe/webview/dist/index.min.js) 以 CDN 地址的方式在外部加载 (CDN 同步最新的版本可能需要一些时间)

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

### 引入和使用

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

```typescript
import TokenWebView from '@consenlabs-fe/webview'
```

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

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

## API 参考

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

### 通用

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

#### isTokenEnv

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

**类型**

```typescript
type isTokenEnv = () => boolean 
```

**使用示例**

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

####

#### getVersion

获取 imToken 应用当前版本。

**类型**

```typescript
type getVersion = () => string
```

**使用示例**

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

// output -> 'Currently version: 2.4.0'
```

####

#### isGreaterThanOrEqualVersion

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

**类型**

```typescript
type isGreaterThanOrEqualVersion = (version: string) => boolean
```

**使用示例**

```typescript
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

比较两个版本的值并返回数字。

对比的值必须为[语义化版本](https://semver.org/)的字符串，返回值和对比逻辑与 [JavaScript sort function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) 完全一致。

**类型**

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

**使用示例**

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

// output -> '0'
```

#### isCancelError

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

**类型**

```typescript
type isCancelError = (error: Error) => boolean
```

**使用示例**

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

#### ERRORS

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

**类型**

```typescript
type ERRORS = Record<string, string>
```

#### apis

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

### device API

#### getCurrentLanguage

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

**类型**

```typescript
type getCurrentLanguage = () => Promise<string>
```

**使用示例**

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

// output -> 'en-us'
```

#### getCurrentCurrency

获取当前的货币编码。

**类型**

```typescript
type getCurrentCurrency = () => Promise<string>
```

**使用示例**

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

// output -> 'CNY'
```

###

### native API

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

#### alert

在弹窗中显示字符串。

**类型**

```typescript
type alert = (content: string) => void
```

**使用示例**

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

####

#### confirm

打开一个确认会话窗口。

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

**类型**

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

**使用示例**

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

#### setLoading

设置当前 WebView 为 Loading 状态。

{% hint style="warning" %}
如果你没有主动取消此状态，用户将无法进行任何操作。Loading 状态将会屏蔽用户的行为事件。
{% endhint %}

**类型**

```typescript
type setLoading = (visible: boolean) => void
```

**使用示例**

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

#### share

分享链接或是图片。

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

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

**类型**

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

type ShareParamsImage = {
  title: string
  image: string
}

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

**使用示例**

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

#### scanQRCode

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

**类型**

```typescript
type scanQRCode = () => Promise<string>
```

**使用示例**

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

```

#### setClipboard

粘贴字符串。

**类型**

```typescript
type setClipboard = (text: string) => void
```

**使用示例**

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

```

###

### navigator API

路由与页面设置。

#### closeDapp

关闭当前 DApp。

**类型**

```typescript
type closeDapp = () => void
```

**使用示例**

```typescript
TokenWebView.apis.navigator.closeDapp()
```

####

#### goBack

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

**类型**

```typescript
type goBack = () => void
```

**使用示例**

```typescript
TokenWebView.apis.navigator.goBack()
```

####

#### routeTo

跳转至指定页面。

**类型**

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

type routeTo = (params: RouteToParams) => void
```

**使用示例**

```typescript
// Jump to other DApps

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

####

#### getOrientation

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

**类型**

```typescript
type Orientation = 'LANDSCAPE' | 'PORTRAIT'

type getOrientation = () => Promise<Orientation>
```

**使用示例**

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

// output -> 'LANDSCAPE'
```

####

#### setOrientation

设置设备方向。

**类型**

```typescript
type Orientation = 'LANDSCAPE' | 'PORTRAIT'

type setOrientation = (orientation: Orientation) => void
```

**使用示例**

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

####

#### setTitle

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

**类型**

```typescript
type setTitle = (title: string) => void
```

**使用示例**

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

####

### user API

#### showAccountSwitch

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

**类型**

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

**使用示例**

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

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

### layout API

#### setOptions

设置 WebView 的外部框架样式。

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

**类型**

```typescript
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
```

**使用示例**

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

####

### internal API

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://imtoken.gitbook.io/developers/zh/products/webview/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.