更新记录

1.0.0（2026-06-05）

初始化

平台兼容性

uni-app(4.23)

uni-app x(4.25)

其他

xtf-downloadtask

xtf-downloadtask 是一个 App 端后台下载插件，适用于 uni-app 和 uni-app x。插件统一提供下载任务的创建、暂停、恢复、取消、查询，以及进度/状态回调能力，适合需要稳定后台下载和任务管理的业务场景。

平台支持

适用场景

• 大文件下载
• 应用切后台后继续下载
• 需要任务暂停与恢复
• 需要在页面中展示下载进度和任务状态

导出内容

• BackgroundDownloader
• BackgroundDownloadRequest
• BackgroundDownloadTask
• BackgroundDownloadList

快速开始

uni-app x

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'

const downloader = new BackgroundDownloader()

uni-app

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'

const downloader = new BackgroundDownloader()

启动一个下载任务

const task = downloader.start({
    taskId: `task-${Date.now()}`,
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'demo.bin',
    directory: 'downloads/background-demo',
    headers: null
})

Demo 页面

当前示例工程已经提供完整联调页面：

• pages/demo/background-download.uvue

首页入口：

• pages/index/index.uvue

这个 Demo 演示了：

• 创建下载任务
• 监听下载进度
• 监听状态变化
• 暂停当前任务
• 恢复当前任务
• 取消当前任务
• 查询全部任务

核心类型

BackgroundDownloadRequest

发起下载时传入的请求对象。

BackgroundDownloadTask

下载任务对象，用于页面展示和业务状态判断。

BackgroundDownloadTaskState

任务状态枚举：

• idle：初始状态
• queued：已入队，等待执行
• running：下载中
• pausing：正在暂停
• paused：已暂停
• pause_failed：暂停失败
• completed：下载完成
• failed：下载失败
• canceled：任务已取消

API 详细说明

new BackgroundDownloader()

创建下载器实例。

作用：

• 初始化插件内部下载环境
• 建立和原生下载实现的桥接
• 为当前页面或模块准备任务操作入口

使用建议：

• 一个页面内通常保留一个实例即可
• 如果页面需要监听回调，建议在页面生命周期内创建并复用同一个实例

示例：

const downloader = new BackgroundDownloader()

start(request)

启动一个后台下载任务。

签名：

start(request: BackgroundDownloadRequest): BackgroundDownloadTask | null

作用：

• 按传入参数创建下载任务
• 将任务交给对应平台的原生后台下载通道处理
• 立即返回当前任务快照，供页面展示

返回值：

• 成功时返回 BackgroundDownloadTask
• 启动失败或参数不合法时返回 null

适用时机：

• 用户点击“开始下载”按钮时
• 页面恢复后需要重建某个下载任务时

示例：

const task = downloader.start({
    taskId: 'file-001',
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'file-001.bin',
    directory: 'downloads/demo',
    headers: null
})

pause(taskId)

暂停指定任务。

签名：

pause(taskId: string): boolean

作用：

• 请求原生层暂停对应任务
• 保留当前已下载进度，便于后续恢复

返回值：

• true：已成功发起暂停请求
• false：任务不存在，或当前状态不允许暂停

适用时机：

• 用户手动暂停下载
• 弱网环境下临时停止下载

resume(taskId)

恢复已暂停任务。

签名：

resume(taskId: string): BackgroundDownloadTask | null

作用：

• 继续下载已暂停的任务
• 如果服务端支持 Range，通常会从断点继续下载

返回值：

• 成功时返回最新任务对象
• 恢复失败时返回 null

适用时机：

• 用户点击“继续下载”
• 网络恢复后重启任务

cancel(taskId)

取消指定任务。

签名：

cancel(taskId: string): boolean

作用：

• 终止下载任务
• 该任务后续不再继续执行

返回值：

• true：已成功发起取消请求
• false：任务不存在，或取消失败

适用时机：

• 用户明确放弃下载
• 当前任务参数失效，需要重新创建任务

getTask(taskId)

查询单个任务。

签名：

getTask(taskId: string): BackgroundDownloadTask | null

作用：

• 获取某个任务的最新快照
• 用于页面恢复时还原任务状态

返回值：

• 查到任务时返回任务对象
• 未查到时返回 null

适用时机：

• 页面重新进入时恢复任务信息
• 业务层主动轮询单个任务状态

getAllTasks()

查询全部任务。

签名：

getAllTasks(): BackgroundDownloadList

作用：

• 返回当前插件维护的全部下载任务
• 用于渲染任务列表、调试状态、恢复历史任务

返回值：

• BackgroundDownloadList，本质是任务数组

适用时机：

