@ohos.request (上传下载)

request部件主要给应用提供上传下载文件、后台传输代理的基础能力。

说明：

本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import request from '@ohos.request';

限制与约束

在开发FA模型下的应用程序时, 默认支持https，如果要支持http，需要在config.json里增加network标签，属性标识 "cleartextTraffic": true。即：

var config = {
  "deviceConfig": {
    "default": {
      "network": {
        "cleartextTraffic": true
      }
      //...
    }
  }
}

1
2
3
4
5
6
7
8
9
10

在开发stage模型下的应用程序时，不涉及属性标识 "cleartextTraffic"。

下载服务器需要支持HTTP协议的head方法，能够通过Content-length获取下载数据大小，否则下载任务失败，可通过on('fail')⁷⁺查看失败原因。

上传目前仅支持HTTP请求，不支持HTTPS。

常量

需要权限：ohos.permission.INTERNET

系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。

网络类型

下载支持自定义网络类型，可以在DownloadConfig中通过networkType配置成以下网络类型。

名称	参数类型	数值	说明
NETWORK_MOBILE	number	0x00000001	使用蜂窝网络时允许下载的位标志。
NETWORK_WIFI	number	0x00010000	使用WLAN时允许下载的位标志。

下载任务的错误码

下载相关on('fail')⁷⁺/off('fail')⁷⁺/getTaskInfo⁹⁺接口可能返回的错误码。

名称	参数类型	数值	说明
ERROR_CANNOT_RESUME⁷⁺	number	0	网络原因导致恢复下载失败。
ERROR_DEVICE_NOT_FOUND⁷⁺	number	1	找不到SD卡等存储设备。
ERROR_FILE_ALREADY_EXISTS⁷⁺	number	2	要下载的文件已存在，下载会话不能覆盖现有文件。
ERROR_FILE_ERROR⁷⁺	number	3	文件操作失败。
ERROR_HTTP_DATA_ERROR⁷⁺	number	4	HTTP传输失败。
ERROR_INSUFFICIENT_SPACE⁷⁺	number	5	存储空间不足。
ERROR_TOO_MANY_REDIRECTS⁷⁺	number	6	网络重定向过多导致的错误。
ERROR_UNHANDLED_HTTP_CODE⁷⁺	number	7	无法识别的HTTP代码。
ERROR_UNKNOWN⁷⁺	number	8	未知错误。
ERROR_OFFLINE⁹⁺	number	9	网络未连接。
ERROR_UNSUPPORTED_NETWORK_TYPE⁹⁺	number	10	网络类型不匹配。

下载任务暂停原因

下载相关getTaskInfo⁹⁺接口可能返回的任务暂停原因

名称	参数类型	数值	说明
PAUSED_QUEUED_FOR_WIFI⁷⁺	number	0	下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。
PAUSED_WAITING_FOR_NETWORK⁷⁺	number	1	由于网络问题（例如网络断开）而暂停下载。
PAUSED_WAITING_TO_RETRY⁷⁺	number	2	发生网络错误，将重试下载会话。
PAUSED_BY_USER⁹⁺	number	3	用户暂停会话。
PAUSED_UNKNOWN⁷⁺	number	4	未知原因导致暂停下载。

下载任务状态码

下载相关getTaskInfo⁹⁺接口可能返回的任务状态码

名称	参数类型	数值	说明
SESSION_SUCCESSFUL⁷⁺	number	0	下载会话已完成。
SESSION_RUNNING⁷⁺	number	1	下载会话正在进行中。
SESSION_PENDING⁷⁺	number	2	正在调度下载会话。
SESSION_PAUSED⁷⁺	number	3	下载会话已暂停。
SESSION_FAILED⁷⁺	number	4	下载会话已失败，将不会重试。

request.uploadFile⁹⁺

uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask>

上传，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	UploadConfig	是	上传的配置信息。

返回值：

类型	说明
Promise<UploadTask>	返回上传任务。

错误码： 以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400002	Bad file path.

示例：

