更新记录

1.0.0（2026-08-03）

• 首发 Android / iOS / HarmonyOS 后台传输 UTS 插件
• 单任务与批量上传下载、断点续传、校验和、去重、分组调度
• 三端原生传输与通知；可选导出到用户 Download
• 通知 open-page 跳转（watchNotificationClick / stopWatcher）
• 修复 HarmonyOS 通知正文点击只拉起应用、不进入 pagesx/list/list：API 12 使用 NotificationKit WantAgent，并监听 EntryAbility 冷/热启动 Want 派发 open-page 事件
• 修复 HarmonyOS 文件字节已下载完成却被标记失败：公共 Download 不支持静默写入时保持任务 completed，手动 exportFile 改用 DocumentViewPicker 授权保存
• 修复 HarmonyOS API 12 通知发布缺少 notificationContentType，并保留失败任务的 Request Agent 供后续恢复/重试
• API 以 interface.uts 为准；示例见 pages/transfer/、pagesx/transfer/

平台兼容性

uni-app(4.87)

uni-app x(5.0)

XView 后台文件传输（xview-transfer）

面向 uni-app 与 uni-app x 的 Android、iOS、HarmonyOS 三端原生后台文件传输 UTS 插件。公共 API 以 utssdk/interface.uts 为准；不支持 Web 或小程序，未支持端不伪造成功。

功能特性

• 单任务传输：后台 HTTP/HTTPS 下载与上传，支持暂停、恢复、取消、失败重试
• 批量分组：startBatchDownload / startBatchUpload，组级暂停/恢复/取消/删除
• 进度与状态：watchTasks / watchGroups；startDownload / startUpload 支持 options 内便捷回调
• 系统通知：Android/iOS 本地通知（进度与操作按钮）；HarmonyOS 使用 NotificationKit 可点击进度通知
• 通知跳转：点击通知正文写入 open-page 事件，由 App 层消费并跳转（插件内不调用 uni.navigateTo）
• 续传与校验：下载 HTTP Range；上传 HTTP Content-Range（需服务端配合）；可选 MD5/SHA256
• 去重与持久化：默认同 URL/路径去重；任务快照跨进程持久化
• Download 导出：传输成功后可选复制副本到用户可访问目录，不覆盖同名文件

集成步骤

1. 将 uni_modules/xview-transfer 放入项目 uni_modules 目录。
2. App.onLaunch 调用 initTransfer()，并配置通知 open-page（见下文）。
3. 传输前调用 requestNotificationPermission() 申请或检查通知权限。
4. 使用 startDownload / startUpload 或批量 API 创建任务；通过 errCode === 0 判断成败。

import { initTransfer, requestNotificationPermission, startDownload } from '@/uni_modules/xview-transfer'

initTransfer()

const permission = await requestNotificationPermission()
if (!permission.granted) {
  console.warn('通知未授权', permission.errMsg)
}

const result = await startDownload({
  url: 'https://example.com/files/report.pdf',
  notificationTitle: '下载报告',
  exportToDownloads: true,
  : (event) => {
    console.log('progress', event.task.progress, event.task.bytesTransferred)
  }
})

if (result.errCode !== 0 || result.task == null) {
  console.error(result.errCode, result.errMsg)
} else {
  console.log('taskId', result.task.taskId)
}

任务状态

progress 为 -1 表示服务端未提供总长度，页面应显示「不确定进度」。canResume 为 false 时，resumeTask 可能从头重新开始，不会假装沿用旧偏移。

API 一览

异步任务 API 均返回 Promise，不会 throw；通过 errCode / errMsg 判断成败（errCode === 0 为成功）。完整类型见 utssdk/interface.uts。

跨端纯逻辑工具

由三端 index.uts 再导出，逻辑与 shared.uts 一致。uni-app .vue 示例请使用 pages/utils/transfer-helpers.js，避免 Android 自定义基座对纯函数生成 ByJs 桥接异常。

常用参数

XviewDownloadOptions 必填 url；可选 destinationPath、headers、exportToDownloads、expectedChecksum、checksumAlgorithm、dedupe、onProgress、onStateChange 等。

XviewUploadOptions 必填 url、sourcePath；可选 method（默认 PUT）、resumable（默认 true）、mimeType 等。

XviewBatchDownloadOptions / XviewBatchUploadOptions 必填 items；可选 groupId、sequential、maxConcurrent、onGroupProgress、onGroupStateChange 等。

XviewTransferConfig 默认值：

任务快照 XviewTransferTask、返回值 XviewTransferResult / XviewTransferBatchResult / XviewTransferGroupResult 等完整字段定义见 utssdk/interface.uts。

通知正文 open-page

Android/iOS 传输通知的动作按钮为暂停/继续/取消；Android、iOS、HarmonyOS 的通知正文点击都会写入 open-page 事件，由 App 在 onShow 消费并跳转。

HarmonyOS API 12 的 Request Agent gauge 不能配置点击 WantAgent，因此 Harmony 端由插件发布可点击的进度通知，并通过 EntryAbility onCreate/onNewWant 覆盖冷启动与热启动点击。拒绝通知权限不会中断后台传输，但不会显示这条可点击通知。

import {
  setupNotificationApp,
  pollNotificationApp,
  drainPendingNavigateUrl
} from '@/pages/utils/notification.js' // uni-app x：@/pagesx/utils/notification.uts

const LIST_PATH = '/pages/list/list' // uni-app x：/pagesx/list/list

// App.onLaunch
setupNotificationApp(LIST_PATH)

// App.onShow
pollNotificationApp(LIST_PATH)
const url = drainPendingNavigateUrl()
if (url.length > 0) {
  uni.navigateTo({ url, fail: () => uni.reLaunch({ url }) })
}

底层 API：setNotificationOpenPage、watchNotificationClick、consumeNotificationClick；取消监听统一使用 stopWatcher(watcherId)。

onProgress / onStateChange 与 watchTasks 回调经内部 keepAlive watcher 派发；任务进入终态后便捷回调自动释放。页面可在卸载时调用 stopWatcher(callbackWatcherId) 提前释放。

存储、权限与隐私

exportToDownloads 导出副本，不移动或删除应用内源文件。HarmonyOS 普通应用不能在后台静默写公共 Download；即使传入 exportToDownloads: true，传输也会先以应用私有文件完成，不会因公共目录不可用而标记失败。需要在应用前台由用户操作 exportFile(taskId)，系统文件选择器授权成功后 task.exportedPath 返回 URI。其他平台仍按完成后自动导出处理；未导出时 task.exportedPath 为空字符串（Android 10+ 可能为 content:// URI）。

插件声明权限见 package.json → dcloudext.declaration.permissions。传输只向调用方指定的 HTTP/HTTPS 地址发送调用方指定的文件；勿将 Authorization 等令牌写入 notificationDescription 或日志。

错误码

需要 UniError 语义时可使用 utssdk/unierror.uts 中的 XviewTransferFailImpl。