@realsee/jsbridge-x
@realsee/jsbridge-x SDK 需搭配 VRWebView 容器 一起使用。 通过此 SDK 可实现 VRWebView 容器 与其嵌入的前端 Web 页面间的消息传递和数据交换。
本 SDK 仅供 Web 端 JavaScript 环境使用，关于客户端(iOS/Android)、小程序环境的 VRWebView 请移步 VRWebView 容器 接入文档。
Install
npm/yarn
npm install @realsee/jsbridge-x
# or
yarn add @realsee/jsbridge-x
cdn
<!-- production -->
<script src="//unpkg.com/@realsee/jsbridge-x@${version}/dist/jsbridge/index.min.js"></script>
Usage
如视针对 iOS\Android、微信小程序等终端、平台均提供了对应的 VRWebView 容器。同样的，@realsee/jsbridge-x 根据不同的 VRWebView 容器 做了适配，您可根据当前的容器选择对应的 jsBridge 版本。
// iOS/Android/微信小程序/浏览器
import JSBridge from '@realsee/jsbridge-x'
const jsBridge = new JSBridge({})
// 监听 jsBridge 是否完成初始化
jsBridge.on('inited', () => /** */)
// 获取当前容器的设备信息
const [deviceInfo, err] = await jsBridge.getDeviceInfo()
适配情况
- iOS VRWebView
- Android VRWebView
- 微信小程序
- 浏览器
- 头条小程序
- 百度小程序
注意：浏览器本身就是 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>> 获取容器设备信息
- 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()监听行为。