let uploadTask;
let uploadConfig = {
  url: 'http://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => {
    uploadTask = data;
  }).catch((err) => {
      console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

request.uploadFile⁹⁺

uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void

上传，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	UploadConfig	是	上传的配置信息。
callback	AsyncCallback<UploadTask>	是	回调函数，异步返回UploadTask对象。

错误码： 以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400002	Bad file path.

示例：

let uploadTask;
let uploadConfig = {
  url: 'http://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => {
    if (err) {
        console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
        return;
    }
    uploadTask = data;
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

request.upload^(deprecated)

upload(config: UploadConfig): Promise<UploadTask>

上传，异步方法，使用promise形式返回结果。

模型约束：此接口仅可在FA模型下使用

说明： 从API Version 9开始不再维护，建议使用request.uploadFile⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
config	UploadConfig	是	上传的配置信息。

返回值：

类型	说明
Promise<UploadTask>	返回上传任务。

示例：

let uploadTask;
let uploadConfig = {
  url: 'http://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig).then((data) => {
    uploadTask = data;
}).catch((err) => {
    console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
})

1
2
3
4
5
6
7
8
9
10
11
12
13

request.upload^(deprecated)

upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void

上传，异步方法，使用callback形式返回结果。

模型约束：此接口仅可在FA模型下使用

说明： 从API Version 9开始不再维护，建议使用request.uploadFile⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
config	UploadConfig	是	上传的配置信息。
callback	AsyncCallback<UploadTask>	是	回调函数，异步返回UploadTask对象。

示例：

let uploadTask;
let uploadConfig = {
  url: 'http://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig, (err, data) => {
    if (err) {
        console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
        return;
    }
    uploadTask = data;
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

UploadTask

上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过request.uploadFile⁹⁺获取，callback形式通过request.uploadFile⁹⁺获取。

on('progress')

on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void

开启上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'progress'（上传的进度信息）。
callback	function	是	上传进度的回调函数。

回调函数的参数

参数名	类型	必填	说明
uploadedSize	number	是	当前已上传文件大小，单位为B。
totalSize	number	是	上传文件的总大小，单位为B。

示例：

uploadTask.on('progress', function callback(uploadedSize, totalSize) {
    console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
}
);

1
2
3
4

on('headerReceive')⁷⁺

on(type: 'headerReceive', callback: (header: object) => void): void

开启上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'headerReceive'（接收响应头）。
callback	function	是	HTTP Response Header事件的回调函数。

回调函数的参数：

参数名	类型	必填	说明
header	object	是	HTTP Response Header。

示例：

uploadTask.on('headerReceive', function callback(headers){   
    console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);

1
2
3
4

on('complete' | 'fail')⁹⁺

on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void;

开启上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。
callback	Callback<Array<TaskState>>	是	上传任务完成或失败的回调函数。

回调函数的参数

参数名	类型	必填	说明
taskstates	Array<TaskState>	是	上传任务返回结果

示例：

uploadTask.on('complete', function callback(taskStates) {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
  }
}
);

uploadTask.on('fail', function callback(taskStates) {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  }
}
);

1
2
3
4
5
6
7
8
9
10
11
12
13

off('progress')

off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void

关闭上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型，取值为'progress'（上传的进度信息）。
callback	function	否	上传任务的回调函数。

回调函数的参数：

参数名	类型	必填	说明
uploadedSize	number	是	当前已上传文件的大小，单位为B。
totalSize	number	是	上传文件的总大小，单位为B。

示例：

uploadTask.off('progress', function callback(uploadedSize, totalSize) {
    console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize);
}
);

1
2
3
4

off('headerReceive')⁷⁺

off(type: 'headerReceive', callback?: (header: object) => void): void

关闭上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型，取值为'headerReceive'（接收响应头）。
callback	function	否	HTTP Response Header事件的回调函数。

回调函数的参数：

参数名	类型	必填	说明
header	object	是	HTTP Response Header。

示例：

uploadTask.off('headerReceive', function callback(headers) {
    console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);

1
2
3
4

off('complete' | 'fail')⁹⁺

off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void;

关闭上传任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。
callback	Callback<Array<TaskState>>	否	上传任务完成或失败的回调函数。

回调函数的参数

参数名	类型	必填	说明
taskstates	Array<TaskState>	是	上传任务返回结果

示例：

uploadTask.off('complete', function callback(taskStates) {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
  }
}
);

uploadTask.off('fail', function callback(taskStates) {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  }
}
);