• 页面初始化时刷新列表
• 收到进度/状态回调后重刷任务面板

onProgress(callback)

监听任务进度回调。

签名：

onProgress(callback: (task: BackgroundDownloadTask) => void): void

作用：

• 在下载进度变化时回调最新任务对象
• 可直接用于更新 UI 进度条、百分比文本、速率估算

回调参数：

• task：当前进度对应的任务对象

适用时机：

• 页面需要实时展示下载进度时
• 业务层需要记录下载过程时

示例：

downloader.onProgress((task) => {
    console.log('progress', task.taskId, task.progress)
})

onStateChange(callback)

监听任务状态变化回调。

签名：

onStateChange(callback: (task: BackgroundDownloadTask) => void): void

作用：

• 在任务状态发生变化时回调
• 可用于刷新状态标签、提示用户失败原因、切换操作按钮

回调常见场景：

• queued -> running
• running -> paused
• running -> completed
• running -> failed

示例：

downloader.onStateChange((task) => {
    console.log('state', task.taskId, task.status)
})

clearCallbacks()

清理已注册的进度与状态回调。

签名：

clearCallbacks(): void

作用：

• 解除当前页面对原生回调的监听
• 避免页面销毁后仍继续更新已失效页面

适用时机：

• 页面 onUnmounted / onUnload 时
• 当前页面切换监听对象时

示例：

downloader.clearCallbacks()

推荐调用顺序

典型页面调用流程：

1. 创建 BackgroundDownloader 实例
2. 注册 onProgress 和 onStateChange
3. 调用 getAllTasks() 恢复页面已有任务
4. 用户触发 start() 创建新任务
5. 根据任务 ID 调用 pause() / resume() / cancel()
6. 页面销毁时调用 clearCallbacks()

uni-app x 页面示例

import {
    BackgroundDownloadTask,
    BackgroundDownloader
} from '@/uni_modules/xtf-downloadtask'

const downloader = new BackgroundDownloader()

downloader.onProgress(function(task: BackgroundDownloadTask) {
    console.log(task.progress)
})

downloader.onStateChange(function(task: BackgroundDownloadTask) {
    console.log(task.status)
})

uni-app 页面示例

import { BackgroundDownloader } from '@/uni_modules/xtf-downloadtask'

const downloader = new BackgroundDownloader()

const task = downloader.start({
    taskId: `task-${Date.now()}`,
    url: 'https://speed.cloudflare.com/__down?bytes=1048576',
    fileName: 'demo.bin',
    directory: 'downloads/background-demo',
    headers: null,
})

console.log(task)

平台特别说明

Android

• 走原生后台下载链路
• 如需验证完整原生能力，建议使用自定义基座
• 建议服务端支持 Range，恢复下载更稳定

iOS

• 走系统后台下载能力
• 建议使用稳定文件地址，不要依赖临时跳转链接

Harmony

Harmony 项目除安装插件外，还需要在项目根目录维护：

harmony-configs/entry/src/main/module.json5

至少需要确保 EntryAbility 具备后台传输能力与权限声明：

{
    "module": {
        "abilities": [
            {
                "name": "EntryAbility",
                "backgroundModes": ["dataTransfer"]
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
                "reason": "$string:EntryAbility_label",
                "usedScene": {
                    "when": "always"
                }
            }
        ]
    }
}

插件内部已经处理：

• 启动后台任务前检查权限
• 未授权时自动申请 KEEP_BACKGROUND_RUNNING

但如果入口 EntryAbility 没有配置 backgroundModes，startBackgroundRunning 仍然可能失败。

使用建议

• taskId 请由业务层保证唯一
• 页面展示进度时建议使用 progress * 100 转成百分比
• 如果需要恢复历史任务，页面初始化时先调用 getAllTasks()
• 如果业务要支持继续下载，服务端最好提供 Content-Length 和 Range
• 页面销毁前记得 clearCallbacks()，避免无效页面继续收到回调

常见问题

1. 为什么任务能创建，但页面没有进度更新？

通常是因为没有注册 onProgress，或者页面离开后没有重新绑定回调。

2. 为什么恢复下载失败？

常见原因：

• 任务 ID 不存在
• 任务并不处于可恢复状态
• 服务端不支持断点续传

3. 为什么 Harmony 会启动后台任务失败？

优先检查：

• harmony-configs/entry/src/main/module.json5 是否配置了 backgroundModes
• 是否声明了 ohos.permission.KEEP_BACKGROUND_RUNNING
• 用户是否拒绝了后台持续运行权限

4. 为什么 Android 真机联调和标准基座表现不一致？

因为插件依赖原生配置，标准基座下原生依赖能力可能不完全生效，建议使用自定义基座验证。