Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 4694bb87 编写于 作者: E esterzhou
浏览文件
操作

update doc (12245) 

Signed-off-by: Nesterzhou <ester.zhou@huawei.com>
上级 8c512bd4
隐藏空白更改
内联 并排
Showing with 204 addition and 136 deletion
en/application-dev/reference/apis/js-apis-system-request.md
浏览文件 @ 4694bb87
# Uploading and Downloading # @system.request
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note：** The **system.request** module provides applications with basic upload and download capabilities.
> - The APIs of this module are no longer maintained since API version 6. It is recommended that you use [`@ohos.request`](js-apis-request.md) instead.
> **NOTE**
> - The APIs of this module are deprecated since API version 9. You are advised to use [`@ohos.request`](js-apis-request.md) instead.
> >
> - The initial APIs of this module are supported since API version 4. Newly added APIs will be marked with a superscript to indicate their earliest API version. > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -13,179 +15,245 @@ ...@@ -13,179 +15,245 @@
import request from '@system.request'; import request from '@system.request';
``` ```
## Required Permissions ## request.upload
ohos.permission.INTERNET. upload(options: UploadRequestOptions): void
Uploads a file. This API returns no value.
## request.upload **System capability**: SystemCapability.MiscServices.Upload
upload(Object): void **Parameters**
Uploads files. | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| options | [UploadRequestOptions](#uploadrequestoptions) | Yes| Upload configurations.|
**Parameters** **Example**
| Name | Type | Mandatory | Description | ```js
| -------- | -------- | -------- | -------- | let uploadRequestOptions = {
| url | string | Yes | URL&nbsp;of&nbsp;the&nbsp;upload&nbsp;server. | url: 'http://www.path.com',
| header | Object | No | Request&nbsp;header. | method: 'POST',
| method | string | No | Request&nbsp;methods&nbsp;available:&nbsp;**POST**&nbsp;and&nbsp;**PUT**.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**POST**. | files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
| files | Array&lt;File&gt; | Yes | List&nbsp;of&nbsp;files&nbsp;to&nbsp;upload,&nbsp;which&nbsp;is&nbsp;submitted&nbsp;through&nbsp;**multipart/form-data**. | data: [{ name: "name123", value: "123" }],
| data | Array&lt;RequestData&gt; | No | Form&nbsp;data&nbsp;in&nbsp;the&nbsp;request&nbsp;body. | success: function(data) {
| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;download&nbsp;task&nbsp;is&nbsp;complete. | console.info(' upload success, code:' + JSON.stringify(data));
| fail | Function | No | Called&nbsp;when&nbsp;downloading&nbsp;fails&nbsp;or&nbsp;the&nbsp;task&nbsp;does&nbsp;not&nbsp;exist. | },
| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete. | 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);
}
```
**Table 1** File
| Name | Type | Mandatory | Description | ## UploadRequestOptions
| -------- | -------- | -------- | -------- |
| filename | string | No | File&nbsp;name&nbsp;in&nbsp;the&nbsp;header&nbsp;when&nbsp;**multipart**&nbsp;is&nbsp;used. |
| name | string | No | Name&nbsp;of&nbsp;a&nbsp;form&nbsp;item&nbsp;when&nbsp;**multipart**&nbsp;is&nbsp;used.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**file**. |
| uri | string | Yes | Local&nbsp;storage&nbsp;path&nbsp;of&nbsp;a&nbsp;file. |
| type | string | No | Type&nbsp;of&nbsp;the&nbsp;file&nbsp;content.&nbsp;By&nbsp;default,&nbsp;the&nbsp;type&nbsp;is&nbsp;obtained&nbsp;based&nbsp;on&nbsp;the&nbsp;suffix&nbsp;of&nbsp;the&nbsp;file&nbsp;name&nbsp;or&nbsp;URI. |
**Table 2** RequestData **System capability**: SystemCapability.MiscServices.Upload
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| name | string | Yes | Name&nbsp;of&nbsp;the&nbsp;form&nbsp;element |
| value | string | Yes | Value&nbsp;of&nbsp;the&nbsp;form&nbsp;element |
When the files are successfully uploaded, the following values will be returned. | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes| URL of the upload server.|
| data | Array&lt;[RequestData](#requestdata)&gt; | No| Form data in the request body.|
| files | Array&lt;[RequestFile](#requestfile)&gt; | Yes| List of files to upload, which is submitted through **multipart/form-data**.|
| header | Object | No| Request header.|
| method | string | No| Request method, which can be **'POST'** or **'PUT'**. The default value is **POST**.|
| success | Function | No| Called when API call is successful.|
| fail | Function | No| Called when API call has failed.|
| complete | Function | No| Called when API call is complete.|
| Name | Type | Description | **success parameter**
| -------- | -------- | -------- | | Name| Type| Mandatory| Description|
| code | number | HTTP&nbsp;status&nbsp;code&nbsp;returned&nbsp;by&nbsp;the&nbsp;server. | | -------- | -------- | -------- | -------- |
| data | string | Content&nbsp;returned&nbsp;by&nbsp;the&nbsp;server.&nbsp;The&nbsp;value&nbsp;type&nbsp;is&nbsp;determined&nbsp;by&nbsp;the&nbsp;type&nbsp;in&nbsp;the&nbsp;returned&nbsp;headers. | | data | [UploadResponse](#uploadresponse) | Yes| Information returned when the upload task is successful.|
| headers | Object | Headers&nbsp;returned&nbsp;by&nbsp;the&nbsp;server. |
When the files fail to be uploaded, an HTTP status code is returned in **code** of **data**. **fail parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | any | Yes| Header information returned when the upload task fails.|
| code | number | Yes| HTTP status code returned when the upload task fails.|
**Example**
```
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');
},
});
}
}
```
## UploadResponse
## request.download **System capability**: SystemCapability.MiscServices.Upload
download(Object): void | Name| Type| Description|
| -------- | -------- | -------- |
| code | number | HTTP status code returned by the server.|
| data | string | Content returned by the server. The value type is determined by the type in the returned headers.|
| headers | Object | Headers returned by the server.|
Downloads files.
**Parameters** ## RequestFile
**System capability**: SystemCapability.MiscServices.Upload
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| filename | string | No| File name in the header when **multipart** is used.|
| name | string | No| Name of a form item when **multipart** is used. The default value is **file**.|
| uri | string | Yes| Local path for storing files.|
| type | string | No| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.|
## RequestData
**System capability**: SystemCapability.MiscServices.Upload
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | Yes | Resource&nbsp;URL. | | name | string | Yes| Name of the form element.|
| header | Object | No | Request&nbsp;header. | | value | string | Yes| Value of the form element.|
| description | string | No | Download&nbsp;description.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;the&nbsp;file&nbsp;name. |
| filename | string | No | Name&nbsp;of&nbsp;the&nbsp;file&nbsp;to&nbsp;download.&nbsp;The&nbsp;value&nbsp;is&nbsp;obtained&nbsp;from&nbsp;the&nbsp;current&nbsp;request&nbsp;or&nbsp;resource&nbsp;URL&nbsp;by&nbsp;default. |
| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;download&nbsp;task&nbsp;is&nbsp;complete. |
| fail | Function | No | Called&nbsp;when&nbsp;downloading&nbsp;fails&nbsp;or&nbsp;the&nbsp;task&nbsp;does&nbsp;not&nbsp;exist. |
| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete. |
Return values of the **success** callback
| Name | Type | Description |
| -------- | -------- | -------- |
| token | string | Download&nbsp;token,&nbsp;which&nbsp;is&nbsp;used&nbsp;to&nbsp;obtain&nbsp;the&nbsp;download&nbsp;status. |
One of the following error codes will be returned if the operation fails. ## request.download
download(options: DownloadRequestOptions): void
Downloads a file. This API returns no value.
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
| Error&nbsp;Code | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | | -------- | -------- | -------- | -------- |
| 400 | Download&nbsp;task&nbsp;failed | | options | [DownloadRequestOptions](#downloadrequestoptions) | Yes| Download configurations.|
**Example** **Example**
``` ```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 **System capability**: SystemCapability.MiscServices.Download
Listens to download task status. | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes| Resource URL.|
| filename | string | No| Name of the file to download. The value is obtained from the current request or resource URL by default.|
| header | Object | No| Request header.|
| description | string | No| Download description. The default value is the file name.|
| success | Function | No| Called when API call is successful.|
| fail | Function | No| Called when API call has failed.|
| complete | Function | No| Called when API call is complete.|
**Parameters** **success parameter**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | [DownloadResponse](#downloadresponse) | Yes| Information returned when the download task is successful.|
**fail parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | any | Yes| Header information returned when the download task fails.|
| code | number | Yes| HTTP status code returned when the download task fails.|
## DownloadResponse
**System capability**: SystemCapability.MiscServices.Download
| Name| Type| Description|
| -------- | -------- | -------- |
| token | string | Download token, which is used to obtain the download status|
## request.onDownloadComplete
| Name | Type | Mandatory | Description | onDownloadComplete(options: OnDownloadCompleteOptions): void
| -------- | -------- | -------- | -------- |
| token | string | Yes | Token&nbsp;of&nbsp;the&nbsp;result&nbsp;returned&nbsp;by&nbsp;the&nbsp;download&nbsp;method |
| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;download&nbsp;task&nbsp;is&nbsp;complete. |
| fail | Function | No | Called&nbsp;when&nbsp;downloading&nbsp;fails&nbsp;or&nbsp;the&nbsp;task&nbsp;does&nbsp;not&nbsp;exist. |
| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete. |
Return values of the **success** callback Listens for download task status. This API returns no value.
| Name | Type | Description | **System capability**: SystemCapability.MiscServices.Download
| -------- | -------- | -------- |
| uri | string | URI&nbsp;of&nbsp;the&nbsp;download&nbsp;file |
One of the following error codes will be returned if the listening fails. **Parameters**
| Error&nbsp;Code | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | | -------- | -------- | -------- | -------- |
| 400 | Download&nbsp;task&nbsp;failed | | options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | Yes| Configurations of the download task.|
| 401 | Download&nbsp;task&nbsp;not&nbsp;exist |
**Example** **Example**
``` ```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
**System capability**: SystemCapability.MiscServices.Download
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| token | string | Yes| Result token returned by the download API.|
| success | Function | No| Called when API call is successful.|
| fail | Function | No| Called when API call has failed.|
| complete | Function | No| Called when API call is complete.|
**success parameter**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | [OnDownloadCompleteResponse](#ondownloadcompleteresponse) | Yes| Information returned when the download task is successful.|
**fail parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | any | Yes| Header information returned when the download task fails.|
| code | number | Yes| HTTP status code returned when the download task fails.|
## OnDownloadCompleteResponse
**System capability**: SystemCapability.MiscServices.Download
| Name| Type| Description|
| -------- | -------- | -------- |
| uri | string | URI of the download file.|
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或