1
2
3
4
5
6
7
8
9
10
11
12
13

delete⁹⁺

delete(): Promise<boolean>

移除上传的任务，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

返回值：

类型	说明
Promise<boolean>	移除任务是否成功。true：成功，false：不成功。

示例：

uploadTask.delete().then((result) => {
    if (result) {
        console.info('Upload task removed successfully. ');
    } else {
        console.error('Failed to remove the upload task. ');
    }
}).catch((err) => {
    console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});

1
2
3
4
5
6
7
8
9

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

移除上传的任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	移除任务的回调函数。

示例：

uploadTask.delete((err, result) => {
    if (err) {
        console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
        return;
    }
    if (result) {
        console.info('Upload task removed successfully.');
    } else {
        console.error('Failed to remove the upload task.');
    }
});

1
2
3
4
5
6
7
8
9
10
11

remove^(deprecated)

remove(): Promise<boolean>

移除上传的任务，异步方法，使用promise形式返回结果。

说明： 从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

返回值：

类型	说明
Promise<boolean>	移除任务是否成功。true：成功，false：不成功。

示例：

uploadTask.remove().then((result) => {
    if (result) {
        console.info('Upload task removed successfully. ');
    } else {
        console.error('Failed to remove the upload task. ');
    }
}).catch((err) => {
    console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});

1
2
3
4
5
6
7
8
9

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

移除上传的任务，异步方法，使用callback形式返回结果。

说明： 从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	移除任务的回调函数。

示例：

uploadTask.remove((err, result) => {
    if (err) {
        console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
        return;
    }
    if (result) {
        console.info('Upload task removed successfully.');
    } else {
        console.error('Failed to remove the upload task.');
    }
});

1
2
3
4
5
6
7
8
9
10
11

UploadConfig

需要权限：ohos.permission.INTERNET

系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。

名称	类型	必填	说明
url	string	是	资源地址。
header	Object	是	添加要包含在上传请求中的HTTP或HTTPS标志头。
method	string	是	请求方法：POST、PUT。缺省为POST。
files	Array<File>	是	要上传的文件列表。请使用 multipart/form-data提交。
data	Array<RequestData>	是	请求的表单数据。

TaskState⁹⁺

需要权限：ohos.permission.INTERNET

系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。

名称	类型	必填	说明
path	string	是	文件路径
responseCode	number	是	上传任务返回值
message	string	是	上传任务结果描述信息

File

需要权限：ohos.permission.INTERNET

系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。

名称	类型	必填	说明
filename	string	是	multipart提交时，请求头中的文件名。
name	string	是	multipart提交时，表单项目的名称，缺省为file。
uri	string	是	文件的本地存储路径。仅支持“internal”协议类型，“internal://cache/”为必填字段，示例： internal://cache/path/to/file.txt
type	string	是	文件的内容类型，默认根据文件名或路径的后缀获取。

RequestData

需要权限：ohos.permission.INTERNET

系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。

名称	类型	必填	说明
name	string	是	表示表单元素的名称。
value	string	是	表示表单元素的值。

request.downloadFile⁹⁺

downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask>

下载，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	DownloadConfig	是	下载的配置信息。

返回值：

类型	说明
Promise<DownloadTask>	返回下载任务。

错误码： 以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400001	File operation error.
13400002	Bad file path.
13400003	Task manager service error.

示例：

let downloadTask;
try {
  request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
      downloadTask = data;
  }).catch((err) => {
      console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
  })
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

1
2
3
4
5
6
7
8
9
10

request.downloadFile⁹⁺

downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void;

下载，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
context	BaseContext	是	基于应用程序的上下文。
config	DownloadConfig	是	下载的配置信息。
callback	AsyncCallback<DownloadTask>	是	下载接口的回调函数。

错误码： 以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400001	File operation error.
13400002	Bad file path.
13400003	Task manager service error.

示例：

