大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在应用开发中,文件下载是一个非常基础但又极易被低估的场景。如果只是拉取一张小图片或一段轻量级 JSON 数据,普通的 HTTP 请求完全可以胜任。但如果面对的是几百兆甚至上 G 的视频文件、安装包或离线资源,普通的 HTTP 请求往往会显得捉襟见肘。

本文将结合 HarmonyOS 官方的 @ohos.request 模块,通过 request.agent 架构,完整实现一个具备后台下载、暂停、恢复、进度监听以及页面重进后状态恢复的文件下载管理场景。

一、普通 HTTP 请求为什么不等于下载管理

在着手写代码之前,这里比较容易出现一个理解偏差:既然 @ohos.net.http 也能通过流式接收数据(Stream)写入本地,为什么官方还推荐使用 request 模块来进行下载管理?

核心区别在于生命周期与进程归属:

  1. 进程绑定:普通的 HTTP 请求运行在应用的当前进程中。一旦用户将应用退到后台运行,或者应用因内存不足被系统挂起、清理,网络请求就会瞬间中断,下载进度直接丢失。
  2. 系统级服务支持:request.agent 是由底层系统守护进程(Daemon)接管的。当我们将下载任务交给 Agent 后,即使应用页面被销毁,下载任务依然可以在后台继续(依赖于具体配置)。
  3. 原生断点续传:Agent 底层自带了完整的下载状态机,原生提供了 pause()、resume() 等接口,不需要开发者自己去维护 HTTP Header 中的 Range 字段。

二、先把官方规则弄清楚

根据 HarmonyOS API 10 及以上版本的官方文档,使用 request.agent 需要注意以下几个前置条件:

  • API 版本要求:推荐使用 API 10 引入的 request.agent。旧版的 request.downloadFile 接口虽然仍存在,但在并发控制和后台任务管理上不如 agent 强大。

  • 权限申请:由于涉及网络请求,必须在 module.json5 中声明 ohos.permission.INTERNET 权限。

  • 核心类与接口:

    • request.agent.create():创建下载任务配置。
    • request.agent.Task:任务实例,负责控制任务启停及绑定回调事件。
    • request.agent.search():用于在页面重新进入时,查询历史未完成的任务。
    • request.agent.getTask():通过任务 ID 重新获取任务对象。

三、搭一个最小实践:完整下载流程

接下来,我们用一个最小示例验证这个能力。目标是实现:点击下载 -> 实时查看进度 -> 支持暂停与恢复 -> 下载完成后保存到沙箱 -> 退出页面重进能够继续显示进度。

1. 创建下载任务与配置

按照官方文档提供的接口组织代码。这一步的关键并不是组件本身,而是 request.agent.Config 的正确配置。

import request from '@ohos.request';
import common from '@ohos.app.ability.common';
import fs from '@ohos.file.fs';

export class DownloadManager {
  private static task: request.agent.Task | null = null;
  private static taskId: string = '';

  // 1. 创建并启动下载任务
  static async startDownload(context: common.UIAbilityContext, url: string, fileName: string) {
    // 文件的最终沙箱保存路径
    let savePath = context.filesDir + '/' + fileName;

    let config: request.agent.Config = {
      action: request.agent.Action.DOWNLOAD,
      url: url,
      title: 'resource_download',
      description: 'Downloading a large file',
      mode: request.agent.Mode.BACKGROUND,
      overwrite: true,
      method: 'GET',
      saveas: savePath,
      network: request.agent.Network.ANY
    };

    try {
      this.task = await request.agent.create(context, config);
      this.taskId = this.task.tid; // 记录任务ID,用于后续恢复
      
      // 绑定进度、完成、失败事件
      this.bindTaskEvents(this.task, savePath);

      // 启动任务
      await this.task.start();
      console.info('Download task started successfully.');
    } catch (err) {
      console.error(`Failed to create/start download task. Code: ${err.code}, message: ${err.message}`);
    }
  }
}

2. 绑定进度与状态事件

真正需要关注的是这三个核心事件:progress、completed 和 failed。

  private static bindTaskEvents(task: request.agent.Task, savePath: string) {
    // 监听下载进度
    task.on('progress', (progress: request.agent.Progress) => {
      let current = progress.processed;
      let total = progress.sizes[0];
      let percent = total > 0 ? (current / total * 100).toFixed(2) : 0;
      console.info(`Download progress: ${current}/${total} (${percent}%)`);
      // 实际开发中,这里可以通过 EventHub 或状态管理通知 UI 更新
    });

    // 监听下载完成
    task.on('completed', (progress: request.agent.Progress) => {
      console.info('Download completed!');
      // 下载完成后,使用 fs 模块校验文件
      this.verifyFile(savePath);
    });

    // 监听下载失败
    task.on('failed', (progress: request.agent.Progress) => {
      console.error('Download failed.');
    });
  }

3. 暂停与恢复控制

有了 task 对象,暂停和恢复只需要调用对应的系统方法:

  static async pauseDownload() {
    if (this.task) {
      await this.task.pause();
      console.info('Download paused.');
    }
  }

  static async resumeDownload() {
    if (this.task) {
      await this.task.resume();
      console.info('Download resumed.');
    }
  }

