Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 fa9affed 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!12245 【仅md格式规范】system.request文档整改 

Merge pull request !12245 from ann_lesley/master
上级 db2f54f2 3aa18cdf
隐藏空白更改
内联 并排
Showing with 202 addition and 134 deletion
zh-cn/application-dev/reference/apis/js-apis-system-request.md
浏览文件 @ fa9affed
# 上传下载 # 上传下载
system.request部件主要给应用提供上传下载文件的基础能力。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - 从API Version 6开始，该接口不再维护，推荐使用新接口[`@ohos.request`](js-apis-request.md)。 > - 从API Version 9开始所有接口不再维护，推荐使用新接口[`@ohos.request`](js-apis-request.md)。
> >
> - 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块 ## 导入模块
...@@ -13,179 +15,245 @@ ...@@ -13,179 +15,245 @@
import request from '@system.request'; import request from '@system.request';
``` ```
## 权限列表 ## request.upload
ohos.permission.INTERNET。 upload(options: UploadRequestOptions): void
上传文件，无返回值。
## request.upload **系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload
upload(Object): void **参数：**
上传文件。 | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| options | [UploadRequestOptions](#uploadrequestoptions) | 是 | 上传的配置信息。 |
**参数：** **示例：**
| 参数名 | 类型 | 必填 | 说明 | ```js
| -------- | -------- | -------- | -------- | let uploadRequestOptions = {
| url | string | 是 | 上传服务器地址。 | url: 'http://www.path.com',
| header | Object | 否 | 请求头。 | method: 'POST',
| method | string | 否 | 请求方法：POST、PUT。缺省POST。 | files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
| files | Array<File> | 是 | 待上传文件列表。请使用multipart/form-data进行提交。 | data: [{ name: "name123", value: "123" }],
| data | Array<RequestData> | 否 | 请求的表单数据。 | success: function(data) {
| success | Function | 否 | 接口调用成功的回调函数。 | console.info(' upload success, code:' + JSON.stringify(data));
| fail | Function | 否 | 接口调用失败的回调函数。 | },
| complete | Function | 否 | 接口调用结束的回调函数。 | fail: function(data, code) {
console.info(' upload fail data: ' + data + 'code: ' + code);
},
complete: function (){
console.info(' upload complete');
}
}
try {
request.upload(uploadRequestOptions);
console.info('upload start ');
} catch(err) {
console.info(' upload err:' + err);
}
```
**表1** File ## UploadRequestOptions
| 参数名 | 类型 | 必填 | 说明 | **系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
| -------- | -------- | -------- | -------- |
| filename | string | 否 | multipart 提交时，请求头中的文件名。 |
| name | string | 否 | multipart 提交时，表单项目的名称，缺省为file。 |
| uri | string | 是 | 文件的本地存储路径。 |
| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
**表2** RequestData
| 参数名 | 类型 | 必填 | 说明 | | 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| name | string | 是 | 表示form 元素的名称。 | | url | string | 是 | 上传服务器地址。 |
| value | string | 是 | 表示form 元素的值。 | | data | Array<[RequestData](#requestdata)> | 否 | 请求的表单数据。 |
| files | Array<[RequestFile](#requestfile)> | 是 | 待上传文件列表。请使用multipart/form-data进行提交。 |
| header | Object | 否 | 请求头。 |
| method | string | 否 | 请求方法：POST、PUT。缺省POST。 |
| success | Function | 否 | 接口调用成功的回调函数。 |
| fail | Function | 否 | 接口调用失败的回调函数。 |
| complete | Function | 否 | 接口调用结束的回调函数。 |
success返回值： **success参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | [UploadResponse](#uploadresponse) | 是 | 上传任务成功返回信息。 |
| 参数名 | 类型 | 说明 | **fail参数：**
| -------- | -------- | -------- | | 参数名 | 类型 | 必填 | 说明 |
| code | number | 服务器返回的HTTP状态码。 | | -------- | -------- | -------- | -------- |
| data | string | 服务器返回的内容。根据返回头内容中的type决定该值的类型。 | | data | any | 是 | 上传任务失败返回header信息。 |
| headers | Object | 服务器返回的返回头内容。 | | code | number | 是 | 上传任务失败返回HTTP状态码。 |
fail返回值中的data中的code为HTTP状态码。
**示例：**
``` ## UploadResponse
export default {
upLoad() {
request.upload({
url: 'http://www.path.com',
files: [
{
uri: 'internal://cache/path/to/file.txt',
name: 'file',
filename: 'file.txt',
},
],
data:[
{
name: 'name1',
value: 'value',
},
],
success: function(data) {
console.log('upload success, code:' + data.code);
},
fail: function() {
console.log('upload fail');
},
});
}
}
```
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
## request.download | 名称 | 类型 | 说明 |
| -------- | -------- | -------- |
| code | number | 服务器返回的HTTP状态码。 |
| data | string | 服务器返回的内容。根据返回头内容中的type决定该值的类型。 |
| headers | Object | 服务器返回的返回头内容。 |
download(Object): void
下载文件。 ## RequestFile
**参数：** **系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| filename | string | 否 | multipart 提交时，请求头中的文件名。 |
| name | string | 否 | multipart 提交时，表单项目的名称，缺省为file。 |
| uri | string | 是 | 文件的本地存储路径。 |
| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
## RequestData
**系统能力**: SystemCapability.MiscServices.Upload。
| 参数名 | 类型 | 必填 | 说明 | | 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | 是 | 资源地址。 | | name | string | 是 | 表示form 元素的名称。 |
| header | Object | 否 | 请求头。 | | value | string | 是 | 表示form 元素的值。 |
| description | string | 否 | 资源地址的下载描述，默认为文件名称。 |
| filename | string | 否 | 本次下载文件的名称。默认从本次请求或资源地址中获取。 |
| success | Function | 否 | 接口调用成功的回调函数。 |
| fail | Function | 否 | 接口调用失败的回调函数。 |
| complete | Function | 否 | 接口调用结束的回调函数。 |
success返回值：
| 参数名 | 类型 | 说明 |
| -------- | -------- | -------- |
| token | string | 表示下载的 token，获取下载状态的依据。 |
fail返回错误代码： ## request.download
download(options: DownloadRequestOptions): void
下载文件，无返回值。
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
**参数：**
| 错误码 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | | -------- | -------- | -------- | -------- |
| 400 | 表示下载任务失败。 | | options | [DownloadRequestOptions](#downloadrequestoptions) | 是 | 下载的配置信息。 |
**示例：** **示例：**
``` ```js
export default { let downloadRequestOptions = {
downLoad() { url: 'http://www.path.com',
request.download({ filename: 'requestSystenTest',
url: 'http://www.path.com', header: '',
success: function(data) { description: 'this is requeSystem download response',
console.log('call success callback success: ' + data.token); success: function(data) {
}, console.info(' download success, code:' + JSON.stringify(data));
fail: function(data, code) { },
console.log('handling fail'); fail: function(data, code) {
}, console.info(' download fail data: ' + data + 'code: ' + code);
}); },
complete: function (){
console.info(' download complete');
}
} }
} try {
``` request.download(downloadRequestOptions);
console.info('download start ');
} catch(err) {
console.info(' download err:' + err);
}
```
## request.onDownloadComplete ## DownloadRequestOptions
onDownloadComplete(Object): void **系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
获取下载任务状态。 | 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| url | string | 是 | 资源地址。 |
| filename | string | 否 | 本次下载文件的名称。默认从本次请求或资源地址中获取。 |
| header | Object | 否 | 请求头。 |
| description | string | 否 | 资源地址的下载描述，默认为文件名称。 |
| success | Function | 否 | 接口调用成功的回调函数。 |
| fail | Function | 否 | 接口调用失败的回调函数。 |
| complete | Function | 否 | 接口调用结束的回调函数。 |
**参数：** **success参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | [DownloadResponse](#downloadresponse) | 是 | 下载任务成功返回信息。 |
**fail参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | any | 是 | 下载任务失败返回header信息。 |
| code | number | 是 | 下载任务失败返回HTTP状态码。 |
## DownloadResponse
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
| 名称 | 类型 | 说明 |
| -------- | -------- | -------- |
| token | string | 表示下载的token，获取下载状态的依据。 |
## request.onDownloadComplete
| 参数名 | 类型 | 必填 | 说明 | onDownloadComplete(options: OnDownloadCompleteOptions): void
| -------- | -------- | -------- | -------- |
| token | string | 是 | download 接口返回的结果 token。 |
| success | Function | 否 | 接口调用成功的回调函数。 |
| fail | Function | 否 | 接口调用失败的回调函数。 |
| complete | Function | 否 | 接口调用结束的回调函数。 |
success返回值： 获取下载任务状态，无返回值。
| 参数名 | 类型 | 说明 | **系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
| -------- | -------- | -------- |
| uri | string | 表示下载文件的uri。 |
fail返回错误代码： **参数：**
| 错误码 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | | -------- | -------- | -------- | -------- |
| 400 | 表示下载任务失败。 | | options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | 是 | 监听下载任务的配置信息。 |
| 401 | 表示不存在该下载任务。 |
**示例：** **示例：**
``` ```js
export default { let onDownloadCompleteOptions = {
onDownloadComplete() { token: 'token-index',
request.onDownloadComplete({ success: function(data) {
token: 'token-index', console.info(' download success, code:' + JSON.stringify(data));
success: function(data) { },
console.log('download success, uri:' + data.uri); fail: function(data, code) {
}, console.info(' download fail data: ' + data + 'code: ' + code);
fail: function(data, code) { },
console.log('download fail'); complete: function (){
}, console.info(' download complete');
}); }
} }
} request.onDownloadComplete(onDownloadCompleteOptions);
``` ```
\ No newline at end of file
## OnDownloadCompleteOptions
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| token | string | 是 | download 接口返回的结果 token。 |
| success | Function | 否 | 接口调用成功的回调函数。 |
| fail | Function | 否 | 接口调用失败的回调函数。 |
| complete | Function | 否 | 接口调用结束的回调函数。 |
**success参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | [OnDownloadCompleteResponse](#ondownloadcompleteresponse) | 是 | 下载任务成功返回信息。 |
**fail参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | any | 是 | 下载任务失败返回header信息。 |
| code | number | 是 | 下载任务失败返回HTTP状态码。 |
## OnDownloadCompleteResponse
**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
| 名称 | 类型 | 说明 |
| -------- | -------- | -------- |
| uri | string | 表示下载文件的uri。 |
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或