回复
HarmonyOS API：@ohos.request (上传下载)
joytrian
发布于 2023-4-7 15:55
浏览
0收藏
版本：v3.1 Beta
@ohos.request (上传下载)
更新时间: 2023-04-04 11:26
request部件主要给应用提供上传下载文件、后台传输代理的基础能力。
说明
本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
导入模块
import request from '@ohos.request';
限制与约束
下载服务器需要支持HTTP协议的head方法，能够通过Content-length获取下载数据大小，否则下载任务失败，可通过on('fail')7+)查看失败原因。
上传目前仅支持HTTP请求，不支持HTTPS。
常量
需要权限：ohos.permission.INTERNET
系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
名称 | 参数类型 | 可读 | 可写 | 说明 |
NETWORK_MOBILE | number | 是 | 否 | 使用蜂窝网络时允许下载的位标志。 |
NETWORK_WIFI | number | 是 | 否 | 使用WLAN时允许下载的位标志。 |
ERROR_CANNOT_RESUME7+ | number | 是 | 否 | 某些临时错误导致的恢复下载失败。 |
ERROR_DEVICE_NOT_FOUND7+ | number | 是 | 否 | 找不到SD卡等存储设备。 |
ERROR_FILE_ALREADY_EXISTS7+ | number | 是 | 否 | 要下载的文件已存在，下载会话不能覆盖现有文件。 |
ERROR_FILE_ERROR7+ | number | 是 | 否 | 文件操作失败。 |
ERROR_HTTP_DATA_ERROR7+ | number | 是 | 否 | HTTP传输失败。 |
ERROR_INSUFFICIENT_SPACE7+ | number | 是 | 否 | 存储空间不足。 |
ERROR_TOO_MANY_REDIRECTS7+ | number | 是 | 否 | 网络重定向过多导致的错误。 |
ERROR_UNHANDLED_HTTP_CODE7+ | number | 是 | 否 | 无法识别的HTTP代码。 |
ERROR_OFFLINE9+ | number | 是 | 否 | 网络未连接。 |
ERROR_UNSUPPORTED_NETWORK_TYPE9+ | number | 是 | 否 | 网络类型不匹配。 |
ERROR_UNKNOWN7+ | number | 是 | 否 | 未知错误。 |
PAUSED_QUEUED_FOR_WIFI7+ | number | 是 | 否 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 |
PAUSED_UNKNOWN7+ | number | 是 | 否 | 未知原因导致暂停下载。 |
PAUSED_WAITING_FOR_NETWORK7+ | number | 是 | 否 | 由于网络问题（例如网络断开）而暂停下载。 |
PAUSED_WAITING_TO_RETRY7+ | number | 是 | 否 | 发生网络错误，将重试下载会话。 |
SESSION_FAILED7+ | number | 是 | 否 | 下载会话已失败，将不会重试。 |
SESSION_PAUSED7+ | number | 是 | 否 | 下载会话已暂停。 |
SESSION_PENDING7+ | number | 是 | 否 | 正在调度下载会话。 |
SESSION_RUNNING7+ | number | 是 | 否 | 下载会话正在进行中。 |
SESSION_SUCCESSFUL7+ | number | 是 | 否 | 下载会话已完成。 |
request.uploadFile9+
uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask>
上传，异步方法，使用promise形式返回结果。
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
context | 是 | 基于应用程序的上下文。 | |
config | 是 | 上传的配置信息。 |
返回值：
类型 | 说明 |
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形式返回结果。
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
context | 是 | 基于应用程序的上下文。 | |
config | 是 | 上传的配置信息。 | |
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模型下使用
说明
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
config | 是 | 上传的配置信息。 |
返回值：
类型 | 说明 |
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模型下使用
说明
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
config | 是 | 上传的配置信息。 | |
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;
});
request.upload(deprecated)
upload(context: BaseContext, config: UploadConfig): Promise<UploadTask>
上传，异步方法，使用promise形式返回结果。
说明
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
context | 是 | 基于应用程序的上下文。 | |
config | 是 | 上传的配置信息。 |
返回值：
类型 | 说明 |
Promise<UploadTask> | 返回上传任务。 |
示例：
let uploadTask;
let uploadConfig = {
url: 'https://patch',
header: { key1: "value1", key2: "value2" },
method: "POST",
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
};
request.upload(globalThis.abilityContext, uploadConfig).then((data) => {
uploadTask = data;
}).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
});
request.upload(deprecated)
upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void
上传，异步方法，使用callback形式返回结果。
说明
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
context | 是 | 基于应用程序的上下文。 | |
config | 是 | 上传的配置信息。 | |
callback | AsyncCallback<UploadTask> | 是 | 回调函数，异步返回UploadTask对象。 |
示例：
let uploadTask;
let uploadConfig = {
url: 'https://patch',
header: { key1: "value1", key2: "value2" },
method: "POST",
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
};
request.upload(globalThis.abilityContext, uploadConfig, (err, data) => {
if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return;
}
uploadTask = data;
});
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。 |
示例：
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
参数：
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应头）。 |
callback | function | 是 | HTTP Response Header事件的回调函数。 |
回调函数的参数：
参数名 | 类型 | 必填 | 说明 |
header | object | 是 | HTTP Response Header。 |
示例：
uploadTask.on('headerReceive', function callback(headers){
console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);
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> | 是 | 上传任务返回结果 |
示例：
uploadTask.on('complete', function callback(taskStates) {
for (let i = 0; i < taskStates.length; i++ ) {
console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
}
}
);
uploadTask.on('fail', function callback(taskStates) {
for (let i = 0; i < taskStates.length; i++ ) {
console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
}
}
);
off('progress')
off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void
关闭上传任务监听，异步方法，使用callback形式返回结果。
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 |
callback | function | 否 | 上传任务的回调函数。 |
回调函数的参数：
参数名 | 类型 | 必填 | 说明 |
uploadedSize | number | 是 | 当前已上传文件的大小，单位为KB。 |
totalSize | number | 是 | 上传文件的总大小，单位为KB。 |
示例：
off('headerReceive')7+
off(type: 'headerReceive', callback?: (header: object) => void): void
关闭上传任务监听，异步方法，使用callback形式返回结果。
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 |
callback | function | 否 | HTTP Response Header事件的回调函数。 |
回调函数的参数：
参数名 | 类型 | 必填 | 说明 |
header | object | 是 | HTTP Response Header。 |
示例：
uploadTask.off('progress', function callback(uploadedSize, totalSize) {
console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize);
}
);
off('complete' | 'fail')9+
off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void;
关闭上传任务监听，异步方法，使用callback形式返回结果。
需要权限：ohos.permission.INTERNET
系统能力: SystemCapability.MiscServices.Upload
参数：
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。 |
callback | Callback<Array<TaskState>> | 否 | 上传任务完成或失败的回调函数。 |
回调函数的参数
参数名 | 类型 | 必填 | 说明 |
taskstates | Array<TaskState> | 是 | 上传任务返回结果 |
示例：
uploadTask.off('complete', function callback(taskStates) {
for (let i = 0; i < taskStates.length; i++ ) {
console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
}
}
);
uploadTask.off('fail', function callback(taskStates) {
for (let i = 0; i < taskStates.length; i++ ) {
console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
}
}
);
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形式返回结果。
说明
需要权限：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形式返回结果。
说明
需要权限：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+
需要权限：ohos.permission.INTERNET
系统能力: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
名称 | 类型 | 必填 | 说明 |
path | string | 是 | 文件路径 |
responseCode | number | 是 | 上传任务返回值 |
message | string | 是 | 上传任务结果描述信息 |
已于2023-4-7 15:55:19修改
赞
收藏
回复
相关推荐
