更新记录

1.0.3（2026-06-07）

优化

1.0.2（2026-06-06）

优化

1.0.1（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,
    showNotification: false
})

Demo 页面

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

• pages/demo/background-download.uvue

首页入口：

• pages/index/index.uvue

这个 Demo 演示了：

• 创建下载任务
• 监听下载进度
• 监听状态变化
• 暂停当前任务
• 恢复当前任务
• 取消当前任务
• 查询全部任务
• Android 通知栏默认开关联调
• Android 通知权限状态检测、权限申请、系统设置跳转
• Harmony 通知显示开关联调
• iOS 完成/失败结果通知开关联调

Demo 联调说明

pages/demo/background-download.uvue 中已经把三端通知相关能力拆成可直接点击验证的按钮。

• Android：可切换默认通知栏开关，对应 setAndroidNotificationEnabled() / getAndroidNotificationEnabled()
• Android：可刷新通知权限状态、申请 POST_NOTIFICATIONS、跳转系统权限设置页
• Harmony：可切换默认通知显示开关，对应 setHarmonyNotificationEnabled() / getHarmonyNotificationEnabled()
• Harmony：可主动请求一次通知授权，对应 requestHarmonyNotificationPermission()；可读取当前通知权限状态，对应 isHarmonyNotificationPermissionEnabled()
• iOS：可切换完成/失败结果通知开关，对应 setIOSResultNotificationEnabled() / getIOSResultNotificationEnabled()

注意：

• Android / Harmony 的 showNotification 用于控制下载任务是否显示通知栏或后台提示
• iOS 不显示 Android 式常驻通知栏，setIOSResultNotificationEnabled() 只控制下载完成或失败时的本地通知
• Demo 中点击“开始下载”时，Android 与 Harmony 会自动带上当前平台对应的 showNotification 值
• Android 运行时通知权限依赖 targetSdkVersion >= 33。本项目已在 manifest.json 中配置 35，但调试基座或历史安装包如果未更新到对应目标版本，点击申请时仍可能不会弹系统框，此时请直接使用“打开系统权限设置”验证
• Harmony 当前会优先调用系统通知授权申请能力；通常首次申请时系统可能弹框，若用户已经同意或拒绝，后续往往不会重复弹框，此时只能引导用户去系统设置确认

核心类型

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,
    showNotification: false
})

通知相关配置

setAndroidNotificationEnabled(enabled)

设置 Android 端默认是否显示通知栏。

签名：

setAndroidNotificationEnabled(enabled: boolean): void

说明：

• 默认值为 false
• 仅当单次 start() 未显式传 showNotification 时生效
• 适合在页面初始化时统一配置 Android 下载任务是否默认显示通知栏

getAndroidNotificationEnabled()

读取 Android 端默认通知栏开关。

签名：

getAndroidNotificationEnabled(): boolean

作用：

• 读取当前 Android 端默认通知栏开关状态
• 适合在页面加载时回填开关 UI

setHarmonyNotificationEnabled(enabled)

设置 Harmony 端默认是否显示通知栏/后台运行提示。

签名：

setHarmonyNotificationEnabled(enabled: boolean): void

说明：

• 默认值为 false
• 仅当单次 start() 未显式传 showNotification 时生效
• 用于控制 Harmony 端后台下载是否默认显示通知栏或后台运行提示

getHarmonyNotificationEnabled()

读取 Harmony 端默认通知栏开关。

签名：

getHarmonyNotificationEnabled(): boolean

作用：

• 读取当前 Harmony 端默认通知显示开关状态
• 适合在页面加载时回填开关 UI

setIOSResultNotificationEnabled(enabled)

设置 iOS 端完成/失败本地通知开关。

签名：

setIOSResultNotificationEnabled(enabled: boolean): void

说明：

• 默认值为 false
• 仅在下载完成或下载失败时发送本地通知
• 不会对进度、暂停、取消发送通知
• 适合在业务侧给用户一个“下载完成提醒我”的显式开关

getIOSResultNotificationEnabled()

读取 iOS 端完成/失败本地通知开关。

签名：

getIOSResultNotificationEnabled(): boolean

作用：

• 读取当前 iOS 结果通知开关状态
• 适合在页面加载时回填开关 UI

签名：

getIOSResultNotificationEnabled(): boolean

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,
    showNotification: false,
})

console.log(task)

平台特别说明

Android

• 走原生后台下载链路
• 默认不显示通知栏
• 可通过 setAndroidNotificationEnabled(true) 设置 Android 默认显示通知栏
• 也可在单次 start() 时传 showNotification: true 覆盖默认值
• 如需验证完整原生能力，建议使用自定义基座
• 建议服务端支持 Range，恢复下载更稳定

iOS

• 走系统后台下载能力
• 不支持 Android 那种常驻通知栏进度
• 可通过 setIOSResultNotificationEnabled(true) 开启下载完成/失败本地通知
• 建议使用稳定文件地址，不要依赖临时跳转链接

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"
                }
            }
        ]
    }
}

插件内部已经处理：

• showNotification=true 时启动后台运行显示逻辑
• 可通过 setHarmonyNotificationEnabled(true) 设置 Harmony 默认显示通知栏

但如果入口 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 真机联调和标准基座表现不一致？

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