上传下载

2024-01-23 16:44 更新

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

说明

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

导入模块

  1. import request from '@ohos.request';

常量

需要权限:ohos.permission.INTERNET

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

网络类型

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

名称

参数类型

数值

说明

NETWORK_MOBILE

number

0x00000001

使用蜂窝网络时允许下载的位标志。

NETWORK_WIFI

number

0x00010000

使用WLAN时允许下载的位标志。

下载任务的错误码

下载on('fail')7+事件的错误参数、 getTaskInfo9+返回值的failedReason字段取值。

名称

参数类型

数值

说明

ERROR_CANNOT_RESUME7+

number

0

网络原因导致恢复下载失败。

ERROR_DEVICE_NOT_FOUND7+

number

1

找不到SD卡等存储设备。

ERROR_FILE_ALREADY_EXISTS7+

number

2

要下载的文件已存在,下载会话不能覆盖现有文件。

ERROR_FILE_ERROR7+

number

3

文件操作失败。

ERROR_HTTP_DATA_ERROR7+

number

4

HTTP传输失败。

ERROR_INSUFFICIENT_SPACE7+

number

5

存储空间不足。

ERROR_TOO_MANY_REDIRECTS7+

number

6

网络重定向过多导致的错误。

ERROR_UNHANDLED_HTTP_CODE7+

number

7

无法识别的HTTP代码。

ERROR_UNKNOWN7+

number

8

未知错误。

ERROR_OFFLINE9+

number

9

网络未连接。

ERROR_UNSUPPORTED_NETWORK_TYPE9+

number

10

网络类型不匹配。

下载任务暂停原因

下载相关getTaskInfo9+返回值的pausedReason字段取值。

名称

参数类型

数值

说明

PAUSED_QUEUED_FOR_WIFI7+

number

0

下载被暂停并等待WLAN连接,因为文件大小超过了使用蜂窝网络的会话允许的最大值。

PAUSED_WAITING_FOR_NETWORK7+

number

1

由于网络问题(例如网络断开)而暂停下载。

PAUSED_WAITING_TO_RETRY7+

number

2

发生网络错误,将重试下载会话。

PAUSED_BY_USER9+

number

3

用户暂停会话。

PAUSED_UNKNOWN7+

number

4

未知原因导致暂停下载。

下载任务状态码

下载相关getTaskInfo9+返回值的status字段取值。

名称

参数类型

数值

说明

SESSION_SUCCESSFUL7+

number

0

下载会话已完成。

SESSION_RUNNING7+

number

1

下载会话正在进行中。

SESSION_PENDING7+

number

2

正在调度下载会话。

SESSION_PAUSED7+

number

3

下载会话已暂停。

SESSION_FAILED7+

number

4

下载会话已失败,将不会重试。

request.uploadFile9+

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

上传,异步方法,使用promise形式返回结果。通过on('fail')7+可获取任务上传时的错误信息。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

context

BaseContext

基于应用程序的上下文。

config

UploadConfig

上传的配置信息。

返回值:

类型

说明

Promise<UploadTask>

返回上传任务。

错误码:

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

错误码ID

错误信息

13400002

bad file path.

示例:

  1. let uploadTask;
  2. let uploadConfig = {
  3. url: 'http://www.example.com', //需要手动替换为真实服务器地址
  4. header: { 'Accept': '*/*' },
  5. method: "POST",
  6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  7. data: [{ name: "name123", value: "123" }],
  8. };
  9. try {
  10. request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => {
  11. uploadTask = data;
  12. }).catch((err) => {
  13. console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  14. });
  15. } catch (err) {
  16. console.error('err.code : ' + err.code + ', err.message : ' + err.message);
  17. }

request.uploadFile9+

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

上传,异步方法,使用callback形式返回结果。通过on('fail')7+可获取任务上传时的错误信息。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

context

BaseContext

基于应用程序的上下文。

config

UploadConfig

上传的配置信息。

callback

AsyncCallback<UploadTask>

回调函数,异步返回UploadTask对象。

错误码:

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

错误码ID

错误信息

13400002

bad file path.

示例:

  1. let uploadTask;
  2. let uploadConfig = {
  3. url: 'http://www.example.com', //需要手动替换为真实服务器地址
  4. header: { 'Accept': '*/*' },
  5. method: "POST",
  6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  7. data: [{ name: "name123", value: "123" }],
  8. };
  9. try {
  10. request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => {
  11. if (err) {
  12. console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  13. return;
  14. }
  15. uploadTask = data;
  16. });
  17. } catch (err) {
  18. console.error('err.code : ' + err.code + ', err.message : ' + err.message);
  19. }