let downloadTask;
try {
  request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', 
  filePath: 'xxx/xxxxx.hap'}, (err, data) => {
      if (err) {
          console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
          return;
      }
      downloadTask = data;
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

1
2
3
4
5
6
7
8
9
10
11
12
13

request.download^(deprecated)

download(config: DownloadConfig): Promise<DownloadTask>

下载，异步方法，使用promise形式返回结果。

说明： 从API Version 9开始不再维护，建议使用request.downloadFile⁹⁺替代。

模型约束：此接口仅可在FA模型下使用

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
config	DownloadConfig	是	下载的配置信息。

返回值：

类型	说明
Promise<DownloadTask>	返回下载任务。

示例：

let downloadTask;
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
    downloadTask = data;
}).catch((err) => {
    console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})

1
2
3
4
5
6

request.download^(deprecated)

download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

下载，异步方法，使用callback形式返回结果。

说明： 从API Version 9开始不再维护，建议使用request.downloadFile⁹⁺替代。

模型约束：此接口仅可在FA模型下使用

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
config	DownloadConfig	是	下载的配置信息。
callback	AsyncCallback<DownloadTask>	是	下载接口的回调函数。

示例：

let downloadTask;
request.download({ url: 'https://xxxx/xxxxx.hap', 
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
    if (err) {
        console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
        return;
    }
    downloadTask = data;
});

1
2
3
4
5
6
7
8
9

DownloadTask

下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过request.downloadFile⁹⁺获取，callback形式通过request.downloadFile⁹⁺获取。

on('progress')

on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void

开启下载任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'progress'（下载的进度信息）。
callback	function	是	下载的回调函数。

回调函数的参数：

参数名	类型	必填	说明
receivedSize	number	是	当前下载的进度，单位为B。
totalSize	number	是	下载文件的总大小，单位为B。

示例：

downloadTask.on('progress', function download_callback(receivedSize, totalSize) {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);

1
2
3
4

off('progress')

off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void

关闭下载任务监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型，取值为'progress'（下载的进度信息）。
callback	function	否	下载任务的回调函数。

回调函数的参数：

参数名	类型	必填	说明
receivedSize	number	是	当前下载的进度，单位为B。
totalSize	number	是	下载文件的总大小，单位为B。

示例：

downloadTask .off('progress', function download_callback(receivedSize, totalSize) {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);

1
2
3
4

on('complete'|'pause'|'remove')⁷⁺

on(type: 'complete'|'pause'|'remove', callback:() => void): void

开启下载任务相关的监听，异步方法，使用callback形式返回。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型。 - 取值为'complete'，表示下载任务完成； - 取值为'pause'，表示下载任务暂停； - 取值为'remove'，表示下载任务移除。
callback	function	是	回调函数。

示例：

downloadTask.on('complete', function callback() {
    console.info('Download task completed.');
}
);

1
2
3
4

off('complete'|'pause'|'remove')⁷⁺

off(type: 'complete'|'pause'|'remove', callback?😦) => void): void

取消下载任务相关的监听，异步方法，使用callback形式返回。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。 - 取值为'complete'，表示下载任务完成； - 取值为'pause'，表示下载任务暂停； - 取值为'remove'，表示下载任务移除。
callback	function	否	回调函数。

示例：

downloadTask.off('complete', function callback() {
    console.info('Download task completed.');
}
);

1
2
3
4

on('fail')⁷⁺

on(type: 'fail', callback: (err: number) => void): void

开启下载任务失败监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	订阅的事件类型，取值为'fail'（下载失败）。
callback	function	是	下载失败的回调函数。

回调函数的参数：

参数名	类型	必填	说明
err	number	是	下载失败的错误码，错误原因见下载任务的错误码。

示例：

downloadTask.on('fail', function callBack(err) {
    console.info('Download task failed. Cause:' + err);
}
);

1
2
3
4

off('fail')⁷⁺

off(type: 'fail', callback?: (err: number) => void): void

取消下载任务失败监听，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型，取值为'fail'（下载失败）。
callback	function	否	取消下载失败的回调函数。

回调函数的参数

参数名	类型	必填	说明
err	number	是	下载失败的错误码。错误原因见下载任务的错误码。

示例：

downloadTask.off('fail', function callBack(err) {
    console.info('Download task failed. Cause:' + err);
} 
);

1
2
3
4

delete⁹⁺

delete(): Promise<boolean>

移除下载的任务，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<boolean>	移除任务是否成功。

示例：

downloadTask.delete().then((result) => {
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    }
}).catch ((err) => {
    console.error('Failed to remove the download task.');
});

