## @realsee/jsbridge-x

![](https://img.shields.io/npm/v/@realsee/jsbridge-x.svg?style=flat-square)
![](https://img.shields.io/npm/dm/@realsee/jsbridge-x.svg?style=flat-square)

**@realsee/jsbridge-x** SDK 需搭配 **[VRWebView 容器]()** 一起使用。
通过此 SDK 可实现 **[VRWebView 容器]()** 与其嵌入的前端 Web 页面间的消息传递和数据交换。

本 SDK 仅供 Web 端 JavaScript 环境使用，关于客户端(iOS/Android)、小程序环境的 `VRWebView` 请移步 [**VRWebView 容器** 接入文档]()。

## Install

npm/yarn

```shell
npm install @realsee/jsbridge-x
# or
yarn add @realsee/jsbridge-x
```

cdn

```html
<!-- production -->
<script src="//unpkg.com/@realsee/jsbridge-x@${version}/dist/jsbridge/index.min.js"></script>
```

## Usage

如视针对 iOS\Android、微信小程序等终端、平台均提供了对应的 **[VRWebView 容器]()**。同样的，**@realsee/jsbridge-x** 根据不同的 **[VRWebView 容器]()** 做了适配，您可根据当前的容器选择对应的 `jsBridge` 版本。

```js
// iOS/Android/微信小程序/浏览器
import JSBridge from '@realsee/jsbridge-x'

const jsBridge = new JSBridge({})

// 监听 jsBridge 是否完成初始化
jsBridge.on('inited', () => /** */)

// 获取当前容器的设备信息
const [deviceInfo, err] = await jsBridge.getDeviceInfo()

// 获取初始化时容器下发的完整静态数据（包含设备信息及可选用户信息）
const [staticData, staticDataErr] = await jsBridge.getStaticData()

```

### 适配情况

- [x] [iOS VRWebView]()
- [x] [Android VRWebView]()
- [x] 微信小程序
- [x] 浏览器
- [ ] 头条小程序
- [ ] 百度小程序

> 注意：浏览器本身就是 WebView 的完整版，并不存在所谓的 `jsBridge`。但为了保障业务源码逻辑的统一性，我们在浏览器环境下也模拟出一个 `jsBridge` 概念。

### 事件监听

#### - `'webViewStateChange': (webViewState: WebViewState) => void` `WebView` 状态发生更新

#### - `'error'(error: Error): void` 异常\错误

### 内置接口

#### - `webViewType: WebViewTypeEnum` WebView 类型

#### - `ready: () => Promise<JSBridgeReturnType<boolean>>` 判断 jsBridge 是否就绪

#### - `loadProgress: (progress: number) => Promise<JSBridgeReturnType<boolean>>` 控制进度条

#### - `closeLoading: () => Promise<JSBridgeReturnType<boolean>>` 关闭进度条

#### - `getDeviceInfo: () => Promise<JSBridgeReturnType<DeviceInfo | false>>` 获取容器设备信息

#### - `getStaticData: () => Promise<JSBridgeReturnType<StaticData | false>>` 获取初始化时容器下发的完整静态数据

#### - `getWebViewState: () => Promise<JSBridgeReturnType<WebViewState | false>>` 获取最新 WebView 状态

#### - `setLeftTopBackButton: (enable: boolean) => Promise<JSBridgeReturnType<boolean>>` 设置左上角隐藏返回按钮（仅 iOS 端有效）

#### - `login: () => Promise<JSBridgeReturnType<UserInfo | false>>` 登录

#### - `logout: () => Promise<JSBridgeReturnType<boolean>>` 登出

#### - `getUserInfo: () => Promise<JSBridgeReturnType<UserInfo | false>>` 获取用户信息（已登录情况下）

#### - `openWebView: (url: string, way: OpenWebViewEnum) => Promise<JSBridgeReturnType<boolean>>` 打开新的 WebView

#### - `closeWebView: () => Promise<JSBridgeReturnType<boolean>>` 关闭当前 WebView

#### - `getBangsHeight: () => Promise<JSBridgeReturnType<number | false>>` 获取"刘海"\"挖孔"占用屏幕高度

#### - `setOrientation: (orientation: OrientationEnum) => Promise<JSBridgeReturnType<boolean>>` 设置横竖屏

#### - `keepScreenLight: (enable: boolean) => Promise<JSBridgeReturnType<boolean>>` 保持屏幕常亮

#### - `shock: (duration?: number) => Promise<JSBridgeReturnType<boolean>>` 震动

> 参数 `duration` 在 iOS 端表示震动次数；在 Android 端表示震动时长（单位：秒）。

#### - `minimize: () => Promise<JSBridgeReturnType<boolean>>` 最小化（"小窗"模式）。

#### - `saveImage2Album: (base64: string) => Promise<JSBridgeReturnType<boolean>>` 保持图片至相册

#### - `detectMicro: () => Promise<JSBridgeReturnType<boolean>>` 监测麦克风授权

#### - `actionShare: (shareConfig: Partial<ShareConfig>) => Promise<JSBridgeReturnType<boolean>>` 分享

#### - `preload: (urls: string[]) => Promise<JSBridgeReturnType<boolean>>` 静态资源预载

#### - `createCacheProxyUrl: (urls: string | string[]) => string[]` 生成代理请求链接

### 自定义接口

`jsBridge` 提供的内置接口基本满足大部分 `js` 环境与客户端双向通信的需求。当然，有些特殊定制类需求内置接口可能并没有兼顾到，你可以通过如下两个比较原子方法实现与客户端的双向通信。

#### - `callAndBackfeed: <T>(scheme: string) => Promise<JSBridgeReturnType<T | false>>`

> 发送 `scheme` 信息给客户端，客户端收到信息后会立马返回给前端。

#### - `callAndListen: <T>(scheme: string, callback: (data: T) => void) => Promise<JSBridgeReturnType<false | (() => void)>>`

> 发送 `scheme` 信息给客户端，客户端会监听相关状态的变化，当相关状态发生后变更后会立马通过回调的方式反馈给前端。与`callAndBackfeed` 的区别是：`callAndBackfeed()` 是一次性行为，`callAndListen()` 监听行为。

## TypeScript/React 支持