Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
“2055c16db32f9ccda7221d3e5eed3958603874d3”上不存在“git@gitcode.net:BaiXuePrincess/Paddle.git”
提交 6445a842 编写于 作者: E ester.zhou
浏览文件
操作

update js-apis-request.md (7457) 

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 ebe29125
显示空白变更内容
内联 并排
Showing with 351 addition and 179 deletion
en/application-dev/reference/apis/js-apis-request.md
浏览文件 @ 6445a842
...@@ -17,9 +17,9 @@ import request from '@ohos.request'; ...@@ -17,9 +17,9 @@ import request from '@ohos.request';
## Constraints ## Constraints
HTTPS is supported by default. To support HTTP, you need to add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**. HTTPS is supported by default in the FA model. To support HTTP, add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**.
``` ```js
var config = { var config = {
"deviceConfig": { "deviceConfig": {
"default": { "default": {
...@@ -32,6 +32,9 @@ var config = { ...@@ -32,6 +32,9 @@ var config = {
} }
``` ```
The **cleartextTraffic** attribute is not involved during the development of applications in the stage model.
## Constants ## Constants
...@@ -39,28 +42,28 @@ var config = { ...@@ -39,28 +42,28 @@ var config = {
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
| Name | Type | Readable | Writable | Description | | Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| NETWORK_MOBILE | number | Yes | No | Whether download is allowed when the cellular network is used. | | NETWORK_MOBILE | number | Yes| No| Whether download is allowed on a mobile network.|
| NETWORK_WIFI | number | Yes | No | Whether download is allowed on a WLAN. | | NETWORK_WIFI | number | Yes| No| Whether download is allowed on a WLAN.|
| ERROR_CANNOT_RESUME<sup>7+</sup> | number | Yes | No | Failure to resume the download due to an error. | | ERROR_CANNOT_RESUME<sup>7+</sup> | number | Yes| No| Failure to resume the download due to an error.|
| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes | No | Failure to find a storage device such as a memory card. | | ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes| No| Failure to find a storage device such as a memory card.|
| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | Yes | No | Failure to download the file because it already exists. | | ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | Yes| No| Failure to download the file because it already exists.|
| ERROR_FILE_ERROR<sup>7+</sup> | number | Yes | No | File operation failure. | | ERROR_FILE_ERROR<sup>7+</sup> | number | Yes| No| File operation failure.|
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP transmission failure. | | ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes| No| HTTP transmission failure.|
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes | No | Insufficient storage space. | | ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes| No| Insufficient storage space.|
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | Yes | No | Error caused by too many network redirections. | | ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | Yes| No| Error caused by too many network redirections.|
| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes | No | Unidentified HTTP code. | | ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes| No| Unidentified HTTP code.|
| ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown error. | | ERROR_UNKNOWN<sup>7+</sup> | number | Yes| No| Unknown error.|
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes | No | Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a cellular network session. | | PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes| No| Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.|
| PAUSED_UNKNOWN<sup>7+</sup> | number | Yes | No | Download paused due to unknown reasons. | | PAUSED_UNKNOWN<sup>7+</sup> | number | Yes| No| Download paused due to unknown reasons.|
| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | Yes | No | Download paused due to a network connection problem, for example, network disconnection. | | PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | Yes| No| Download paused due to a network connection problem, for example, network disconnection.|
| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | Yes | No | Download paused and then retried. | | PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | Yes| No| Download paused and then retried.|
| SESSION_FAILED<sup>7+</sup> | number | Yes | No | Download failure without retry. | | SESSION_FAILED<sup>7+</sup> | number | Yes| No| Download failure without retry.|
| SESSION_PAUSED<sup>7+</sup> | number | Yes | No | Download paused. | | SESSION_PAUSED<sup>7+</sup> | number | Yes| No| Download paused.|
| SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download pending. | | SESSION_PENDING<sup>7+</sup> | number | Yes| No| Download pending.|
| SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download in progress. | | SESSION_RUNNING<sup>7+</sup> | number | Yes| No| Download in progress.|
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful download. | | SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes| No| Successful download.|
## request.upload ## request.upload
...@@ -69,30 +72,36 @@ upload(config: UploadConfig): Promise&lt;UploadTask&gt; ...@@ -69,30 +72,36 @@ upload(config: UploadConfig): Promise&lt;UploadTask&gt;
Uploads files. This API uses a promise to return the result. Uploads files. This API uses a promise to return the result.
This API can be used only in the FA model.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. | | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;[UploadTask](#uploadtask)&gt; | Promise used to return the **UploadTask** object. | | Promise&lt;[UploadTask](#uploadtask)&gt; | Promise used to return the **UploadTask** object.|
**Example** **Example**
```js ```js
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; let uploadTask;
request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }).then((data) => { 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; uploadTask = data;
}).catch((err) => { }).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
...@@ -106,25 +115,31 @@ upload(config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void ...@@ -106,25 +115,31 @@ upload(config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void
Uploads files. This API uses an asynchronous callback to return the result. Uploads files. This API uses an asynchronous callback to return the result.
This API can be used only in the FA model.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. | | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No | Callback used to return the **UploadTask** object. | | callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No| Callback used to return the **UploadTask** object.|
**Example** **Example**
```js ```js
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; let uploadTask;
request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }, (err, data) => { 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) { if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return; return;
...@@ -132,8 +147,87 @@ Uploads files. This API uses an asynchronous callback to return the result. ...@@ -132,8 +147,87 @@ Uploads files. This API uses an asynchronous callback to return the result.
uploadTask = data; uploadTask = data;
}); });
``` ```
## request.upload<sup>9+</sup>
upload(context: BaseContext, config: UploadConfig): Promise&lt;UploadTask&gt;
Uploads files. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | BaseContext | Yes| Application-based context.|
| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;[UploadTask](#uploadtask)&gt; | Promise used to return the **UploadTask** object.|
**Example**
```js
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<sup>9+</sup>
upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void
Uploads files. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | BaseContext | Yes| Application-based context.|
| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No| Callback used to return the **UploadTask** object.|
**Example**
```js
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
Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object. Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object.
...@@ -143,7 +237,7 @@ Implements file uploads. Before using any APIs of this class, you must obtain an ...@@ -143,7 +237,7 @@ Implements file uploads. Before using any APIs of this class, you must obtain an
on(type: 'progress', callback:(uploadedSize: number, totalSize: number) =&gt; void): void on(type: 'progress', callback:(uploadedSize: number, totalSize: number) =&gt; void): void
Subscribes to the upload progress event. This API uses an asynchronous callback to return the result. Subscribes to an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -151,17 +245,17 @@ Subscribes to the upload progress event. This API uses an asynchronous callback ...@@ -151,17 +245,17 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **progress** (upload progress). | | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).|
| callback | function | Yes | Callback for the upload progress event. | | callback | function | Yes| Callback for the upload progress event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. | | uploadedSize | number | Yes| Size of the uploaded files, in KB.|
| totalSize | number | Yes | Total size of the files to upload, in KB. | | totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example** **Example**
...@@ -177,7 +271,7 @@ Subscribes to the upload progress event. This API uses an asynchronous callback ...@@ -177,7 +271,7 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
on(type: 'headerReceive', callback: (header: object) =&gt; void): void on(type: 'headerReceive', callback: (header: object) =&gt; void): void
Subscribes to the **headerReceive** event, which is triggered when an HTTP response header is received. This API uses an asynchronous callback to return the result. Subscribes to an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -185,16 +279,16 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo ...@@ -185,16 +279,16 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **'headerReceive'** (response header). | | type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).|
| callback | function | Yes | Callback for the HTTP Response Header event. | | callback | function | Yes| Callback for the HTTP Response Header event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP Response Header. | | header | object | Yes| HTTP Response Header.|
**Example** **Example**
...@@ -210,7 +304,7 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo ...@@ -210,7 +304,7 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) =&gt; void): void off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) =&gt; void): void
Unsubscribes from the upload progress event. This API uses an asynchronous callback to return the result. Unsubscribes from an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -218,17 +312,17 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb ...@@ -218,17 +312,17 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (upload progress). | | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).|
| callback | function | No | Callback for the upload progress event. | | callback | function | No| Callback for the upload progress event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. | | uploadedSize | number | Yes| Size of the uploaded files, in KB.|
| totalSize | number | Yes | Total size of the files to upload, in KB. | | totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example** **Example**
...@@ -244,7 +338,7 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb ...@@ -244,7 +338,7 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
off(type: 'headerReceive', callback?: (header: object) =&gt; void): void off(type: 'headerReceive', callback?: (header: object) =&gt; void): void
Unsubscribes from the **headerReceive** event. This API uses an asynchronous callback to return the result. Unsubscribes from an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -252,16 +346,16 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal ...@@ -252,16 +346,16 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **'headerReceive'** (response header). | | type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).|
| callback | function | No | Callback for the HTTP Response Header event. | | callback | function | No| Callback for the HTTP Response Header event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP Response Header. | | header | object | Yes| HTTP Response Header.|
**Example** **Example**
...@@ -285,9 +379,9 @@ Removes this upload task. This API uses a promise to return the result. ...@@ -285,9 +379,9 @@ Removes this upload task. This API uses a promise to return the result.
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed. | | Promise&lt;boolean&gt; | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed.|
**Example** **Example**
...@@ -316,9 +410,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r ...@@ -316,9 +410,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -339,37 +433,42 @@ Removes this upload task. This API uses an asynchronous callback to return the r ...@@ -339,37 +433,42 @@ Removes this upload task. This API uses an asynchronous callback to return the r
## UploadConfig ## UploadConfig
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. | | url | string | Yes| Resource URL.|
| header | object | Yes | HTTP or HTTPS header added to an upload request. | | header | object | Yes| HTTP or HTTPS header added to an upload request.|
| method | string | Yes | Request method, which can be **POST** or **PUT**. The default value is **POST**. | | method | string | Yes| Request method, which can be **'POST'** or **'PUT'**. The default value is **'POST'**.|
| files | Array&lt;[File](#file)&gt; | Yes | List of files to upload, which is submitted through **multipart/form-data**. | | files | Array&lt;[File](#file)&gt; | Yes| List of files to upload, which is submitted through **multipart/form-data**.|
| data | Array&lt;[RequestData](#requestdata)&gt; | Yes | Form data in the request body. | | data | Array&lt;[RequestData](#requestdata)&gt; | Yes| Form data in the request body.|
## File ## File
**System capability**: SystemCapability.MiscServices.Upload **Required permissions**: ohos.permission.INTERNET
| Name | Type | Mandatory | Description | **System capability**: SystemCapability.MiscServices.Download
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| filename | string | No | File name in the header when **multipart** is used. | | 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**. | | 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.<br/>The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:<br>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br>internal://cache/path/to/file.txt | | uri | string | Yes| Local path for storing files.<br>The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:<br>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br><br>internal://cache/path/to/file.txt |
| type | string | No | Type of the file content. By default, the type is obtained based on the extension of the file name or URI. | | 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 ## RequestData
**System capability**: SystemCapability.MiscServices.Upload **Required permissions**: ohos.permission.INTERNET
| Name | Type | Mandatory | Description | **System capability**: SystemCapability.MiscServices.Download
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| name | string | Yes | Name of a form element. | | name | string | Yes| Name of a form element.|
| value | string | Yes | Value of a form element. | | value | string | Yes| Value of a form element.|
## request.download ## request.download
...@@ -378,21 +477,23 @@ download(config: DownloadConfig): Promise&lt;DownloadTask&gt; ...@@ -378,21 +477,23 @@ download(config: DownloadConfig): Promise&lt;DownloadTask&gt;
Downloads files. This API uses a promise to return the result. Downloads files. This API uses a promise to return the result.
This API can be used only in the FA model.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. | | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise used to return the result. | | Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise used to return the result.|
**Example** **Example**
...@@ -412,16 +513,18 @@ download(config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): v ...@@ -412,16 +513,18 @@ download(config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): v
Downloads files. This API uses an asynchronous callback to return the result. Downloads files. This API uses an asynchronous callback to return the result.
This API can be used only in the FA model.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. | | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No | Callback used to return the result. | | callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No| Callback used to return the result.|
**Example** **Example**
...@@ -437,7 +540,72 @@ Downloads files. This API uses an asynchronous callback to return the result. ...@@ -437,7 +540,72 @@ Downloads files. This API uses an asynchronous callback to return the result.
}); });
``` ```
## request.download<sup>9+</sup>
download(context: BaseContext, config: DownloadConfig): Promise&lt;DownloadTask&gt;
Downloads files. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | BaseContext | Yes| Application-based context.|
| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise used to return the result.|
**Example**
```js
let downloadTask;
request.download(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
downloadTask = data;
}).catch((err) => {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})
```
## request.download<sup>9+</sup>
download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): void;
Downloads files. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | BaseContext | Yes| Application-based context.|
| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No| Callback used to return the result.|
**Example**
```js
let downloadTask;
request.download(globalThis.abilityContext, { 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 ## DownloadTask
Implements file downloads. Implements file downloads.
...@@ -447,7 +615,7 @@ Implements file downloads. ...@@ -447,7 +615,7 @@ Implements file downloads.
on(type: 'progress', callback:(receivedSize: number, totalSize: number) =&gt; void): void on(type: 'progress', callback:(receivedSize: number, totalSize: number) =&gt; void): void
Subscribes to the download progress event. This API uses an asynchronous callback to return the result. Subscribes to a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -455,17 +623,17 @@ Subscribes to the download progress event. This API uses an asynchronous callbac ...@@ -455,17 +623,17 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **'progress'** (download progress). | | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).|
| callback | function | Yes | Callback for the download progress event. | | callback | function | Yes| Callback for the download progress event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. | | receivedSize | number | Yes| Size of the downloaded files, in KB.|
| totalSize | number | Yes | Total size of the files to download, in KB. | | totalSize | number | Yes| Total size of the files to download, in KB.|
**Example** **Example**
...@@ -481,7 +649,7 @@ Subscribes to the download progress event. This API uses an asynchronous callbac ...@@ -481,7 +649,7 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
off(type: 'progress', callback?: (receivedSize: number, totalSize: number) =&gt; void): void off(type: 'progress', callback?: (receivedSize: number, totalSize: number) =&gt; void): void
Unsubscribes from the download progress event. This API uses an asynchronous callback to return the result. Unsubscribes from a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -489,17 +657,17 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal ...@@ -489,17 +657,17 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (download progress). | | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).|
| callback | function | No | Callback for the download progress event. | | callback | function | No| Callback for the download progress event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. | | receivedSize | number | Yes| Size of the downloaded files.|
| totalSize | number | Yes | Total size of the files to download, in KB. | | totalSize | number | Yes| Total size of the files to download.|
**Example** **Example**
...@@ -523,10 +691,10 @@ Subscribes to a download event. This API uses an asynchronous callback to return ...@@ -523,10 +691,10 @@ Subscribes to a download event. This API uses an asynchronous callback to return
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Event type.<br/>- **'complete'**: download task completion event.<br/>- **'pause'**: download task pause event.<br/>- **'remove'**: download task removal event. | | type | string | Yes| Type of the event to subscribe to.<br>- **'complete'**: download task completion event.<br>- **'pause'**: download task pause event.<br>- **'remove'**: download task removal event.|
| callback | function | Yes | Callback used to return the result. | | callback | function | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -542,7 +710,7 @@ Subscribes to a download event. This API uses an asynchronous callback to return ...@@ -542,7 +710,7 @@ Subscribes to a download event. This API uses an asynchronous callback to return
off(type: 'complete'|'pause'|'remove', callback?:() =&gt; void): void off(type: 'complete'|'pause'|'remove', callback?:() =&gt; void): void
Unsubscribes from the download event. This API uses an asynchronous callback to return the result. Unsubscribes from a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -550,10 +718,10 @@ Unsubscribes from the download event. This API uses an asynchronous callback to ...@@ -550,10 +718,10 @@ Unsubscribes from the download event. This API uses an asynchronous callback to
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Event type.<br/>- **'complete'**: download task completion event.<br/>- **'pause'**: download task pause event.<br/>- **'remove'**: download task removal event. | | type | string | Yes| Type of the event to unsubscribe from.<br>- **'complete'**: download task completion event.<br>- **'pause'**: download task pause event.<br>- **'remove'**: download task removal event.|
| callback | function | No | Callback used to return the result. | | callback | function | No| Callback used to return the result.|
**Example** **Example**
...@@ -577,16 +745,16 @@ Subscribes to the download task failure event. This API uses an asynchronous cal ...@@ -577,16 +745,16 @@ Subscribes to the download task failure event. This API uses an asynchronous cal
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the subscribed event. The value is **'fail'** (download failure). | | type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).|
| callback | function | Yes | Callback for the download task failure event. | | callback | function | Yes| Callback for the download task failure event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). | | err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).|
**Example** **Example**
...@@ -610,16 +778,16 @@ Unsubscribes from the download task failure event. This API uses an asynchronous ...@@ -610,16 +778,16 @@ Unsubscribes from the download task failure event. This API uses an asynchronous
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **'fail'** (download failure). | | type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).|
| callback | function | No | Callback for the download task failure event. | | callback | function | No| Callback for the download task failure event.|
**callback** parameters Parameters of the callback function
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). | | err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).|
**Example** **Example**
...@@ -643,9 +811,9 @@ Removes this download task. This API uses a promise to return the result. ...@@ -643,9 +811,9 @@ Removes this download task. This API uses a promise to return the result.
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return the task removal result. | | Promise&lt;boolean&gt; | Promise used to return the task removal result.|
**Example** **Example**
...@@ -674,9 +842,9 @@ Removes this download task. This API uses an asynchronous callback to return the ...@@ -674,9 +842,9 @@ Removes this download task. This API uses an asynchronous callback to return the
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the task removal result. | | callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the task removal result.|
**Example** **Example**
...@@ -706,10 +874,9 @@ Queries this download task. This API uses a promise to return the result. ...@@ -706,10 +874,9 @@ Queries this download task. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
**Parameters** **Parameters**
| Type| Description|
| Type | Description | | -------- | -------- |
| -------- | -------- | | Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information.|
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information. |
**Example** **Example**
...@@ -734,9 +901,9 @@ Queries this download task. This API uses an asynchronous callback to return the ...@@ -734,9 +901,9 @@ Queries this download task. This API uses an asynchronous callback to return the
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | Yes | Callback used to return the download task information. | | callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | Yes| Callback used to return the download task information.|
**Example** **Example**
...@@ -755,7 +922,7 @@ Queries this download task. This API uses an asynchronous callback to return the ...@@ -755,7 +922,7 @@ Queries this download task. This API uses an asynchronous callback to return the
queryMimeType(): Promise&lt;string&gt; queryMimeType(): Promise&lt;string&gt;
Queries **MimeType** of this download task. This API uses a promise to return the result. Queries the **MimeType** of this download task. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -763,9 +930,9 @@ Queries **MimeType** of this download task. This API uses a promise to return th ...@@ -763,9 +930,9 @@ Queries **MimeType** of this download task. This API uses a promise to return th
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;string&gt; | Promise used to return **MimeType** of the download task. | | Promise&lt;string&gt; | Promise used to return the **MimeType** of the download task.|
**Example** **Example**
...@@ -782,7 +949,7 @@ Queries **MimeType** of this download task. This API uses a promise to return th ...@@ -782,7 +949,7 @@ Queries **MimeType** of this download task. This API uses a promise to return th
queryMimeType(callback: AsyncCallback&lt;string&gt;): void; queryMimeType(callback: AsyncCallback&lt;string&gt;): void;
Queries **MimeType** of this download task. This API uses an asynchronous callback to return the result. Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET **Required permissions**: ohos.permission.INTERNET
...@@ -790,9 +957,9 @@ Queries **MimeType** of this download task. This API uses an asynchronous callba ...@@ -790,9 +957,9 @@ Queries **MimeType** of this download task. This API uses an asynchronous callba
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return **MimeType** of the download task. | | callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the **MimeType** of the download task.|
**Example** **Example**
...@@ -819,9 +986,9 @@ Pauses this download task. This API uses a promise to return the result. ...@@ -819,9 +986,9 @@ Pauses this download task. This API uses a promise to return the result.
**Return value** **Return value**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the download task pause result. | | Promise&lt;void&gt; | Promise used to return the download task pause result.|
**Example** **Example**
...@@ -850,9 +1017,9 @@ Pauses this download task. This API uses an asynchronous callback to return the ...@@ -850,9 +1017,9 @@ Pauses this download task. This API uses an asynchronous callback to return the
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -883,9 +1050,9 @@ Resumes this download task. This API uses a promise to return the result. ...@@ -883,9 +1050,9 @@ Resumes this download task. This API uses a promise to return the result.
**Parameters** **Parameters**
| Type | Description | | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. | | Promise&lt;void&gt; | Promise used to return the result.|
**Example** **Example**
...@@ -915,9 +1082,9 @@ Resumes this download task. This API uses an asynchronous callback to return the ...@@ -915,9 +1082,9 @@ Resumes this download task. This API uses an asynchronous callback to return the
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -938,34 +1105,39 @@ Resumes this download task. This API uses an asynchronous callback to return the ...@@ -938,34 +1105,39 @@ Resumes this download task. This API uses an asynchronous callback to return the
## DownloadConfig ## DownloadConfig
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. | | url | string | Yes| Resource URL.|
| header | object | No | HTTP or HTTPS header added to a download request. | | header | object | No| HTTP or HTTPS header added to a download request.|
| enableMetered | boolean | No | Download allowed in metered connections. | | enableMetered | boolean | No| Download allowed in metered connections.|
| enableRoaming | boolean | No | Download allowed on a roaming network. | | enableRoaming | boolean | No| Download allowed on a roaming network.|
| description | string | No | Description of the download session. | | description | string | No| Description of the download session.|
| filePath<sup>7+</sup> | string | No | Download path. (The default path is **'internal://cache/'**.<br/>- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.<br/>- filePath:'test.txt': Files are stored in the default path.<br/>- filePath:'workspace/': The **workspace** directory is created in the default path to store files. | | filePath<sup>7+</sup> | string | No| Download path. (The default path is **'internal://cache/'**.)<br>- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.<br>- filePath:'test.txt': Files are stored in the default path.<br>- filePath:'workspace/': The **workspace** directory is created in the default path to store files.|
| networkType | number | No | Network type allowed for download. | | networkType | number | No| Network type allowed for download.|
| title | string | No | Title of the download session. | | title | string | No| Title of the download session.|
| background | boolean | No| Whether to enable the background task notification. When this parameter is enabled, the download status is displayed in the notification panel.|
## DownloadInfo<sup>7+</sup> ## DownloadInfo<sup>7+</sup>
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
| Name | Type | Mandatory | Description | | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| downloadId | number | Yes | ID of the downloaded file. | | downloadId | number | Yes| ID of the downloaded file.|
| failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). | | failedReason | number | No| Download failure cause, which can be any constant of [ERROR_*](#constants).|
| fileName | string | Yes | Name of the downloaded file. | | fileName | string | Yes| Name of the downloaded file.|
| filePath | string | Yes | URI of the saved file. | | filePath | string | Yes| URI of the saved file.|
| pausedReason | number | No | Reason for session pause, which can be any constant of [PAUSED_*](#constants). | | pausedReason | number | No| Reason for session pause, which can be any constant of [PAUSED_*](#constants).|
| status | number | Yes | Download status code, which can be any constant of [SESSION_*](#constants). | | status | number | Yes| Download status code, which can be any constant of [SESSION_*](#constants).|
| targetURI | string | Yes | URI of the downloaded file. | | targetURI | string | Yes| URI of the downloaded file.|
| downloadTitle | string | Yes | Title of the downloaded file. | | downloadTitle | string | Yes| Title of the downloaded file.|
| downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). | | downloadTotalBytes | number | Yes| Total size of the files to download (int bytes).|
| description | string | Yes | Description of the file to download. | | description | string | Yes| Description of the file to download.|
| downloadedBytes | number | Yes | Size of the files downloaded (int bytes). | | downloadedBytes | number | Yes| Size of the files downloaded (int bytes).|
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或