1
2
3
4
5
6
7
8
9

delete⁹⁺

delete(callback: AsyncCallback<boolean>): void

移除下载的任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	移除任务是否成功。

示例：

downloadTask.delete((err, result)=>{
    if(err) {
        console.error('Failed to remove the download task.');
        return;
    } 
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    } 
});

1
2
3
4
5
6
7
8
9
10
11

getTaskInfo⁹⁺

getTaskInfo(): Promise<DownloadInfo>

查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<DownloadInfo>	查询下载任务信息。

示例：

downloadTask.getTaskInfo().then((downloadInfo) => {    
    console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
    console.error('Failed to query the download task. Cause:' + err)
});

1
2
3
4
5

getTaskInfo⁹⁺

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

查询下载的任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<DownloadInfo>	是	查询下载任务的回调函数。

示例：

downloadTask.getTaskInfo((err, downloadInfo)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('download query success. data:'+ JSON.stringify(downloadInfo));
    }
});

1
2
3
4
5
6
7

getTaskMimeType⁹⁺

getTaskMimeType(): Promise<string>

查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<string>	查询下载任务的MimeType。

示例：

downloadTask.getTaskMimeType().then((data) => {    
    console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});

1
2
3
4
5

getTaskMimeType⁹⁺

getTaskMimeType(callback: AsyncCallback<string>): void;

查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	查询下载任务的MimeType的回调函数。

示例：

downloadTask.getTaskMimeType((err, data)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('Download task queried. data:' + JSON.stringify(data));
    }
});

1
2
3
4
5
6
7

suspend⁹⁺

suspend(): Promise<boolean>

暂停下载任务，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<boolean>	暂停下载任务是否成功。

示例：

downloadTask.suspend().then((result) => {    
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
}).catch((err) => {
    console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});

1
2
3
4
5
6
7
8
9

suspend⁹⁺

suspend(callback: AsyncCallback<boolean>): void

暂停下载任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	暂停下载任务的回调函数。

示例：

downloadTask.suspend((err, result)=>{
    if(err) {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
        return;
    }
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
});

1
2
3
4
5
6
7
8
9
10
11

restore⁹⁺

restore(): Promise<boolean>

重新启动暂停的下载任务，异步方法，使用promise形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<boolean>	重新启动暂停的下载任务是否成功。

示例：

downloadTask.restore().then((result) => {
    if (result) {
        console.info('Download task resumed.')
    } else {
        console.error('Failed to resume the download task. ');
    }
    console.info('Download task resumed.')
}).catch((err) => {
    console.error('Failed to resume the download task. Cause:' + err);
});

1
2
3
4
5
6
7
8
9
10

restore⁹⁺

restore(callback: AsyncCallback<boolean>): void

重新启动暂停的下载任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	重新启动暂停的下载任务的回调函数。

示例：

downloadTask.restore((err, result)=>{
    if (err) {
        console.error('Failed to resume the download task. Cause:' + err);
        return;
    } 
    if (result) {
        console.info('Download task resumed.');
    } else {
        console.error('Failed to resume the download task.');
    }
});

1
2
3
4
5
6
7
8
9
10
11

remove^(deprecated)

remove(): Promise<boolean>

移除下载的任务，异步方法，使用promise形式返回结果。

说明： 从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<boolean>	移除任务是否成功。

示例：

downloadTask.remove().then((result) => {
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    }
}).catch ((err) => {
    console.error('Failed to remove the download task.');
});

1
2
3
4
5
6
7
8
9

remove^(deprecated)

remove(callback: AsyncCallback<boolean>): void

移除下载的任务，异步方法，使用callback形式返回结果。

说明： 从API Version 9开始不再维护，建议使用delete⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	移除任务是否成功。

示例：

downloadTask.remove((err, result)=>{
    if(err) {
        console.error('Failed to remove the download task.');
        return;
    } 
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    } 
});

1
2
3
4
5
6
7
8
9
10
11

query^(deprecated)

