鸿蒙开发网络管理:【@ohos.request (上传下载)】

上传下载

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

导入模块

import request from '@ohos.request';

限制与约束

默认支持https,如果要支持http,需要在config.json里增加network标签,属性标识 “cleartextTraffic”: true。即:

  "deviceConfig": {
    "default": {
      "network": {
        "cleartextTraffic": true
      }
      ...
    }
  }

常量

需要权限:ohos.permission.INTERNET

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

名称参数类型可读可写说明
NETWORK_MOBILEnumber使用蜂窝网络时允许下载的位标志。
NETWORK_WIFInumber使用WLAN时允许下载的位标志。
ERROR_CANNOT_RESUME7+number某些临时错误导致的恢复下载失败。
ERROR_DEVICE_NOT_FOUND7+number找不到SD卡等存储设备。
ERROR_FILE_ALREADY_EXISTS7+number要下载的文件已存在,下载会话不能覆盖现有文件。
ERROR_FILE_ERROR7+number文件操作失败。
ERROR_HTTP_DATA_ERROR7+numberHTTP传输失败。
ERROR_INSUFFICIENT_SPACE7+number存储空间不足。
ERROR_TOO_MANY_REDIRECTS7+number网络重定向过多导致的错误。
ERROR_UNHANDLED_HTTP_CODE7+number无法识别的HTTP代码。
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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

返回值:

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

示例:

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

request.upload

upload(config: UploadConfig, callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

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

示例:

let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" };
let data = { name: "name123", value: "123" };
let header = { key1: "value1", key2: "value2" };
let uploadTask;
request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }, (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

参数:

参数名类型必填说明
typestring订阅的事件类型,取值为’progress’(上传的进度信息)。
callbackfunction上传进度的回调函数。

回调函数的参数

参数名类型必填说明
uploadedSizenumber当前已上传文件大小,单位为KB。
totalSizenumber上传文件的总大小,单位为KB。

示例:

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

on(‘headerReceive’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名类型必填说明
typestring订阅的事件类型,取值为’headerReceive’(接收响应头)。
callbackfunctionHTTP Response Header事件的回调函数。

回调函数的参数:

参数名类型必填说明
headerobjectHTTP Response Header。

示例:

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

off(‘progress’)

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名参数类型必填说明
typestring取消订阅的事件类型,取值为’progress’(上传的进度信息)。
callbackfunction上传任务的回调函数。

回调函数的参数:

参数名类型必填说明
uploadedSizenumber当前已上传文件的大小,单位为KB。
totalSizenumber上传文件的总大小,单位为KB。

示例:

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

off(‘headerReceive’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名参数类型必填说明
typestring取消订阅的事件类型,取值为’headerReceive’(接收响应头)。
callbackfunctionHTTP Response Header事件的回调函数。

回调函数的参数:

参数名类型必填说明
headerobjectHTTP Response Header。

示例:

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

remove

remove(): Promise

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

返回值:

类型说明
Promise移除任务是否成功。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

remove(callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Upload

参数:

参数名参数类型必填说明
callbackAsyncCallback移除任务的回调函数。

示例:

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

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

名称类型必填说明
urlstring资源地址。
headerobject添加要包含在上载请求中的HTTP或HTTPS标志头。
methodstring请求方法:POST、PUT。缺省为POST。
filesArray<[File]>要上传的文件列表。请使用 multipart/form-data提交。
dataArray<[RequestData]>请求的表单数据。

File

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

名称类型必填说明
filenamestringmultipart提交时,请求头中的文件名。
namestringmultipart提交时,表单项目的名称,缺省为file。
uristring文件的本地存储路径。 支持“dataability”和“internal”两种协议类型,但“internal”仅支持临时目录,示例: dataability:///com.domainname.dataability.persondata/person/10/file.txt internal://cache/path/to/file.txt
typestring文件的内容类型,默认根据文件名或路径的后缀获取。

RequestData

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

名称类型必填说明
namestring表示表单元素的名称。
valuestring表示表单元素的值。

request.download

download(config: DownloadConfig): Promise

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

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

download(config: DownloadConfig, callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
config[DownloadConfig]下载的配置信息。
callbackAsyncCallback<[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

参数:

参数名类型必填说明
typestring订阅的事件类型,取值为’progress’(下载的进度信息)。
callbackfunction下载的回调函数。

回调函数的参数:

参数名类型必填说明
receivedSizenumber当前下载的进度,单位为KB。
totalSizenumber下载文件的总大小,单位为KB。

示例:

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

off(‘progress’)

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
typestring取消订阅的事件类型,取值为’progress’(下载的进度信息)。
callbackfunction下载任务的回调函数。

回调函数的参数:

参数名类型必填说明
receivedSizenumber当前下载的进度。
totalSizenumber下载文件的总大小。

示例:

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

on(‘complete’|‘pause’|‘remove’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名类型必填说明
typestring订阅的事件类型。 - 取值为’complete’,表示下载任务完成; - 取值为’pause’,表示下载任务暂停; - 取值为’remove’,表示下载任务移除。
callbackfunction回调函数。

示例:

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

off(‘complete’|‘pause’|‘remove’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名类型必填说明
typestring取消订阅的事件类型。 - 取值为’complete’,表示下载任务完成; - 取值为’pause’,表示下载任务暂停; - 取值为’remove’,表示下载任务移除。
callbackfunction回调函数。

示例:

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

on(‘fail’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名类型必填说明
typestring订阅的事件类型,取值为’fail’(下载失败)。
callbackfunction下载失败的回调函数。

回调函数的参数:

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

示例:

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

off(‘fail’)7+

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

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名类型必填说明
typestring取消订阅的事件类型,取值为’fail’(下载失败)。
callbackfunction取消下载失败的回调函数。

回调函数的参数

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

示例:

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

remove

remove(): Promise

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

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

示例:

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

remove(callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
callbackAsyncCallback移除任务是否成功。

示例:

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

query7+

query(): Promise

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

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

query7+

query(callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
callbackAsyncCallback<[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));
    }
});

queryMimeType7+

queryMimeType(): Promise

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

类型说明
Promise查询下载任务的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))
});

queryMimeType7+

queryMimeType(callback: AsyncCallback): void;

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
callbackAsyncCallback查询下载任务的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));
    }
});