request.upload(deprecated)

upload(config: UploadConfig): Promise<UploadTask>

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

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

config

UploadConfig

上传的配置信息。

返回值:

类型

说明

Promise<UploadTask>

返回上传任务。

示例:

  1. let uploadTask;
  2. let uploadConfig = {
  3. url: 'http://www.example.com', //需要手动替换为真实服务器地址
  4. header: { 'Accept': '*/*' },
  5. method: "POST",
  6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  7. data: [{ name: "name123", value: "123" }],
  8. };
  9. request.upload(uploadConfig).then((data) => {
  10. uploadTask = data;
  11. }).catch((err) => {
  12. console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  13. })

request.upload(deprecated)

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

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

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

config

UploadConfig

上传的配置信息。

callback

AsyncCallback<UploadTask>

回调函数,异步返回UploadTask对象。

示例:

  1. let uploadTask;
  2. let uploadConfig = {
  3. url: 'http://www.example.com', //需要手动替换为真实服务器地址
  4. header: { 'Accept': '*/*' },
  5. method: "POST",
  6. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  7. data: [{ name: "name123", value: "123" }],
  8. };
  9. request.upload(uploadConfig, (err, data) => {
  10. if (err) {
  11. console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  12. return;
  13. }
  14. uploadTask = data;
  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

当前已上传文件大小,单位为bit。

totalSize

number

上传文件的总大小,单位为bit。

示例:

  1. let upProgressCallback = (uploadedSize, totalSize) => {
  2. console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize);
  3. };
  4. uploadTask.on('progress', upProgressCallback);

on('headerReceive')7+

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

订阅上传任务HTTP标头监听,同步方法,使用callback形式返回结果。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

type

string

订阅的事件类型,取值为'headerReceive'(接收响应头)。

callback

function

HTTP Response Header事件的回调函数。

回调函数的参数:

参数名

类型

必填

说明

header

object

HTTP Response Header。

示例:

  1. let headerCallback = (headers) => {
  2. console.info("upOnHeader headers:" + JSON.stringify(headers)
  3. );
  4. uploadTask.on('headerReceive', headerCallback);

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

Callback<Array<TaskState>>

上传任务完成或失败的回调函数。

回调函数的参数:

参数名

类型

必填

说明

taskstates

Array<TaskState>

上传任务返回结果。

示例:

  1. let upCompleteCallback = (taskStates) => {
  2. for (let i = 0; i < taskStates.length; i++ ) {
  3. console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
  4. }
  5. };
  6. uploadTask.on('complete', upCompleteCallback);
  7. let upFailCallback = (taskStates) => {
  8. for (let i = 0; i < taskStates.length; i++ ) {
  9. console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  10. }
  11. };
  12. uploadTask.on('fail', upFailCallback);

off('progress')

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

删除上传任务进度监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

type

string

取消订阅的事件类型,取值为'progress'(上传的进度信息)。

callback

function

上传任务的回调函数。

uploadedSize:当前已上传文件的大小,单位为bit。

totalSize:上传文件的总大小,单位为bit。

示例:

  1. let upProgressCallback = (uploadedSize, totalSize) => {
  2. console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
  3. };
  4. uploadTask.off('progress', upProgressCallback);

off('headerReceive')7+

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

删除上传任务HTTP标头监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

type

string

取消订阅的事件类型,取值为'headerReceive'(接收响应头)。

callback

function

HTTP Response Header事件的回调函数。

header:HTTP Response Header。

示例:

  1. let headerCallback = (header) => {
  2. console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
  3. };
  4. uploadTask.off('headerReceive', headerCallback);

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

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

删除上传任务完成或失败监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

type

string

订阅的事件类型,取值为'complete',表示上传任务完成;取值为'fail',表示上传任务失败。

callback

Callback<Array<TaskState>>

需要删除的上传任务完成或失败的回调函数。

taskstates:上传任务返回结果。

示例:

  1. let upCompleteCallback = (taskStates) => {
  2. console.info('Upload delete complete notification.');
  3. for (let i = 0; i < taskStates.length; i++ ) {
  4. console.info('taskState:' + JSON.stringify(taskStates[i]));
  5. }
  6. };
  7. uploadTask.off('complete', upCompleteCallback);
  8. let upFailCallback = (taskStates) => {
  9. console.info('Upload delete fail notification.');
  10. for (let i = 0; i < taskStates.length; i++ ) {
  11. console.info('taskState:' + JSON.stringify(taskStates[i]));
  12. }
  13. };
  14. uploadTask.off('fail', upFailCallback);

delete9+

delete(): Promise<boolean>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

返回值:

类型

说明

Promise<boolean>

移除任务是否成功。true:成功,false:不成功。

示例:

  1. uploadTask.delete().then((result) => {
  2. if (result) {
  3. console.info('Upload task removed successfully. ');
  4. } else {
  5. console.error('Failed to remove the upload task. ');
  6. }
  7. }).catch((err) => {
  8. console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
  9. });

delete9+

delete(callback: AsyncCallback<boolean>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

移除任务的回调函数。

示例:

  1. uploadTask.delete((err, result) => {
  2. if (err) {
  3. console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
  4. return;
  5. }
  6. if (result) {
  7. console.info('Upload task removed successfully.');
  8. } else {
  9. console.error('Failed to remove the upload task.');
  10. }
  11. });

remove(deprecated)

remove(): Promise<boolean>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

返回值:

类型

说明

Promise<boolean>

移除任务是否成功。true:成功,false:不成功。

示例:

  1. uploadTask.remove().then((result) => {
  2. if (result) {
  3. console.info('Upload task removed successfully. ');
  4. } else {
  5. console.error('Failed to remove the upload task. ');
  6. }
  7. }).catch((err) => {
  8. console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
  9. });

remove(deprecated)

remove(callback: AsyncCallback<boolean>): void

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

移除任务的回调函数。

示例:

  1. uploadTask.remove((err, result) => {
  2. if (err) {
  3. console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
  4. return;
  5. }
  6. if (result) {
  7. console.info('Upload task removed successfully.');
  8. } else {
  9. console.error('Failed to remove the upload task.');
  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+

上传任务信息,on('complete' | 'fail')off('complete' | 'fail')接口的回调参数。

需要权限:ohos.permission.INTERNET

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

名称

类型

必填

说明

path

string

文件路径

responseCode

number

上传任务返回值

message

string

上传任务结果描述信息

File

UploadConfig中的文件列表。

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

UploadConfig中的表单数据。

需要权限:ohos.permission.INTERNET

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

名称

类型

必填

说明

name

string

表示表单元素的名称。

value

string

表示表单元素的值。

request.downloadFile9+

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

下载,异步方法,使用promise形式返回结果。通过on('complete'|'pause'|'remove')可获取任务下载时的状态信息,包括任务完成、暂停或移除。通过on('fail')可获取任务下载时的错误信息。

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

示例:

  1. let downloadTask;
  2. try {
  3. request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
  4. downloadTask = data;
  5. }).catch((err) => {
  6. console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
  7. })
  8. } catch (err) {
  9. console.error('err.code : ' + err.code + ', err.message : ' + err.message);
  10. }

request.downloadFile9+

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

下载,异步方法,使用callback形式返回结果。通过on('complete'|'pause'|'remove')可获取任务下载时的状态信息,包括任务完成、暂停或移除。通过on('fail')可获取任务下载时的错误信息。

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

示例:

  1. let downloadTask;
  2. try {
  3. request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap',
  4. filePath: 'xxx/xxxxx.hap'}, (err, data) => {
  5. if (err) {
  6. console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
  7. return;
  8. }
  9. downloadTask = data;
  10. });
  11. } catch (err) {
  12. console.error('err.code : ' + err.code + ', err.message : ' + err.message);
  13. }

request.download(deprecated)

download(config: DownloadConfig): Promise<DownloadTask>

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

说明

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

config

DownloadConfig

下载的配置信息。

返回值:

类型

说明

Promise<DownloadTask>

返回下载任务。

示例:

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

request.download(deprecated)

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

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

说明

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

config

DownloadConfig

下载的配置信息。

callback

AsyncCallback<DownloadTask>

下载接口的回调函数。

示例:

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

DownloadTask

下载任务,使用下列方法前,需要先获取DownloadTask对象,promise形式通过request.downloadFile9+获取,callback形式通过request.downloadFile9+获取。

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

当前下载的进度,单位为bit。

totalSize

number

下载文件的总大小,单位为bit。

示例:

  1. let progresCallback = (receivedSize, totalSize) => {
  2. console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
  3. };
  4. downloadTask.on('progress', progresCallback);

off('progress')

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

删除下载任务进度监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

type

string

取消订阅的事件类型,取值为'progress'(下载的进度信息)。

callback

function

需要删除的下载任务进度的回调。

receivedSize:当前下载任务的进度,单位为bit。

totalSize:下载文件的总大小,单位为bit。

示例:

  1. let progresCallback = (receivedSize, totalSize) => {
  2. console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
  3. };
  4. downloadTask .off('progress',progresCallback);

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

回调函数。

示例:

  1. let completeCallback = () => {
  2. console.info('Download task completed.');
  3. };
  4. downloadTask.on('complete', completeCallback);
  5. let pauseCallback = () => {
  6. console.info('Download task pause.');
  7. };
  8. downloadTask.on('pause', pauseCallback);
  9. let removeCallback = () => {
  10. console.info('Download task remove.');
  11. };
  12. downloadTask.on('remove', removeCallback);

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

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

删除下载任务相关的监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

type

string

取消订阅的事件类型。

- 取值为'complete',表示下载任务完成;

- 取值为'pause',表示下载任务暂停;

- 取值为'remove',表示下载任务移除。

callback

function

回调函数。

示例:

  1. let completeCallback = () => {
  2. console.info('Download delete complete notification.');
  3. };
  4. downloadTask.off('complete', completeCallback);
  5. let pauseCallback = () => {
  6. console.info('Download delete pause notification.');
  7. };
  8. downloadTask.off('pause', pauseCallback);
  9. let removeCallback = () => {
  10. console.info('Download delete remove notification.');
  11. };
  12. downloadTask.off('remove', removeCallback);

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

下载失败的错误码,错误原因见下载任务的错误码

示例:

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

off('fail')7+

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

删除下载任务失败监听,同步方法。

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

type

string

取消订阅的事件类型,取值为'fail'(下载失败)。

callback

function

需要删除的下载失败的回调函数。

err:下载失败的错误码。

示例:

  1. let failCallback = (err) => {
  2. console.info(`Download delete fail notification. err: ${err.message}`);
  3. };
  4. downloadTask.off('fail', failCallback);

delete9+

delete(): Promise<boolean>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<boolean>

移除任务是否成功。

示例:

  1. downloadTask.delete().then((result) => {
  2. if (result) {
  3. console.info('Download task removed.');
  4. } else {
  5. console.error('Failed to remove the download task.');
  6. }
  7. }).catch ((err) => {
  8. console.error('Failed to remove the download task.');
  9. });

delete9+

delete(callback: AsyncCallback<boolean>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

移除任务是否成功。

示例:

  1. downloadTask.delete((err, result)=>{
  2. if(err) {
  3. console.error('Failed to remove the download task.');
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task removed.');
  8. } else {
  9. console.error('Failed to remove the download task.');
  10. }
  11. });

getTaskInfo9+

getTaskInfo(): Promise<DownloadInfo>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<DownloadInfo>

查询下载任务信息。

示例:

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

getTaskInfo9+

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<DownloadInfo>

查询下载任务的回调函数。

示例:

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

getTaskMimeType9+

getTaskMimeType(): Promise<string>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<string>

查询下载任务的MimeType。

示例:

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

getTaskMimeType9+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<string>

查询下载任务的MimeType的回调函数。

示例:

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

suspend9+

suspend(): Promise<boolean>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<boolean>

暂停下载任务是否成功。

示例:

  1. downloadTask.suspend().then((result) => {
  2. if (result) {
  3. console.info('Download task paused. ');
  4. } else {
  5. console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
  6. }
  7. }).catch((err) => {
  8. console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
  9. });

suspend9+

suspend(callback: AsyncCallback<boolean>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

暂停下载任务的回调函数。

示例:

  1. downloadTask.suspend((err, result)=>{
  2. if(err) {
  3. console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task paused. ');
  8. } else {
  9. console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
  10. }
  11. });

restore9+

restore(): Promise<boolean>

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<boolean>

重新启动暂停的下载任务是否成功。

示例:

  1. downloadTask.restore().then((result) => {
  2. if (result) {
  3. console.info('Download task resumed.')
  4. } else {
  5. console.error('Failed to resume the download task. ');
  6. }
  7. console.info('Download task resumed.')
  8. }).catch((err) => {
  9. console.error('Failed to resume the download task. Cause:' + err);
  10. });

restore9+

restore(callback: AsyncCallback<boolean>): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

重新启动暂停的下载任务的回调函数。

示例:

  1. downloadTask.restore((err, result)=>{
  2. if (err) {
  3. console.error('Failed to resume the download task. Cause:' + err);
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task resumed.');
  8. } else {
  9. console.error('Failed to resume the download task.');
  10. }
  11. });

remove(deprecated)

remove(): Promise<boolean>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<boolean>

移除任务是否成功。

示例:

  1. downloadTask.remove().then((result) => {
  2. if (result) {
  3. console.info('Download task removed.');
  4. } else {
  5. console.error('Failed to remove the download task.');
  6. }
  7. }).catch ((err) => {
  8. console.error('Failed to remove the download task.');
  9. });

remove(deprecated)

remove(callback: AsyncCallback<boolean>): void

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<boolean>

移除任务是否成功。

示例:

  1. downloadTask.remove((err, result)=>{
  2. if(err) {
  3. console.error('Failed to remove the download task.');
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task removed.');
  8. } else {
  9. console.error('Failed to remove the download task.');
  10. }
  11. });

query(deprecated)

query(): Promise<DownloadInfo>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<DownloadInfo>

查询下载任务信息。

示例:

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

query(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<DownloadInfo>

查询下载任务的回调函数。

示例:

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

queryMimeType(deprecated)

queryMimeType(): Promise<string>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<string>

查询下载任务的MimeType。

示例:

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

queryMimeType(deprecated)

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

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<string>

查询下载任务的MimeType的回调函数。

示例:

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

pause(deprecated)

pause(): Promise<void>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<void>

暂停下载任务是否成功。

示例:

  1. downloadTask.pause().then((result) => {
  2. if (result) {
  3. console.info('Download task paused. ');
  4. } else {
  5. console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
  6. }
  7. }).catch((err) => {
  8. console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
  9. });

pause(deprecated)

pause(callback: AsyncCallback<void>): void

说明

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<void>

暂停下载任务的回调函数。

示例:

  1. downloadTask.pause((err, result)=>{
  2. if(err) {
  3. console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task paused. ');
  8. } else {
  9. console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
  10. }
  11. });

resume(deprecated)

resume(): Promise<void>

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

说明

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型

说明

Promise<void>

重新启动暂停的下载任务是否成功。

示例:

  1. downloadTask.resume().then((result) => {
  2. if (result) {
  3. console.info('Download task resumed.')
  4. } else {
  5. console.error('Failed to resume the download task. ');
  6. }
  7. console.info('Download task resumed.')
  8. }).catch((err) => {
  9. console.error('Failed to resume the download task. Cause:' + err);
  10. });

resume(deprecated)

resume(callback: AsyncCallback<void>): void

说明

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名

类型

必填

说明

callback

AsyncCallback<void>

重新启动暂停的下载任务的回调函数。

示例:

  1. downloadTask.resume((err, result)=>{
  2. if (err) {
  3. console.error('Failed to resume the download task. Cause:' + err);
  4. return;
  5. }
  6. if (result) {
  7. console.info('Download task resumed.');
  8. } else {
  9. console.error('Failed to resume the download task.');
  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

设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络,数据流量为计费网络。

- true:是

- false:否

enableRoaming

boolean

设置是否允许在漫游网络中下载(默认使用false)。

- true:是

- false:否

description

string

设置下载会话的描述。

filePath7+

string

设置下载路径。

- FA模型下使用context 获取应用存储路径,比如:'${featureAbility.getContext().getFilesDir()}/test.txt',并将文件存储在此路径下。

- Stage模型下使用AbilityContext 类获取文件路径,比如:'${globalThis.abilityContext.tempDir}/test.txt'并将文件存储在此路径下。

networkType

number

设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI,网络正常连接即可下载)。

- NETWORK_MOBILE:0x00000001

- NETWORK_WIFI:0x00010000

title

string

设置下载任务名称。

background9+

boolean

后台任务通知开关,开启后可在通知中显示下载状态(默认使用false)。

DownloadInfo7+

下载任务信息, getTaskInfo9+接口的回调参数。

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

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号