XuqmGroup 8f0a940830 feat: xwebview handleDownloadRequest + README 更新

- 新增 handleDownloadRequest() 统一下载处理函数
- 导出 download 相关工具函数
- 更新 rn-update 和 rn-xwebview README

Co-Authored-By: Claude <noreply@anthropic.com>

2026-06-16 13:25:46 +08:00

4.0 KiB

原始文件 Blame 文件历史

@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

组件

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 内置文件下载支持，自动拦截以下场景：

URL 以常见下载扩展名结尾（.pdf, .zip, .apk 等）
<a download="..."> 标签点击
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/ 目录。

4.0 KiB 原始文件 Blame 文件历史 Unescape Escape