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

3.8 KiB

原始文件 Blame 文件历史

@xuqm/rn-update

XuqmGroup RN SDK 更新模块。提供 App 整包更新检查和 RN 插件热更新能力。

安装

yarn add @xuqm/rn-update @react-native-async-storage/async-storage

Peer dependencies：react-native >= 0.76，@react-native-async-storage/async-storage >= 1.21.0

快速开始

import { UpdateSDK } from '@xuqm/rn-update'

// 注册插件
UpdateSDK.registerPlugins([
  { moduleId: 'szyx' },
  { moduleId: 'miniapp' },
])

// 注入宿主 BundleRuntime
UpdateSDK.setBundleCallbacks({
  writeBundle: writeBundleFile,
  reloadBundle: loadBundle,
})

// 检查 App 更新
const info = await UpdateSDK.checkAppUpdate()
if (info.needsUpdate) {
  await UpdateSDK.downloadAndInstallApk(info.downloadUrl)
}

// 检查插件更新
const pluginInfo = await UpdateSDK.checkPluginUpdate('szyx')
if (pluginInfo.needsUpdate) {
  await UpdateSDK.updatePlugin('szyx', { onProgress: setProgress })
}

API

插件注册

API	说明
`UpdateSDK.registerPlugins(plugins)`	批量注册插件
`UpdateSDK.registerPlugin(meta)`	单个注册（向后兼容）
`UpdateSDK.setBundleCallbacks(callbacks)`	注入宿主写入/重载能力
`UpdateSDK.getRegisteredPlugins()`	获取已注册插件列表

App 整包更新

API	说明
`UpdateSDK.checkAppUpdate(bypassIgnore?)`	检查 App 更新（30 分钟缓存）
`UpdateSDK.downloadApk(info, options?)`	下载 APK，返回 ArrayBuffer（支持进度回调）
`UpdateSDK.downloadAndInstallApk(url, options?)`	下载 APK 并调起系统安装器（Android）
`UpdateSDK.openStore(appStoreUrl?, marketUrl?)`	跳转应用商店
`UpdateSDK.getAppVersionCode()`	获取当前 versionCode
`UpdateSDK.getAppVersionName()`	获取当前 versionName

插件热更新

API	说明
`UpdateSDK.checkPluginUpdate(moduleId)`	检查插件更新（30 分钟缓存）
`UpdateSDK.downloadPlugin(moduleId, info, options?)`	下载插件 bundle，返回 JS 源码（支持进度回调）
`UpdateSDK.updatePlugin(moduleId, options?)`	一步完成：检查 → 下载 → 写文件 → 重载

类型定义

interface PluginRegistration {
  moduleId: string
}

interface AppUpdateInfo {
  needsUpdate: boolean
  versionName?: string
  versionCode?: number
  downloadUrl?: string
  changeLog?: string
  forceUpdate?: boolean
  appStoreUrl?: string
  marketUrl?: string
  apkHash?: string | null
}

interface PluginUpdateInfo {
  needsUpdate: boolean
  latestVersion: string
  currentVersion: string
  downloadUrl: string
  md5: string
  minCommonVersion: string
  note: string
  forceUpdate?: boolean
}

interface CachedRnBundle {
  moduleId: string
  version: string
  md5: string
  downloadedAt: string
  source: string
}

type UpdateDownloadProgress = {
  bytesDownloaded: number
  totalBytes: number
  /** 0-100 */
  percent: number
}

下载进度回调

downloadApk() 和 downloadPlugin() 支持 onProgress 回调，使用 fetch + ReadableStream 实现流式进度计算：

// 下载 APK 带进度
const buffer = await UpdateSDK.downloadApk(info, {
  onProgress: ({ bytesDownloaded, totalBytes, percent }) => {
    console.log(`下载进度: ${percent}% (${bytesDownloaded}/${totalBytes})`)
  },
})

// 下载插件 bundle 带进度
const source = await UpdateSDK.downloadPlugin('szyx', pluginInfo, {
  onProgress: ({ percent }) => setProgress(percent),
})

工作原理

版本号由 SDK 自动从本地 AsyncStorage 缓存读取，首次为 0.0.0
更新检查结果缓存 30 分钟（TTL），避免频繁请求
updatePlugin() 内部自动完成：checkPluginUpdate → fetch(downloadUrl) → AsyncStorage 缓存 → writeBundle → reloadBundle
silent: true 时跳过 reloadBundle，下次启动生效

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