query(): Promise<DownloadInfo>

查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskInfo⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<DownloadInfo>	查询下载任务信息。

示例：

downloadTask.query().then((downloadInfo) => {    
    console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
    console.error('Failed to query the download task. Cause:' + err)
});

1
2
3
4
5

query^(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

查询下载的任务，异步方法，使用callback形式返回结果。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskInfo⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<DownloadInfo>	是	查询下载任务的回调函数。

示例：

downloadTask.query((err, downloadInfo)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('download query success. data:'+ JSON.stringify(downloadInfo));
    }
});

1
2
3
4
5
6
7

queryMimeType^(deprecated)

queryMimeType(): Promise<string>

查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskMimeType⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<string>	查询下载任务的MimeType。

示例：

downloadTask.queryMimeType().then((data) => {    
    console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});

1
2
3
4
5

queryMimeType^(deprecated)

queryMimeType(callback: AsyncCallback<string>): void;

查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用getTaskMimeType⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	查询下载任务的MimeType的回调函数。

示例：

downloadTask.queryMimeType((err, data)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('Download task queried. data:' + JSON.stringify(data));
    }
});

1
2
3
4
5
6
7

pause^(deprecated)

pause(): Promise<void>

暂停下载任务，异步方法，使用promise形式返回结果。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用suspend⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<void>	暂停下载任务是否成功。

示例：

downloadTask.pause().then((result) => {    
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
}).catch((err) => {
    console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});

1
2
3
4
5
6
7
8
9

pause^(deprecated)

pause(callback: AsyncCallback<void>): void

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用suspend⁹⁺替代。

暂停下载任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	暂停下载任务的回调函数。

示例：

downloadTask.pause((err, result)=>{
    if(err) {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
        return;
    }
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
});

1
2
3
4
5
6
7
8
9
10
11

resume^(deprecated)

resume(): Promise<void>

重新启动暂停的下载任务，异步方法，使用promise形式返回结果。

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用restore⁹⁺替代。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值：

类型	说明
Promise<void>	重新启动暂停的下载任务是否成功。

示例：

downloadTask.resume().then((result) => {
    if (result) {
        console.info('Download task resumed.')
    } else {
        console.error('Failed to resume the download task. ');
    }
    console.info('Download task resumed.')
}).catch((err) => {
    console.error('Failed to resume the download task. Cause:' + err);
});

1
2
3
4
5
6
7
8
9
10

resume^(deprecated)

resume(callback: AsyncCallback<void>): void

说明： 从API Version 7开始支持，从API Version 9开始不再维护，建议使用restore⁹⁺替代。

重新启动暂停的下载任务，异步方法，使用callback形式返回结果。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	重新启动暂停的下载任务的回调函数。

示例：

downloadTask.resume((err, result)=>{
    if (err) {
        console.error('Failed to resume the download task. Cause:' + err);
        return;
    } 
    if (result) {
        console.info('Download task resumed.');
    } else {
        console.error('Failed to resume the download task.');
    }
});

1
2
3
4
5
6
7
8
9
10
11

DownloadConfig

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

名称	类型	必填	说明
url	string	是	资源地址。
header	Object	否	添加要包含在下载请求中的HTTPS标志头。开发者可以通过header的X-TLS-Version参数指定需要使用的TLS版本(如果不指定，则默认使用CURL_SSLVERSION_TLSv1_2版本，指定则使用指定版本。) CURL_SSLVERSION_TLSv1_0 CURL_SSLVERSION_TLSv1_1 CURL_SSLVERSION_TLSv1_2 CURL_SSLVERSION_TLSv1_3 通过header的X-Cipher-List参数指定需要使用的密码套件(如果不指定，则默认使用安全密码套件，指定则使用指定密码套件。) -1.2允许使用的密码套件白名单： TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384, TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256, TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384, TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM, TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM, TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM, TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 -1.3允许使用的密码套件白名单： TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256 -1.3新增国密算法套： TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3
enableMetered	boolean	否	设置是否允许在按流量计费的连接下下载。 - true：是 - false：否
enableRoaming	boolean	否	设置是否允许在漫游网络中下载。 - true：是 - false：否
description	string	否	设置下载会话的描述。
filePath⁷⁺	string	否	设置下载路径。 - filePath:'/data/storage/el2/base/haps/entry/files/test.txt'：将文件存储在绝对路径下。 - FA模型下使用context 获取应用存储路径，比如：'{featureAbility.getContext().getFilesDir()}/test.txt'，并将文件存储在此路径下。 - Stage模型下使用[AbilityContext](js-apis-inner-application-context.md) 类获取文件路径，比如：'{globalThis.abilityContext.tempDir}/test.txt'并将文件存储在此路径下。
networkType	number	否	设置允许下载的网络类型。 - NETWORK_MOBILE：0x00000001 - NETWORK_WIFI：0x00010000
title	string	否	设置下载任务名称。
background⁹⁺	boolean	否	后台任务通知开关，开启后可在通知中显示下载状态。

