当前位置： 首页 > news >正文

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

news 来源：原创 2024/9/29 11:38:46

上传下载

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+number是否HTTP传输失败。
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’（接收响应头）。
callbackfunction是HTTP Response Header事件的回调函数。

回调函数的参数：

参数名类型必填说明
headerobject是HTTP 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’（接收响应头）。
callbackfunction否HTTP Response Header事件的回调函数。

回调函数的参数：

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

名称类型必填说明
filenamestring否multipart提交时，请求头中的文件名。
namestring否multipart提交时，表单项目的名称，缺省为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）。

相关文章：

  • 48-4 内网渗透 - Rotten Potato(烂土豆) 提权
  • StableSwarmUI 安装教程（详细）
  • 【朝花夕拾】RT1170 CSI 如何使能摄像头Y8功能
  • 【自动驾驶】从零开始做自动驾驶小车
  • scale()函数详解
  • MySQL笔记——事务
  • 分享HTML显示2D/3D时间
  • Unity3d 游戏暂停(timeScale=0)引起的deltaTime关联的系列问题解决
  • [c++刷题]贪心算法.N01
  • 揭秘无局放电源：定义、工作原理及其在工业设备中的重要性
  • 鸿蒙开发：【进程模型概述】
  • PHP杂货铺家庭在线记账理财管理系统源码
  • kettle无法启动问题_PENTAHO_JAVA_HOME
  • Dify知识库接入微信
  • 解释React中的“端口（Portals）”是什么，以及如何使用它来渲染子节点到DOM树以外的部分。
  • codis proxy处理流程
  • JavaScript实现分页效果
  • java概述
  • Mybatis初体验
  • MySQL数据库运维之数据恢复
  • orm2 中文文档 3.1 模型属性
  • React Transition Group -- Transition 组件
  • seaborn 安装成功 + ImportError: DLL load failed: 找不到指定的模块 问题解决
  • TiDB 源码阅读系列文章（十）Chunk 和执行框架简介
  • vue数据传递--我有特殊的实现技巧
  • vue--为什么data属性必须是一个函数
  • Web Storage相关
  • 从零开始在ubuntu上搭建node开发环境
  • 基于 Ueditor 的现代化编辑器 Neditor 1.5.4 发布
  • 漫谈开发设计中的一些“原则”及“设计哲学”
  • 前端设计模式
  • 数据可视化之 Sankey 桑基图的实现
  • 怎么将电脑中的声音录制成WAV格式
  • kubernetes资源对象--ingress
  • ​​​【收录 Hello 算法】9.4 小结
  • # Swust 12th acm 邀请赛# [ K ] 三角形判定 [题解]
  • #define用法
  • #Spring-boot高级
  • $.type 怎么精确判断对象类型的 --（源码学习2）
  • （1）Hilt的基本概念和使用
  • (13)[Xamarin.Android] 不同分辨率下的图片使用概论
  • (Matlab)基于蝙蝠算法实现电力系统经济调度
  • （PWM呼吸灯）合泰开发板HT66F2390-----点灯大师
  • （python）数据结构---字典
  • （Redis使用系列） Springboot 在redis中使用BloomFilter布隆过滤器机制 六
  • （二）pulsar安装在独立的docker中，python测试
  • （附源码）springboot美食分享系统 毕业设计 612231
  • (汇总)os模块以及shutil模块对文件的操作
  • （三） diretfbrc详解
  • （十）Flink Table API 和 SQL 基本概念
  • （十一）c52学习之旅-动态数码管
  • （四）Linux Shell编程——输入输出重定向
  • （四）stm32之通信协议
  • (转)Linq学习笔记
  • （状压dp）uva 10817 Headmaster's Headache