Skip to content

D
Docs

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

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

!7921 翻译完成 7457/7769：js-apis-request.md 

Merge pull request !7921 from ester.zhou/TR-7457
上级 23537099 6445a842
显示空白变更内容
内联 并排
Showing with 351 addition and 179 deletion
en/application-dev/reference/apis/js-apis-request.md
浏览文件 @ ddf5c080
......@@ -17,9 +17,9 @@ import request from '@ohos.request';
## 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 = {
"deviceConfig": {
"default": {
......@@ -32,6 +32,9 @@ var config = {
}
```
The **cleartextTraffic** attribute is not involved during the development of applications in the stage model.
## Constants
......@@ -39,28 +42,28 @@ var config = {
**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_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_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_ERROR<sup>7+</sup> | number | Yes | No | File operation 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_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_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_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_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_PAUSED<sup>7+</sup> | number | Yes | No | Download paused. |
| SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download pending. |
| SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download in progress. |
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful download. |
| 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.|
| 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_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_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_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_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 mobile network session.|
| 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_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_PAUSED<sup>7+</sup> | number | Yes| No| Download paused.|
| SESSION_PENDING<sup>7+</sup> | number | Yes| No| Download pending.|
| SESSION_RUNNING<sup>7+</sup> | number | Yes| No| Download in progress.|
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes| No| Successful download.|
## request.upload
......@@ -69,30 +72,36 @@ upload(config: UploadConfig): Promise&lt;UploadTask&gt;
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
**System capability**: SystemCapability.MiscServices.Upload
**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**
| 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**
```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;
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;
}).catch((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
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
**System capability**: SystemCapability.MiscServices.Upload
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No | Callback used to return the **UploadTask** object. |
| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No| Callback used to return the **UploadTask** object.|
**Example**
```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;
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) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return;
......@@ -132,8 +147,87 @@ Uploads files. This API uses an asynchronous callback to return the result.
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
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
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
......@@ -151,17 +245,17 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
**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). |
| callback | function | Yes | Callback for the upload progress event. |
| 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** parameters
Parameters of the callback function
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
| totalSize | number | Yes | Total size of the files to upload, in KB. |
| uploadedSize | number | Yes| Size of the uploaded files, in KB.|
| totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example**
......@@ -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
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
......@@ -185,16 +279,16 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
**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). |
| callback | function | Yes | Callback for the HTTP Response Header event. |
| 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** 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**
......@@ -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
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
......@@ -218,17 +312,17 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
**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). |
| callback | function | No | Callback for the upload progress event. |
| 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** parameters
Parameters of the callback function
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
| totalSize | number | Yes | Total size of the files to upload, in KB. |
| uploadedSize | number | Yes| Size of the uploaded files, in KB.|
| totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example**
......@@ -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
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
......@@ -252,16 +346,16 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal
**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). |
| callback | function | No | Callback for the HTTP Response Header event. |
| 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** 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**
......@@ -285,9 +379,9 @@ Removes this upload task. This API uses a promise to return the result.
**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**
......@@ -316,9 +410,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r
**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**
......@@ -339,37 +433,42 @@ Removes this upload task. This API uses an asynchronous callback to return the r
## UploadConfig
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. |
| 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**. |
| 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. |
| url | string | Yes| Resource URL.|
| 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'**.|
| 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.|
## 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. |
| 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 |
| type | string | No | Type of the file content. By default, the type is obtained based on the extension of the file name or URI. |
| 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.<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.|
## 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. |
| value | string | Yes | Value of a form element. |
| name | string | Yes| Name of a form element.|
| value | string | Yes| Value of a form element.|
## request.download
......@@ -378,21 +477,23 @@ download(config: DownloadConfig): Promise&lt;DownloadTask&gt;
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
**System capability**: SystemCapability.MiscServices.Download
**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**
| 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**
......@@ -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.
This API can be used only in the FA model.
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No | Callback used to return the result. |
| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No| Callback used to return the result.|
**Example**
......@@ -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
Implements file downloads.
......@@ -447,7 +615,7 @@ Implements file downloads.
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
......@@ -455,17 +623,17 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
**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). |
| callback | function | Yes | Callback for the download progress event. |
| 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** parameters
Parameters of the callback function
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. |
| totalSize | number | Yes | Total size of the files to download, in KB. |
| receivedSize | number | Yes| Size of the downloaded files, in KB.|
| totalSize | number | Yes| Total size of the files to download, in KB.|
**Example**
......@@ -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
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
......@@ -489,17 +657,17 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal
**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). |
| callback | function | No | Callback for the download progress event. |
| 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** parameters
Parameters of the callback function
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. |
| totalSize | number | Yes | Total size of the files to download, in KB. |
| receivedSize | number | Yes| Size of the downloaded files.|
| totalSize | number | Yes| Total size of the files to download.|
**Example**
......@@ -523,10 +691,10 @@ Subscribes to a download event. This API uses an asynchronous callback to return
**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. |
| callback | function | Yes | Callback used to return the result. |
| 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.|
**Example**
......@@ -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
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
......@@ -550,10 +718,10 @@ Unsubscribes from the download event. This API uses an asynchronous callback to
**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. |
| callback | function | No | Callback used to return the result. |
| 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.|
**Example**
......@@ -577,16 +745,16 @@ Subscribes to the download task failure event. This API uses an asynchronous cal
**Parameters**
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the subscribed event. The value is **'fail'** (download failure). |
| callback | function | Yes | Callback for the download task failure event. |
| 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** 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**
......@@ -610,16 +778,16 @@ Unsubscribes from the download task failure event. This API uses an asynchronous
**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). |
| callback | function | No | Callback for the download task failure event. |
| 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** 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**
......@@ -643,9 +811,9 @@ Removes this download task. This API uses a promise to return the result.
**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**
......@@ -674,9 +842,9 @@ Removes this download task. This API uses an asynchronous callback to return the
**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**
......@@ -706,10 +874,9 @@ Queries this download task. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information. |
| Type| Description|
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information.|
**Example**
......@@ -734,9 +901,9 @@ Queries this download task. This API uses an asynchronous callback to return the
**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**
......@@ -755,7 +922,7 @@ Queries this download task. This API uses an asynchronous callback to return the
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
......@@ -763,9 +930,9 @@ Queries **MimeType** of this download task. This API uses a promise to return th
**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**
......@@ -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;
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
......@@ -790,9 +957,9 @@ Queries **MimeType** of this download task. This API uses an asynchronous callba
**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**
......@@ -819,9 +986,9 @@ Pauses this download task. This API uses a promise to return the result.
**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**
......@@ -850,9 +1017,9 @@ Pauses this download task. This API uses an asynchronous callback to return the
**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**
......@@ -883,9 +1050,9 @@ Resumes this download task. This API uses a promise to return the result.
**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**
......@@ -915,9 +1082,9 @@ Resumes this download task. This API uses an asynchronous callback to return the
**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**
......@@ -938,34 +1105,39 @@ Resumes this download task. This API uses an asynchronous callback to return the
## DownloadConfig
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
| Name | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. |
| header | object | No | HTTP or HTTPS header added to a download request. |
| enableMetered | boolean | No | Download allowed in metered connections. |
| enableRoaming | boolean | No | Download allowed on a roaming network. |
| 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. |
| networkType | number | No | Network type allowed for download. |
| title | string | No | Title of the download session. |
| url | string | Yes| Resource URL.|
| header | object | No| HTTP or HTTPS header added to a download request.|
| enableMetered | boolean | No| Download allowed in metered connections.|
| enableRoaming | boolean | No| Download allowed on a roaming network.|
| 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.|
| networkType | number | No| Network type allowed for download.|
| 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>
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| downloadId | number | Yes | ID of the downloaded file. |
| failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). |
| fileName | string | Yes | Name of the downloaded file. |
| filePath | string | Yes | URI of the saved file. |
| 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). |
| targetURI | string | Yes | URI of the downloaded file. |
| downloadTitle | string | Yes | Title of the downloaded file. |
| downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). |
| description | string | Yes | Description of the file to download. |
| downloadedBytes | number | Yes | Size of the files downloaded (int bytes). |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| downloadId | number | Yes| ID of the downloaded file.|
| failedReason | number | No| Download failure cause, which can be any constant of [ERROR_*](#constants).|
| fileName | string | Yes| Name of the downloaded file.|
| filePath | string | Yes| URI of the saved file.|
| 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).|
| targetURI | string | Yes| URI of the downloaded file.|
| downloadTitle | string | Yes| Title of the downloaded file.|
| downloadTotalBytes | number | Yes| Total size of the files to download (int bytes).|
| description | string | Yes| Description of the file to download.|
| 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.
先完成此消息的编辑！
想要评论请 注册 或