Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

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

!13101 翻译完成 12245 

Merge pull request !13101 from ester.zhou/TR-12245
上级 34ed0238 4694bb87
隐藏空白更改
内联 并排
Showing with 204 addition and 136 deletion
en/application-dev/reference/apis/js-apis-system-request.md
浏览文件 @ 020714bf
# Uploading and Downloading
# @system.request
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note：**
> - 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.
The **system.request** module provides applications with basic upload and download capabilities.
> **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
......@@ -13,179 +15,245 @@
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 |
| -------- | -------- | -------- | -------- |
| url | string | Yes | URL of the upload server. |
| header | Object | No | Request header. |
| method | string | No | Request methods available: **POST** and **PUT**. The default value is **POST**. |
| files | Array<File> | Yes | List of files to upload, which is submitted through **multipart/form-data**. |
| data | Array<RequestData> | No | Form data in the request body. |
| success | Function | No | Called when the download task is complete. |
| fail | Function | No | Called when downloading fails or the task does not exist. |
| complete | Function | No | Called when the execution is complete. |
```js
let uploadRequestOptions = {
url: 'http://www.path.com',
method: 'POST',
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
success: function(data) {
console.info(' upload success, code:' + JSON.stringify(data));
},
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 |
| -------- | -------- | -------- | -------- |
| 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 storage path of a file. |
| type | string | No | Type of the file content. By default, the type is obtained based on the suffix of the file name or URI. |
## UploadRequestOptions
**Table 2** RequestData
**System capability**: SystemCapability.MiscServices.Upload
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| name | string | Yes | Name of the form element |
| value | string | Yes | Value of the form 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<[RequestData](#requestdata)> | No| Form data in the request body.|
| files | Array<[RequestFile](#requestfile)> | 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 |
| -------- | -------- | -------- |
| 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. |
**success parameter**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| data | [UploadResponse](#uploadresponse) | Yes| Information returned when the upload task is successful.|
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 |
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. |
| header | Object | No | Request header. |
| description | string | No | Download description. The default value is the file name. |
| filename | string | No | Name of the file to download. The value is obtained from the current request or resource URL by default. |
| success | Function | No | Called when the download task is complete. |
| fail | Function | No | Called when downloading fails or the task does not exist. |
| complete | Function | No | Called when the execution is complete. |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| name | string | Yes| Name of the form element.|
| value | string | Yes| Value of the form element.|
Return values of the **success** callback
| Name | Type | Description |
| -------- | -------- | -------- |
| token | string | Download token, which is used to obtain the download 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 Code | Description |
| -------- | -------- |
| 400 | Download task failed |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| options | [DownloadRequestOptions](#downloadrequestoptions) | Yes| Download configurations.|
**Example**
```
export default {
downLoad() {
request.download({
url: 'http://www.path.com',
success: function(data) {
console.log('call success callback success: ' + data.token);
},
fail: function(data, code) {
console.log('handling fail');
},
});
```js
let downloadRequestOptions = {
url: 'http://www.path.com',
filename: 'requestSystenTest',
header: '',
description: 'this is requeSystem download response',
success: function(data) {
console.info(' download success, code:' + JSON.stringify(data));
},
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 |
| -------- | -------- | -------- | -------- |
| token | string | Yes | Token of the result returned by the download method |
| success | Function | No | Called when the download task is complete. |
| fail | Function | No | Called when downloading fails or the task does not exist. |
| complete | Function | No | Called when the execution is complete. |
onDownloadComplete(options: OnDownloadCompleteOptions): void
Return values of the **success** callback
Listens for download task status. This API returns no value.
| Name | Type | Description |
| -------- | -------- | -------- |
| uri | string | URI of the download file |
**System capability**: SystemCapability.MiscServices.Download
One of the following error codes will be returned if the listening fails.
**Parameters**
| Error Code | Description |
| -------- | -------- |
| 400 | Download task failed |
| 401 | Download task not exist |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | Yes| Configurations of the download task.|
**Example**
```
export default {
onDownloadComplete() {
request.onDownloadComplete({
token: 'token-index',
success: function(data) {
console.log('download success, uri:' + data.uri);
},
fail: function(data, code) {
console.log('download fail');
},
});
```js
let onDownloadCompleteOptions = {
token: 'token-index',
success: function(data) {
console.info(' download success, code:' + JSON.stringify(data));
},
fail: function(data, code) {
console.info(' download fail data: ' + data + 'code: ' + code);
},
complete: function (){
console.info(' download complete');
}
}
}
```
\ No newline at end of file
request.onDownloadComplete(onDownloadCompleteOptions);
```
## 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.
先完成此消息的编辑！
想要评论请 注册 或