pause7+

pause(): Promise

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

返回值:

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

示例:

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

pause7+

pause(callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

参数名参数类型必填说明
callbackAsyncCallback暂停下载任务的回调函数。

示例:

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

resume7+

resume(): Promise

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

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

resume7+

resume(callback: AsyncCallback): void

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

需要权限:ohos.permission.INTERNET

系统能力: SystemCapability.MiscServices.Download

参数:

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

示例:

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

系统能力: SystemCapability.MiscServices.Download

名称类型必填说明
urlstring资源地址。
headerobject添加要包含在下载请求中的HTTP或HTTPS标志头。
enableMeteredboolean允许在按流量计费的连接下下载。
enableRoamingboolean允许在漫游网络中下载。
descriptionstring设置下载会话的描述。
filePath7+string设置下载路径(默认在’internal://cache/'路径下)。 - filePath:‘workspace/test.txt’:默认路径下创建workspace路径,并将文件存储在workspace路径下。 - filePath:‘test.txt’:将文件存储在默认路径下。 - filePath:‘workspace/’:默认路径下创建workspace路径,并将文件存储在workspace路径下。
networkTypenumber设置允许下载的网络类型。
titlestring设置下载会话标题。

DownloadInfo7+

系统能力: SystemCapability.MiscServices.Download

名称类型必填说明
downloadIdnumber下载的文件ID。
failedReasonnumber下载失败原因,可以是任何[ERROR_*]常量。
fileNamestring下载的文件名。
filePathstring存储文件的URI。
pausedReasonnumber会话暂停的原因,可以是任何[PAUSED_*]常量。
statusnumber下载状态代码,可以是任何[SESSION_*]常量。
targetURIstring下载文件的URI。
downloadTitlestring下载的文件的标题。
downloadTotalBytesnumber下载的文件的总大小(int bytes)。
descriptionstring待下载文件的描述信息。
downloadedBytesnumber实时下载大小(int  bytes)。
  • 8
    点赞
  • 15
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值