四、几个关键点拆开看

1. 页面重进后恢复任务显示

如果用户在下载中途退出了当前页面(甚至清除了应用后台,只要系统任务还在),重新进入页面时,原有的 this.task 变量已经为空。如果直接按照普通页面的逻辑处理,进度条就会归零。

这里必须通过 request.agent.search 查询正在进行的任务,并重新接管:

  // 恢复之前的未完成任务
  static async restoreTask(context: common.UIAbilityContext) {
    try {
      // 查询处于特定状态的下载任务
      let filters: request.agent.Filter = {
        action: request.agent.Action.DOWNLOAD,
        state: request.agent.State.RUNNING // 也可以加入 PAUSED 状态
      };
      
      let tids = await request.agent.search(context, filters);
      
      if (tids && tids.length > 0) {
        // 假设我们只接管第一个任务
        let tid = tids[0];
        this.task = await request.agent.getTask(context, tid);
        this.taskId = tid;
        
        // 重新绑定事件以恢复 UI 更新
        // 注意:实际开发中需重新推导 savePath
        this.bindTaskEvents(this.task, context.filesDir + '/sample_video.mp4');
        console.info(`Successfully restored task: ${tid}`);
      }
    } catch (err) {
      console.error(`Failed to search/restore tasks. Code: ${err.code}`);
    }
  }

2. 下载完成后 fileIo (fs) 管理文件

官方的 request 模块只负责把数据拉下来并写入指定的沙箱路径。业务逻辑往往还需要验证文件大小、将其移动到指定目录或进行解压。此时需要介入 @ohos.file.fs(API 9+ 替代了原有的 fileIo)。

  private static verifyFile(filePath: string) {
    try {
      let stat = fs.statSync(filePath);
      console.info(`File successfully saved. Size: ${stat.size} bytes`);
      
      // 如果需要重命名或移动,可以直接调用 fs API
      // fs.renameSync(filePath, newFilePath);
    } catch (err) {
      console.error(`File verification failed: ${err.message}`);
    }
  }

3. 移除任务对象

这个地方值得单独注意:completed 触发后,任务本身已经在本地持久化记录了。为了避免系统数据库中堆积过多无效的下载记录,或者导致后续同名文件下载冲突,在确认业务完全结束后,应当主动清理任务。

  static async clearTask(context: common.UIAbilityContext) {
    if (this.taskId) {
      try {
        await request.agent.remove(context, this.taskId);
        this.task = null;
        this.taskId = '';
        console.info('Task removed from agent system.');
      } catch (err) {
        console.error(`Failed to remove task. Code: ${err.code}`);
      }
    }
  }

五、容易踩坑的地方

根据官方接口约束和实际开发反馈,这里有几个很容易出现理解偏差的限制:

  1. saveas 的路径权限:
    在 Config 中配置的 saveas 路径,不能随意指向任意的系统公共目录。它必须是当前应用沙箱内的路径(例如 context.filesDir 或 context.cacheDir)。如果配置了一个无权访问的路径,任务在 create 阶段就会直接报错。
  2. 事件监听的内存泄漏:
    task.on() 绑定事件后,如果在页面销毁(aboutToDisappear)时不调用 task.off() 取消绑定,反复进入页面可能会导致多个回调同时触发,引发内存泄漏或 UI 更新错乱。
  3. 状态机的严格校验:
    不能对一个已经处于 COMPLETED 状态的任务调用 pause(),同样不能对 RUNNING 状态的任务调用 start()。每次调用控制流接口前,最好通过 task.show() 获取一下最新的 request.agent.TaskInfo 状态,否则会抛出业务逻辑异常。

六、实际项目中怎么排查

如果在开发中发现下载无法启动或进度不动,建议整理成这样的排查顺序:

  1. 先看权限与网络:确认设备是否联网,module.json5 中是否有 ohos.permission.INTERNET。
  2. 再看路径配置:检查 saveas 是否指向了正确的、且有写入权限的沙箱路径(可以先打个 Log 看一下拼接后的 absolute path)。
  3. 观察控制台异常回调:重点关注 failed 事件中的 err.code,系统常常会在其中返回网络超时或空间不足的具体原因。
  4. 最后检查生命周期:如果只有退后台回来后看不到进度,优先检查页面 aboutToAppear 生命周期中,是否正确执行了 request.agent.search() 并成功获取到了历史 tid。

七、开发经验总结

使用 @ohos.request.agent 实现下载管理,不仅让代码脱离了脆弱的应用进程限制,更赋予了应用原生级别的断点续传能力。总结一下核心逻辑:

  1. 用 agent.create 创建基于后台模式(BACKGROUND)的下载任务。
  2. 及时通过 taskId 把控任务状态,利用 on('progress') 驱动 UI。
  3. 页面重载时,不要重新创建,而是通过 agent.search 和 agent.getTask 接管老任务。
  4. 业务收尾时,结合 @ohos.file.fs 校验成果,并用 agent.remove 释放系统资源。

如果你正在开发类似的应用商店、游戏启动器或大型附件阅览类 App,可以重点观察一下自己的下载队列是否做了页面异常退出后的状态恢复,这类问题往往比单纯跑通下载流程更影响用户的实际体验。

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