上传下载


上传下载

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

icon-note.gif 说明: 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import request from '@ohos.request';
1

限制与约束

在开发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协议的header方法,能够通过content-length获取下载数据大小,否则下载任务失败,可通过on('fail')7+)查看失败原因。

常量

需要权限:ohos.permission.INTERNET

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

名称 参数类型 可读 可写 说明
NETWORK_MOBILE number 使用蜂窝网络时允许下载的位标志。
NETWORK_WIFI number 使用WLAN时允许下载的位标志。
ERROR_CANNOT_RESUME7+ number 某些临时错误导致的恢复下载失败。
ERROR_DEVICE_NOT_FOUND7+ number 找不到SD卡等存储设备。
ERROR_FILE_ALREADY_EXISTS7+ number 要下载的文件已存在,下载会话不能覆盖现有文件。
ERROR_FILE_ERROR7+ number 文件操作失败。
ERROR_HTTP_DATA_ERROR7+ number HTTP传输失败。
ERROR_INSUFFICIENT_SPACE7+ number 存储空间不足。
ERROR_TOO_MANY_REDIRECTS7+ number 网络重定向过多导致的错误。
ERROR_UNHANDLED_HTTP_CODE7+ number 无法识别的HTTP代码。
ERROR_OFFLINE9+ number 网络未连接。
ERROR_UNSUPPORTED_NETWORK_TYPE9+ number 网络类型不匹配。
ERROR_UNKNOWN7+ number 未知错误。
PAUSED_QUEUED_FOR_WIFI7+ number 下载被暂停并等待WLAN连接,因为文件大小超过了使用蜂窝网络的会话允许的最大值。
PAUSED_UNKNOWN7+ number 未知原因导致暂停下载。
PAUSED_WAITING_FOR_NETWORK7+ number 由于网络问题(例如网络断开)而暂停下载。
PAUSED_WAITING_TO_RETRY7+ number 发生网络错误,将重试下载会话。
SESSION_FAILED7+ number 下载会话已失败,将不会重试。
SESSION_PAUSED7+ number 下载会话已暂停。
SESSION_PENDING7+ number 正在调度下载会话。
SESSION_RUNNING7+ number 下载会话正在进行中。
SESSION_SUCCESSFUL7+ number 下载会话已完成。

request.upload

upload(config: UploadConfig): Promise<UploadTask>

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

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

说明: 从API Version 9开始废弃,建议使用request.uploadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

返回值:

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

示例:

let uploadTask;
let uploadConfig = {
  url: 'https://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

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

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

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

说明: 从API Version 9开始废弃,建议使用request.uploadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

示例:

let uploadTask;
let uploadConfig = {
  url: 'https://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

request.upload9+

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

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

说明: 从API Version 9开始废弃,建议使用request.uploadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

返回值:

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

示例:

let uploadTask;
let uploadConfig = {
  url: 'https://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(globalThis.abilityContext, 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.upload9+

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

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

说明: 从API Version 9开始废弃,建议使用request.uploadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

示例:

let uploadTask;
let uploadConfig = {
  url: 'https://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(globalThis.abilityContext, 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

request.uploadFile9+

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: 'https://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.uploadFile(globalThis.abilityContext, 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.uploadFile9+

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: 'https://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.uploadFile(globalThis.abilityContext, 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对象。

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 当前已上传文件大小,单位为KB。
totalSize number 上传文件的总大小,单位为KB。

示例:

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

on('headerReceive')7+

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')9+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名 类型 必填 说明
type string 订阅的事件类型,取值为'complete',表示上传任务完成;取值为'fail',表示上传任务失败。
callback function 上传任务完成或失败的回调函数。

回调函数的参数

参数名 类型 必填 说明
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 当前已上传文件的大小,单位为KB。
totalSize number 上传文件的总大小,单位为KB。

示例:

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

off('headerReceive')7+

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')9+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名 类型 必填 说明
type string 订阅的事件类型,取值为'complete',表示上传任务完成;取值为'fail',表示上传任务失败。
callback function 上传任务完成或失败的回调函数。

回调函数的参数

参数名 类型 必填 说明
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

remove

remove(): Promise<boolean>

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

说明: 从API Version 9开始废弃,建议使用delete9+替代。

需要权限: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

remove(callback: AsyncCallback<boolean>): void

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

说明: 从API Version 9开始废弃,建议使用delete9+替代。

需要权限: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

delete9+

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

delete9+

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

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> 请求的表单数据。

TaskState9+

需要权限: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 文件的本地存储路径。
支持“dataability”和“internal”两种协议类型,但“internal”仅支持临时目录,示例:
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt
type string 文件的内容类型,默认根据文件名或路径的后缀获取。

RequestData

需要权限:ohos.permission.INTERNET

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

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

request.download

download(config: DownloadConfig): Promise<DownloadTask>

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

说明: 从API Version 9开始废弃,建议使用request.downloadFile9+替代。

此接口仅可在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

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

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

说明: 从API Version 9开始废弃,建议使用request.downloadFile9+替代。

此接口仅可在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

request.download9+

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

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

说明: 从API Version 9开始废弃,建议使用request.downloadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

返回值:

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

示例:

let downloadTask;
request.download(globalThis.abilityContext, { 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.download9+

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

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

说明: 从API Version 9开始废弃,建议使用request.downloadFile9+替代。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

let downloadTask;
request.download(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;
});
1
2
3
4
5
6
7
8
9

request.downloadFile9+

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;
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));
})
1
2
3
4
5
6

request.downloadFile9+

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;
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;
});
1
2
3
4
5
6
7
8
9

