HarmonyOS 鸿蒙Next中如何实现不阻塞主线程的下载操作

使用 TaskPool配合request.downloadFile。

taskPool适合IO密集型。如果资源有限，大于API 18 还可以用AsyncRunner可以控制并发数量。

request.downloadFile鸿蒙原生支持后台、并发、进度、断点等。

import { common } from '@kit.AbilityKit';
import { request } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { taskpool } from '@kit.ArkTS';

// 必须用 @Concurrent ，才能被 TaskPool 调度
@Concurrent
async function downloadSingleFile(
  context: common.UIAbilityContext,
  url: string,
  savePath: string
): Promise<string> {
  return new Promise(async (resolve, reject) => {
    try {
      // 确保目录存在
      const dir = savePath.substring(0, savePath.lastIndexOf('/'));
      await fileIo.mkdir(dir, true);

      // 下载配置
      const config: request.DownloadConfig = {
        url: url,
        filePath: savePath,
        enableMetered: true,
        enableRoaming: true
      };

      // 发起下载
      const task = await request.downloadFile(context, config);

      // 监听完成/失败
      task.on('complete', () => {
        task.off('complete');
        task.off('fail');
        resolve(savePath);
      });

      task.on('fail', (err) => {
        task.off('complete');
        task.off('fail');
        reject(new Error(`Download fail: ${err}`));
      });

    } catch (e) {
      reject(e);
    }
  });
}

@Entry
@Component
struct Index {
  @State progressText: string = '准备开始';
  context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

  // 多个文件 URL
  private urls: string[] = [
    'https://xx.com/file1.xx',
    'https://xx.com/file2.xx',
    'https://xx.com/file3.xx'
  ];

  // 多线程批量下载
  async downloadFiles() {
    this.progressText = '多线程下载中...';

    // 控制并发数量
    @Available({ minApiVersion: 'OpenHarmony 18' })
    let asyncRunner: taskpool.AsyncRunner = new taskpool.AsyncRunner(2);

    for (let i = 0; i < this.urls.length; i++) {
      const url = this.urls[i];
      const fileName = `file_${i}.xxx`;
      const savePath = `${this.context.filesDir}/fdownload/${fileName}`;

      // 提交到 TaskPool 并发执行
      const task: taskpool.Task = new taskpool.Task(downloadSingleFile,this.context, url, savePath);
      if (deviceInfo.sdkApiVersion >= 18) {
        asyncRunner.execute(task).catch(() => {
          // TODO: Implement error handling.
        });
      } else {
        // Fallback to an earlier version
        taskpool.execute(task).catch(() => {
          // TODO: Implement error handling.
        });
      }
    }
  }

  build() {
    Column() {
      Button('开始下载')
        .margin(20)
        .onClick(() => {
          this.downloadFiles();
        });

      Text(this.progressText)
        .fontSize(14)
        .margin(10)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

根据自己项目实际改改。优化的时候可以研究下这个多线程并发，希望帮到你。

HarmonyOS Next 中推荐直接使用系统下载能力，无需依赖第三方库。系统 API @ohos.request 支持创建下载任务，任务在独立线程中异步执行，完全不阻塞主线程。

核心示例代码如下：

import request from '@ohos.request';
import { BusinessError } from '@ohos.base';

// 配置下载任务
let config: request.DownloadConfig = {
  url: 'https://example.com/file.zip',            // 下载地址
  filePath: getContext().filesDir + '/file.zip',  // 必须用应用沙箱路径
  enableMetered: true,                           // 允许移动网络下载
  enableRoaming: true                            // 允许漫游下载
};

try {
  // 创建并启动下载任务，整个过程异步
  request.downloadFile(getContext(), config)
    .then((task: request.DownloadTask) => {
      task.on('progress', (receivedSize, totalSize) => {
        console.info(`进度: ${receivedSize}/${totalSize}`);
      });
      task.on('complete', () => {
        console.info('下载完成');
      });
      task.on('fail', (errCode: number, errMsg: string) => {
        console.error(`下载失败: ${errCode} ${errMsg}`);
      });
    }).catch((err: BusinessError) => {
      console.error('创建任务失败: ' + err.message);
    });
} catch (err) {
  console.error('配置异常: ' + JSON.stringify(err));
}

为什么 TaskPool / Worker 可能失败？

• TaskPool 引擎对部分系统能力上下文有严格限制，某些第三方库或涉及沙箱路径的操作可能不被支持。
• Worker 自身有独立沙箱，直接传入主线程的文件路径可能因权限隔离导致无法访问。必须通过 workerPort.postMessage 传递应用沙箱路径（如 context.filesDir 拼接路径），且需要提前确认 Worker 对该路径有读写权限。

综上，直接采用系统下载 API 是最简洁、稳定的非阻塞方案。