DownloadInfo⁷⁺

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

名称	类型	必填	说明
downloadId	number	是	下载的文件ID。
failedReason	number	否	下载失败原因，可以是任何下载任务的错误码常量。
fileName	string	是	下载的文件名。
filePath	string	是	存储文件的URI。
pausedReason	number	否	会话暂停的原因，可以是任何下载任务暂停原因常量。
status	number	是	下载状态码，可以是任何下载任务状态码常量。
targetURI	string	是	下载文件的URI。
downloadTitle	string	是	下载任务名称。
downloadTotalBytes	number	是	下载的文件的总大小（int bytes）。
description	string	是	待下载文件的描述信息。
downloadedBytes	number	是	实时下载大小（int bytes）。

@ohos.request (上传下载)

@ohos.request (上传下载)

导入模块

限制与约束

常量

网络类型

下载任务的错误码

下载任务暂停原因

下载任务状态码

request.uploadFile9+

request.uploadFile9+

request.upload(deprecated)

request.upload(deprecated)

UploadTask

on('progress')

on('headerReceive')7+

on('complete' | 'fail')9+

off('progress')

off('headerReceive')7+

off('complete' | 'fail')9+

delete9+

delete9+

remove(deprecated)

remove(deprecated)

UploadConfig

TaskState9+

File

RequestData

request.downloadFile9+

request.downloadFile9+

request.download(deprecated)

request.download(deprecated)

DownloadTask

on('progress')

off('progress')

on('complete'|'pause'|'remove')7+

off('complete'|'pause'|'remove')7+

on('fail')7+

off('fail')7+

delete9+

delete9+

getTaskInfo9+

getTaskInfo9+

getTaskMimeType9+

getTaskMimeType9+

suspend9+

suspend9+

restore9+

restore9+

remove(deprecated)

remove(deprecated)

query(deprecated)

query(deprecated)

queryMimeType(deprecated)

queryMimeType(deprecated)

pause(deprecated)

pause(deprecated)

resume(deprecated)

resume(deprecated)

DownloadConfig

DownloadInfo7+

Description

request.uploadFile⁹⁺

request.uploadFile⁹⁺

request.upload^(deprecated)

request.upload^(deprecated)

on('headerReceive')⁷⁺

on('complete' | 'fail')⁹⁺

off('headerReceive')⁷⁺

off('complete' | 'fail')⁹⁺

delete⁹⁺

delete⁹⁺

remove^(deprecated)

remove^(deprecated)

TaskState⁹⁺

request.downloadFile⁹⁺

request.downloadFile⁹⁺

request.download^(deprecated)

request.download^(deprecated)

on('complete'|'pause'|'remove')⁷⁺

off('complete'|'pause'|'remove')⁷⁺

on('fail')⁷⁺

off('fail')⁷⁺

delete⁹⁺

delete⁹⁺

getTaskInfo⁹⁺

getTaskInfo⁹⁺

getTaskMimeType⁹⁺

getTaskMimeType⁹⁺

suspend⁹⁺

suspend⁹⁺

restore⁹⁺

restore⁹⁺

remove^(deprecated)

remove^(deprecated)

query^(deprecated)

query^(deprecated)

queryMimeType^(deprecated)

queryMimeType^(deprecated)

pause^(deprecated)

pause^(deprecated)

resume^(deprecated)

resume^(deprecated)

DownloadInfo⁷⁺