XuqmGroup-RNSDK/packages/xwebview

@xuqm/rn-xwebview

XuqmGroup RN SDK WebView 模块。提供增强型 WebView 组件和 JSBridge 通信能力。

安装

yarn add @xuqm/rn-xwebview react-native-webview react-native-blob-util react-native-svg

Peer dependencies：react >= 18，react-native >= 0.76，@react-navigation/native >= 7.0.0

组件

XWebViewScreen — 全屏 WebView（React Navigation screen）

import { XWebViewScreen } from '@xuqm/rn-xwebview'

// 在导航中使用
<XWebViewScreen />
// URL 通过 openXWebView() 预设

XWebViewView — 嵌入式 WebView 组件

import { XWebViewView } from '@xuqm/rn-xwebview'

<XWebViewView
  config={{
    url: 'https://example.com',
    title: '嵌入式网页',
    jsBridgeName: 'XWebViewBridge',
  }}
/>

XWebViewProgress — 进度条

import { XWebViewProgress } from '@xuqm/rn-xwebview'

<XWebViewProgress progress={50} />

API

API	说明
openXWebView(url, options?)	打开 WebView 页面
setXWebViewController(controller)	设置全局 WebView 控制器
getXWebViewConfig()	获取当前 WebView 配置
XWebViewControl	WebView 控制器类

XWebViewConfig 参数

参数	类型	说明
url	string	初始加载地址
title	string	页面标题
jsBridgeName	string	JS 桥接对象名（默认 'XWebViewBridge'）
hideToolbar	boolean	隐藏顶栏
userAgent	string?	自定义 User-Agent
injectedJavaScript	string?	页面加载后注入的 JS
onMessage	(event) => void	H5 发送消息回调

JSBridge 通信

// H5 → Native
window.XWebViewBridge.postMessage(JSON.stringify({ type: 'login', token: '...' }))

// Native → H5
controller.postMessageToWeb("window.dispatchEvent(new CustomEvent('nativeMsg', { detail: { key: 'value' } }))")

内置 JSBridge Handler

Action	说明	参数
xuqm.getDeviceInfo	获取设备信息	—
xuqm.getToken	获取当前用户 token	—
xuqm.getUserInfo	获取用户信息	—
xuqm.openNativePage	打开原生页面	{ route, params? }
xuqm.closeWebView	关闭 WebView	—
xuqm.showToast	显示 Toast	{ message }
xuqm.scanQRCode	打开扫码页（需宿主注册 handler）	—

文件下载

XWebView 内置文件下载支持，自动拦截以下场景：

1. URL 以常见下载扩展名结尾（.pdf, .zip, .apk 等）
2. <a download="..."> 标签点击
3. blob: URL 下载（通过 injected JS 拦截）

使用 handleDownloadRequest

import { handleDownloadRequest } from '@xuqm/rn-xwebview'

const handle = await handleDownloadRequest(url, hintFilename, {
  autoDownload: true,
  downloadConflict: 'rename',
  onDownloadProgress: (p) => console.log(`${p.percentage}%`),
  onDownloadComplete: (r) => console.log('saved to', r.filePath),
  onDownloadError: (url, err) => console.error(err),
})
// handle?.cancel() 可取消下载

XWebViewConfig 下载相关参数

参数	类型	说明
autoDownload	boolean	自动下载（默认 true），false 时需 onDownloadDecide
downloadConflict	'rename' | 'overwrite'	文件名冲突策略（默认 rename）
onDownloadStart	(request) => void	下载开始回调
onDownloadProgress	(progress) => void	下载进度回调
onDownloadComplete	(result) => void	下载完成回调
onDownloadError	(url, error) => void	下载失败回调
onDownloadDecide	(request) => Decision	非自动模式下的下载决策回调

低级 API

API	说明
fetchDownloadInfo(url, hintFilename?)	HEAD 请求获取文件名/MIME/大小
saveBase64File(base64, filename, savePath?, conflict)	保存 base64 数据为文件
startDownload(url, filename, savePath?, conflict, onProgress, onComplete, onError)	开始下载，返回 DownloadHandle

详细 handler 列表见 @xuqm/rn-common 的 xwebview/ 目录。

已知问题

RN 0.85 Bridgeless 模式下 react-native-blob-util 崩溃

现象：宿主 app 使用 RN 0.85 Bridgeless 模式时，引入 XWebViewView 会触发 XWebViewDownload.ts 中 react-native-blob-util 的模块级初始化，导致 Cannot read property 'getConstants' of null。

根因：react-native-blob-util 目前在 RN 0.85 JSI/TurboModule 路径下 ReactNativeBlobUtil 原生模块为 null，PackageList.java 的旧架构注册方式不足以在 Bridgeless 模式下完成初始化。

临时方案：宿主 app 的 XWebViewContent 直接使用 react-native-webview， 跳过 XWebViewView，功能对等（无下载拦截和 JSBridge，纯内容展示场景够用）。

待修复：

• 升级 react-native-blob-util 到支持 Bridgeless 的版本，或
• 在 XWebViewDownload.ts 中对 ReactNativeBlobUtil 为 null 做防御，延迟到实际下载时才初始化