DownloadTask

下载任务。

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 当前下载的进度,单位为KB。
totalSize number 下载文件的总大小,单位为KB。

示例:

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 当前下载的进度。
totalSize number 下载文件的总大小。

示例:

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

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

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')7+

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')7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

回调函数的参数:

参数名 类型 必填 说明
err number 下载失败的错误码,错误原因见ERROR.*

示例:

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

off('fail')7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

回调函数的参数

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

示例:

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

remove

remove(): Promise<boolean>

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

说明: 从API Version 9开始废弃,建议使用delete9+替代。

需要权限: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

remove(callback: AsyncCallback<boolean>): void

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

说明: 从API Version 9开始废弃,建议使用delete9+替代。

需要权限: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

query7+

query(): Promise<DownloadInfo>

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

说明: 从API Version 9开始废弃,建议使用getTaskInfo9+替代。

需要权限: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

query7+

query(callback: AsyncCallback<DownloadInfo>): void

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

说明: 从API Version 9开始废弃,建议使用getTaskInfo9+替代。

需要权限: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

queryMimeType7+

queryMimeType(): Promise<string>

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

说明: 从API Version 9开始废弃,建议使用getTaskMimeType9+替代。

需要权限: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

queryMimeType7+

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

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

说明: 从API Version 9开始废弃,建议使用getTaskMimeType9+替代。

需要权限: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

pause7+

pause(): Promise<void>

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

说明: 从API Version 9开始废弃,建议使用suspend9+替代。

需要权限: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

pause7+

pause(callback: AsyncCallback<void>): void

说明: 从API Version 9开始废弃,建议使用suspend9+替代。

暂停下载任务,异步方法,使用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

resume7+

resume(): Promise<void>

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

说明: 从API Version 9开始废弃,建议使用restore9+替代。

需要权限: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

resume7+

resume(callback: AsyncCallback<void>): void

说明: 从API Version 9开始废弃,建议使用restore9+替代。

重新启动暂停的下载任务,异步方法,使用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

delete9+

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

delete9+

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

getTaskInfo9+

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

getTaskInfo9+

query(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

getTaskMimeType9+

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

getTaskMimeType9+

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

suspend9+

suspend(): Promise<void>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

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

示例:

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

suspend9+

suspend(callback: AsyncCallback<void>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

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

restore9+

restore(): Promise<void>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

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

restore9+

restore(callback: AsyncCallback<void>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

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

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 设置下载会话的描述。
filePath7+ string 设置下载路径(默认在'internal://cache/'路径下)。
- filePath:'workspace/test.txt':默认路径下创建workspace路径,并将文件存储在workspace路径下。
- filePath:'test.txt':将文件存储在默认路径下。
- filePath:'workspace/':默认路径下创建workspace路径,并将文件存储在workspace路径下。
networkType number 设置允许下载的网络类型。
- NETWORK_MOBILE:0x00000001
- NETWORK_WIFI:0x00010000
title string 设置下载会话标题。
background9+ boolean 后台任务通知开关,开启后可在通知中显示下载状态。

DownloadInfo7+

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

名称 类型 必填 说明
downloadId number 下载的文件ID。
failedReason number 下载失败原因,可以是任何ERROR_*常量。
fileName string 下载的文件名。
filePath string 存储文件的URI。
pausedReason number 会话暂停的原因,可以是任何PAUSED_*常量。
status number 下载状态代码,可以是任何SESSION_*常量。
targetURI string 下载文件的URI。
downloadTitle string 下载的文件的标题。
downloadTotalBytes number 下载的文件的总大小(int bytes)。
description string 待下载文件的描述信息。
downloadedBytes number 实时下载大小(int  bytes)。