文档首页/ 对象存储服务 OBS/ SDK参考/ Harmony（公测）/ 对象相关接口(HarmonyOS SDK)/ 基础操作/ 进度回调(HarmonyOS SDK)
更新时间：2026-08-28 GMT+08:00
查看PDF
分享

进度回调(HarmonyOS SDK)

功能说明

进度回调是 SDK 本地能力：应用在上传或下载接口的入参中设置 ProgressCallback 回调函数，SDK 在数据传输过程中按已传字节数调用该函数，应用据此刷新界面进度。回调函数仅上报已传字节数等进度信息，不干预主传输流程。回调失败不影响主数据传输，SDK 捕获并忽略回调异常。

方法定义

ProgressCallback 是一个函数类型的参数,不是独立接口，而是putObject/getObject/uploadFile/downloadFile 等上传下载接口共用的入参。

1
2
3
4
5
 
type ProgressCallback = (
  transferredAmount: number,
  totalAmount: number,
  totalSeconds: number,
) => void;

参数说明

表1 ProgressCallback 参数

参数名称

参数类型

是否必选

描述

transferredAmount

number

必选

参数解释：

本次请求已传输的字节数。上传为已上传字节数,下载为已接收字节数，从0累计至totalAmount。

totalAmount

number

必选

参数解释：

本次请求待传输的总字节数。上传为请求体大小,下载为响应体大小。

totalSeconds

number

必选

参数解释：

本次请求从开始传输到本次回调时刻的耗时，单位秒，用于计算传输速率。
表2 覆盖接口

接口

覆盖方向

说明

putObject

上传进度

上传对象时按已上传字节数回调，覆盖单次上传全程进度。

getObject

下载进度

文件下载（SaveFilePath 落盘）时按已接收字节数回调，覆盖单次下载全程进度。

uploadFile

上传进度

断点续传上传时按各段已上传字节数累加回调，覆盖分段上传全程进度。

downloadFile

下载进度

断点续传下载时按各段已下载字节数累加回调，覆盖分段下载全程进度。

代码示例-上传进度

本示例在上传对象时设置 ProgressCallback,按已传输字节数刷新进度。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
// 引入依赖包
import ObsClient, { PutObjectInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const processManager = new process.ProcessManager();

// 创建ObsClient实例
const obsClient = new ObsClient({
  // 推荐通过环境变量获取AKSK,这里也可以使用其他外部引入方式传入,如果使用硬编码可能会存在泄露风险
  // 您可以登录访问管理控制台获取访问密钥AK/SK,获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
  AccessKeyId: processManager.getEnvironmentVar("ACCESS_KEY_ID"),
  SecretAccessKey: processManager.getEnvironmentVar("SECRET_ACCESS_KEY"),
  // 【可选】如果使用临时AK/SK和SecurityToken访问OBS,同样建议您尽量避免使用硬编码,以降低信息泄露风险。您可以通过环境变量获取访问密钥AK/SK,也可以使用其他外部引入方式传入。
  // SecurityToken: processManager.getEnvironmentVar("SECURITY_TOKEN"),
  // Server填写Bucket对应的Endpoint, 这里以华北-北京四为例,其他地区请按实际情况填写。
  Server: "https://obs.cn-north-4.myhuaweicloud.com",
});

async function putObject() {
  try {
    const params: PutObjectInput = {
      // 指定存储桶名称
      Bucket: "examplebucket",
      // 指定对象,此处以 example/objectname 为例
      Key: "example/objectname",
      // 指定上传内容
      Body: 'Hello OBS',
      ProgressCallback: (transferred, total, seconds) => {
        const percent = total > 0 ? Math.round(transferred / total * 100) : 0;
        hilog.info(0x0001, 'OBS-Harmony', "progress: %d%% (%d bytes, %ds)", percent, transferred, seconds);
      },
    };
    // 上传对象
    const result = await obsClient.putObject(params);
    if (result.CommonMsg.Status < 300) {
      hilog.info(0x0001, 'OBS-Harmony', "Put object(%s) under the bucket(%s) successful!!", params.Key, params.Bucket);
      hilog.info(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
      hilog.info(0x0001, 'OBS-Harmony', "StorageClass:%s, ETag:%s", result.InterfaceResult.StorageClass, result.InterfaceResult.ETag);
      return;
    }
    hilog.error(0x0001, 'OBS-Harmony', "An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    hilog.error(0x0001, 'OBS-Harmony', "Status: %d", result.CommonMsg.Status);
    hilog.error(0x0001, 'OBS-Harmony', "Code: %s", result.CommonMsg.Code);
    hilog.error(0x0001, 'OBS-Harmony', "Message: %s", result.CommonMsg.Message);
    hilog.error(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    const err = error as BusinessError;
    hilog.error(0x0001, 'OBS-Harmony', 'An Exception occurred: code=%d, message: %s', err.code, err.message);
  }
}

putObject();

相关链接

父主题： 基础操作

相关文档