@ohos.request (上传下载)

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

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

导入模块

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+事件callback的错误参数、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('complete'|'fail')9+可获取任务上传时的错误信息。

需要权限：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" }],
};
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);
}

request.uploadFile9+

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

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

需要权限：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" }],
};
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);
}

request.upload(deprecated)

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));
})

request.upload(deprecated)

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;
});

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。

示例：

let upProgressCallback = (uploadedSize, totalSize) => {
    console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
};
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。

示例：

let headerCallback = (headers) => {
    console.info("upOnHeader headers:" + JSON.stringify(headers));
};
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> 是 上传任务返回结果

示例：

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

let upFailCallback = (taskStates) => {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  }
};
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：当前已上传文件的大小，单位为B。
totalSize：上传文件的总大小，单位为B。

示例：

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。

示例：

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：上传任务返回结果

示例：

uploadTask.off('complete', upCompleteCallback);

uploadTask.off('fail', upFailCallback);

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));
});

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.');
    }
});

remove(deprecated)

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));
});

remove(deprecated)

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.');
    }
});

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')9+和off('complete' | 'fail')9+接口的回调参数。

需要权限：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')7+可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过on('fail')7+可获取任务下载时的错误信息。

需要权限：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);
}

request.downloadFile9+

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

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

需要权限：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);
}

request.download(deprecated)

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));
})

request.download(deprecated)

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;
});

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

示例：

let progresCallbanck = (receivedSize, totalSize) => {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
};
downloadTask.on('progress', progresCallbanck);

off('progress')

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

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

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数：

参数名 类型 必填 说明
type string 是 取消订阅的事件类型，取值为'progress'（下载的进度信息）。
callback function 否 需要删除的下载任务进度的回调。
receivedSize：当前下载任务的进度；
totalSize：下载文件的总大小。

示例：

downloadTask .off('progress',progresCallbanck);

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 是 下载任务相关的回调函数。

示例：

let completeCallback = () => {
    console.info('Download task completed.');
};
downloadTask.on('complete', completeCallback);

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 否 需要删除的下载任务相关的回调。

示例：

downloadTask.off('complete', completeCallback);

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 是 下载失败的错误码，错误原因见下载任务的错误码。

示例：

let failCallback = (err) => {
    console.info('Download task failed. Cause:' + err);
};
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：下载失败的错误码。

示例：

downloadTask.off('fail', failCallback);

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.');
});

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.');
    } 
});

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)
});

getTaskInfo9+

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));
    }
});

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))
});

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));
    }
});

suspend9+

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));
});

suspend9+

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));
    }
});

restore9+

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);
});

restore9+

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.');
    }
});

remove(deprecated)

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.');
});

remove(deprecated)

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.');
    } 
});

query(deprecated)

query(): Promise<DownloadInfo>

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

说明： 从API Version 7开始支持，从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)
});

query(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

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

说明： 从API Version 7开始支持，从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));
    }
});

queryMimeType(deprecated)

queryMimeType(): Promise<string>

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

说明： 从API Version 7开始支持，从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))
});

queryMimeType(deprecated)

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

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

说明： 从API Version 7开始支持，从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));
    }
});

pause(deprecated)

pause(): Promise<void>

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

说明： 从API Version 7开始支持，从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));
});

pause(deprecated)

pause(callback: AsyncCallback<void>): void

说明： 从API Version 7开始支持，从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));
    }
});

resume(deprecated)

resume(): Promise<void>

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

说明： 从API Version 7开始支持，从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);
});

resume(deprecated)

resume(callback: AsyncCallback<void>): void

说明： 从API Version 7开始支持，从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.');
    }
});

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）。