XuqmGroup-RNSDK/docs/XWebView-JSBridge.md

XWebView JSBridge 标准接口

最后更新：2026-06-15

---

概述

XWebView 内置 JSBridge，支持 H5 页面与 React Native 宿主之间的双向通信。

通信机制：

• H5 → RN：window.ReactNativeWebView.postMessage(JSON.stringify(data))
• RN → H5：webViewRef.injectJavaScript(jsString)

---

一、H5 → RN 消息协议

1.1 内置消息（__xwv 前缀）

XWebView 自动拦截以下浏览器行为，通过 postMessage 发送给 RN：

消息类型	触发场景	数据格式
alert	window.alert(msg)	{__xwv: 'alert', msg: string}
confirm	window.confirm(msg)	{__xwv: 'confirm', msg: string}
prompt	window.prompt(msg, def)	{__xwv: 'prompt', msg: string, def: string}
download	点击下载链接	{__xwv: 'download', url: string, filename: string}
blobdownload	blob URL 下载	{__xwv: 'blobdownload', url: string, filename: string, data: base64}
bloberror	blob 读取失败	{__xwv: 'bloberror', msg: string}
log	调试日志	{__xwv: 'log', msg: string}

1.2 自定义消息

H5 发送非 __xwv 前缀的消息时，XWebView 将其转发给 onMessage 回调：

// H5 端
window.ReactNativeWebView.postMessage(JSON.stringify({
  type: 'customEvent',
  payload: { key: 'value' }
}));

// RN 端
<XWebViewView
  onMessage={(event) => {
    const data = JSON.parse(event.nativeEvent.data);
    if (data.type === 'customEvent') {
      // 处理自定义消息
    }
  }}
/>

---

二、RN → H5 通信

2.1 注入 JavaScript

// 通过 controller API
controller.postMessageToWeb('window.dispatchEvent(new CustomEvent("rnMessage", {detail: {type: "update", data: "hello"}}))');

// 通过 ref
webViewRef.injectJavaScript('window.handleRNMessage("hello")');

2.2 Controller API

通过 setXWebViewController 获取的 controller 对象提供以下方法：

方法	说明
refresh()	刷新当前页面
close()	关闭 WebView
goBack()	返回上一页
goForward()	前进
copyUrl()	复制当前 URL 到剪贴板
postMessageToWeb(jsString)	向 H5 注入并执行 JS
getTitle()	获取当前页面标题

---

三、下载处理

3.1 自动下载拦截

XWebView 自动拦截以下文件扩展名的链接点击：

.pdf .zip .rar .tar .gz .apk .ipa .doc .docx .xls .xlsx .ppt .pptx .mp4 .mp3 .mov .exe .dmg

3.2 下载回调

<XWebViewView
  autoDownload={true}
  onDownloadStart={(request) => {
    // request: { url, suggestedFilename, mimeType?, fileSize? }
    console.log('Download started:', request.suggestedFilename);
  }}
  onDownloadProgress={(progress) => {
    // progress: { url, filename, received, total, percentage }
    console.log(`Download: ${progress.percentage}%`);
  }}
  onDownloadComplete={(result) => {
    // result: { url, filename, filePath, fileSize }
    console.log('Download complete:', result.filePath);
  }}
  onDownloadError={(url, error) => {
    console.error('Download failed:', url, error);
  }}
  onDownloadDecide={(request) => {
    // 返回下载决策
    return { allowed: true, filename: request.suggestedFilename };
  }}
  downloadConflict="rename" // 'rename' | 'overwrite'
/>

3.3 Blob URL 下载

XWebView 自动处理 blob URL 下载：

1. 拦截 <a href="blob:..."> 点击
2. 通过 FileReader 读取 blob 数据为 base64
3. 通过 saveBase64File 保存到本地

---

四、内置 Dialog 覆盖

XWebView 注入 DIALOG_OVERRIDE_JS，覆盖浏览器原生对话框：

原生方法	覆盖行为
window.alert(msg)	发送 {__xwv: 'alert', msg} 消息
window.confirm(msg)	发送 {__xwv: 'confirm', msg} 消息，始终返回 true
window.prompt(msg, def)	发送 {__xwv: 'prompt', msg, def} 消息，返回默认值
window.open(url)	发送日志消息，然后 window.location.href = url

RN 端收到这些消息后，可以展示原生 Alert/Confirm/Prompt 对话框。

---

五、标准 Bridge 接口（宿主实现）

以下接口由宿主应用通过 bridgeHandlers 实现，H5 通过 xuqm.call(method, params) 调用：

5.1 会话管理

接口	参数	返回值	说明
getSession	—	{token, userId}	获取当前登录会话
getUserInfo	—	{userId, name, phone, avatar}	获取用户信息

5.2 导航

接口	参数	返回值	说明
navigate	{screen, params?}	—	跳转宿主页面
close	—	—	关闭当前 WebView
goBack	—	—	返回上一页

5.2 UI 交互

接口	参数	返回值	说明
showToast	{message}	—	显示 Toast
showAlert	{title?, message}	—	显示 Alert 对话框
showConfirm	{title?, message, confirmText?, cancelText?}	{confirmed: boolean}	显示确认对话框

5.3 文件操作

接口	参数	返回值	说明
uploadFile	{accept?}	{url, name, size}	选择并上传文件
openCamera	—	{url, base64}	打开相机拍照
scanQR	—	{result}	扫描二维码

5.4 设备信息

接口	参数	返回值	说明
getDeviceInfo	—	{platform, version, model}	获取设备信息
getLocation	—	{latitude, longitude}	获取当前位置

---

六、H5 端调用示例

// 获取会话
xuqm.call('getSession').then(session => {
  console.log('Token:', session.token);
});

// 跳转宿主页面
xuqm.call('navigate', { screen: 'Settings' });

// 显示 Toast
xuqm.call('showToast', { message: '操作成功' });

// 上传文件
xuqm.call('uploadFile', { accept: 'image/*' }).then(file => {
  console.log('Uploaded:', file.url);
});