鸿蒙（HarmonyOS）中文件上传下载

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、功能概述

鸿蒙通过 @ohos.request 模块提供文件上传下载能力，支持以下特性：

• 多任务管理：支持同时处理多个上传/下载任务 
• 断点续传：后台任务自动记录进度，支持暂停后继续 
• 进度监听：实时回调传输进度（约1秒一次） 
• 权限控制：需声明网络权限 ohos.permission.INTERNET 

二、文件上传实现

1. 基础上传方式

方法一：request.uploadFile

import request from '@ohos.request';
import fs from '@ohos.file.fs';

// 1. 创建测试文件
let context = getContext(this) as common.UIAbilityContext;
let file = fs.openSync(context.cacheDir + '/test.txt', fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
fs.writeSync(file.fd, 'Hello HarmonyOS');
fs.closeSync(file);

// 2. 配置上传参数
let uploadConfig = {
  url: 'https://your-server.com/upload',
  method: 'POST',
  files: [
    { 
      filename: 'test.txt', 
      uri: 'internal://cache/test.txt', // 对应cacheDir目录
      type: 'text/plain' 
    }
  ],
  header: { 'Content-Type': 'multipart/form-data' }
};

// 3. 执行上传
request.uploadFile(context, uploadConfig)
  .then((task) => {
    task.on('progress', (progress) => {
      console.log(`进度: ${progress.processed}/${progress.total}`);
    });
    task.on('complete', () => console.log('上传完成'));
  })
  .catch((err) => console.error(`上传失败: ${err.code}`));

特点：简单易用，适合单文件上传

方法二：request.agent（支持后台任务）

let config: request.agent.Config = {
  action: request.agent.Action.UPLOAD,
  url: 'https://your-server.com/upload',
  mode: request.agent.Mode.BACKGROUND, // 后台任务
  files: [{ path: './test.txt' }],
  method: 'POST'
};

request.agent.create(context, config).then((task) => {
  task.on('progress', (p) => console.log(`已上传: ${p.processed}字节`));
  task.start();
});

优势：支持后台运行和断点续传

2. 高级功能

• 分片上传：通过设置 range: [start, end] 实现文件分块传输
• 自定义代理：API 12+ 支持设置代理地址参数 
• 多文件上传：在 files 数组中添加多个文件项 

三、文件下载实现

1. 基础下载方式

let downloadConfig = {
  url: 'https://example.com/file.zip',
  saveas: './', // 保存到应用缓存目录
  overwrite: true, // 覆盖已有文件
  gauge: true    // 启用进度通知
};

request.agent.create(context, {
  ...downloadConfig,
  action: request.agent.Action.DOWNLOAD,
  mode: request.agent.Mode.FOREGROUND
}).then((task) => {
  task.on('completed', () => console.log('下载完成'));
  task.start();
});

注意：

• 前台任务仅支持单文件下载 
• 后台任务 (mode: BACKGROUND) 支持多文件并行下载 

2. 多文件下载监听

// 封装单个下载任务组件
@Component
struct DownloadItem {
  @State progress: number = 0;
  
  build() {
    Row() {
      Text(`进度: ${this.progress}%`)
      Button(this.progress > 0 ? '暂停' : '开始')
        .onClick(() => this.toggleDownload())
    }
  }

  toggleDownload() {
    // 实现任务启动/暂停逻辑
  }
}

// 主页面调用
ForEach(this.downloadList, (item) => {
  DownloadItem({ config: item })
})

关键点：每个任务需独立配置 request.agent.Config 并注册监听

四、文件管理

1. 路径获取

2. 文件操作

// 检查文件是否存在
let exist = fs.accessSync(path); 

// 读取文件内容
let buffer = new ArrayBuffer(1024);
fs.readSync(fd, buffer); 

// 保存到系统相册（需UTS插件）
photoAccessHelper.showAssetsCreationDialog(uri); 

限制：上传仅支持 cacheDir 下的文件

五、注意事项

1. 权限声明

   "requestPermissions": [
     { "name": "ohos.permission.INTERNET" },
     { "name": "ohos.permission.WRITE_IMAGEVIDEO" } // 如需保存到相册
   ]

2. 后台任务限制

   • 最多10个未完成任务 
   • 退出应用后可通过通知栏查看进度

3. 错误处理

   task.on('failed', (err) => {
     console.error(`错误码: ${err.code}`, err.message);
   });

4. 兼容性

   • 需API 10+（部分特性需API 12+） 
   • 仅标准系统支持（如RK3568）

六、完整示例

参考OpenHarmony官方示例：

git clone https://gitee.com/openharmony/applications_app_samples.git
cd code/BasicFeature/Connectivity/UploadAndDownload/

 包含上传下载完整模块化实现。