Switches to another subtype of the current input method. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY<br>**NOTE**<br>- API version 10 and later: This API can be called by system applications and the current input method application.<br>- API version 9: This API can be called by system applications only.
Switches to another subtype of the current input method. This API uses a promise to return the result.
**Required permissions**: ohos.permission.CONNECT_IME_ABILITY<br>**NOTE**<br>- API version 10 and later: This API can be called by system applications and the current input method application.<br>- API version 9: This API can be called by system applications only.
Enables listening for the delete-to-the-left or delete-to-the-right event of the input method. This API uses an asynchronous callback to return the result.
Enables listening for the backward delete event. This API uses an asynchronous callback to return the result.
@@ -1704,8 +1714,8 @@ Enables listening for the delete-to-the-left or delete-to-the-right event of the
| Name | Type| Mandatory| Description|
| -------- | ----- | ---- | ----- |
| type | string | Yes | Listening type.<br>- The value **'deleteLeft'** indicates the delete-to-the-left event.<br>- The value **'deleteRight'** indicates the delete-to-the-right event.|
| callback | (length: number) => void | Yes | Callback used to return the length of the text to be deleted to the left or to the right.<br>Your application needs to operate the content in the edit box based on the length returned in the callback.|
| type | string | Yes | Listening type.<br>The value **'deleteLeft'** indicates the backward delete event.|
| callback | (length: number) => void | Yes | Callback used to return the length of the text to be deleted backward.<br>Your application needs to operate the content in the edit box based on the length returned in the callback.|
**Error codes**
...
...
@@ -1725,7 +1735,34 @@ try {
}catch(err){
console.error(`Failed to subscribe deleteLeft: ${JSON.stringify(err)}`);
| type | string | Yes | Listening type.<br>The value **'deleteRight'** indicates the forward delete event.|
| callback | (length: number) => void | Yes | Callback used to return the length of the text to be deleted forward.<br>Your application needs to operate the content in the edit box based on the length returned in the callback.|
**Error codes**
For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
| type | string | Yes | Listening type.<br>- The value **'deleteLeft'** indicates the delete-to-the-left event.<br>- The value **'deleteRight'** indicates the delete-to-the-right event.|
| type | string | Yes | Listening type.<br>The value **'deleteLeft'** indicates the backward delete event.|
| type | string | Yes | Listening type.<br>The value **'getLeftTextOfCursor'** indicates the event of obtaining the length of text deleted backward.|
| callback | (length: number) => string | Yes | Callback used to obtain the text of the specified length deleted backward.<br>In this callback, obtain the text of the specified length on the left of the cursor in the latest state of the edit box and return the text.|
| type | string | Yes | Listening type.<br>The value **'getLeftTextOfCursor'** indicates the event of obtaining the length of text deleted backward.|
| callback | (length: number) => string | No | Callback used to obtain the text of the specified length deleted backward. The value must be the same as that passed in by the **on** API.|
| type | string | Yes | Listening type.<br>The value **'getRightTextOfCursor'** indicates the event of obtaining the length of text deleted forward.|
| callback | (length: number) => string | Yes | Callback used to obtain the text of the specified length deleted forward.<br>In this callback, obtain the text of the specified length on the right of the cursor in the latest state of the edit box and return the text.|
| type | string | Yes | Listening type.<br>The value **'getRightTextOfCursor'** indicates the event of obtaining the length of text deleted forward.|
| callback | (length: number) => string | No | Callback used to obtain the text of the specified length deleted forward. The value must be the same as that passed in by the **on** API.|
| type | string | Yes | Listening type.<br>The value **'getTextIndexAtCursor'** indicates the event of obtaining the index of text at the cursor.|
| callback | () => number | Yes | Callback used to obtain the index of text at the cursor.<br>In this callback, obtain the index of text at the cursor in the latest state of the edit box and return the index.|
| type | string | Yes | Listening type.<br>The value **'getTextIndexAtCursor'** indicates the event of obtaining the index of text at the cursor.|
| callback | () => number | No | Callback used to obtain the index of text at the cursor. The value must be the same as that passed in by the **on** API.|
console.info(`Succeeded in unsubscribing getTextIndexAtCursor.`);
letindex:number=0;
returnindex;
});
}catch(err){
console.error(`Failed to unsubscribing getTextIndexAtCursor. Code: ${err.code}, message: ${err.message}`);
}
```
## InputMethodSetting<sup>8+</sup>
In the following API examples, you must first use [getSetting](#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance.
...
...
@@ -2110,11 +2339,11 @@ Disables listening for the input method and subtype change event. This API uses
Enables listening for a soft keyboard visibility event of the input method. This API uses an asynchronous callback to return the result.
Enables listening for the show event of the soft keyboard. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
...
...
@@ -2124,7 +2353,7 @@ Enables listening for a soft keyboard visibility event of the input method. This
| Name | Type| Mandatory| Description|
| -------- | ---- | ---- | ---- |
| type | string | Yes| Listening type.<br>- The value **'imeShow'** indicates the soft keyboard display event.<br>- The value **'imeHide'** indicates the soft keyboard hiding event.|
| type | string | Yes| Listening type.<br>The value **'imeShow'** indicates the show event of the soft keyboard.|
| callback | (info: Array\<InputWindowInfo>) => void | Yes| Callback used to return the information about the soft keyboard of the input method.|
Disables listening for a soft keyboard visibility event of the input method.
Disables listening for the show event of the soft keyboard.
**System API**: This is a system API.
...
...
@@ -2149,7 +2403,7 @@ Disables listening for a soft keyboard visibility event of the input method.
| Name | Type| Mandatory| Description |
| -------- | ---- | ---- | ------ |
| type | string | Yes| Listening type.<br>- The value **'imeShow'** indicates the soft keyboard display event.<br>- The value **'imeHide'** indicates the soft keyboard hiding event.|
| type | string | Yes| Listening type.<br>The value **'imeShow'** indicates the show event of the soft keyboard.|
| callback | (info: Array\<InputWindowInfo>) => void | No| Callback used for disable listening. If this parameter is not specified, all callbacks corresponding to the set event are invoked.|
**Example**
...
...
@@ -2158,6 +2412,29 @@ Disables listening for a soft keyboard visibility event of the input method.
| type | string | Yes| Listening type.<br>The value **'imeHide'** indicates the hide event of the soft keyboard.|
| callback | (info: Array\<InputWindowInfo>) => void | No| Callback used for disable listening. If this parameter is not specified, all callbacks corresponding to the set event are invoked.|
| type | string | Yes | Listening type.<br>The value **'keyEvent'** indicates the keyboard event.|
| callback | function | Yes | Callback used to return the result.<br>- The input parameter, of the [InputKeyEvent](js-apis-keyevent.md#KeyEvent) type, indicates the key event information.<br>- If the event is consumed by the event subscriber, **true** is returned. Otherwise, **false** is returned.|
| type | string | Yes | Listening type.<br>The value **'keyEvent'** indicates the keyboard event.|
| callback | function | No | Callback to be unregistered.<br>- The input parameter, of the [InputKeyEvent](js-apis-keyevent.md#KeyEvent) type, indicates the key event information.<br>- If the event is consumed by the event subscriber, **true** is returned. Otherwise, **false** is returned.<br>- This parameter is optional. If this parameter is not specified, all callbacks registered for the event will be unregistered.|
| type | 'show'\|'hide' | Yes| Listening type.<br>- The value **'show'** indicates the panel display event.<br>- The value **'hide'** indicates the panel hiding event.|
| type | string | Yes| Listening type.<br>The value **'show'** indicates the show event.|
| callback | () => void | Yes | Callback used to return the result.|
| type | 'show'\|'hide' | Yes| Listening type.<br>- The value **'show'** indicates the panel display event.<br>- The value **'hide'** indicates the panel hiding event.|
| type | string | Yes| Listening type.<br>The value **'hide'** indicates the hide event.|
| callback | () => void | Yes | Callback used to return the result.|
**Example**
```js
panel.on('hide',()=>{
console.log('Panel is hiding.');
});
```
### off('show')<sup>10+</sup>
off(type: 'show', callback?: () => void): void
Disables listening for the show event of this panel. This API uses an asynchronous callback to return the result.
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
}
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
## request.uploadFile<sup>9+</sup>
...
...
@@ -142,6 +148,7 @@ Uploads files. This API uses an asynchronous callback to return the result. You
| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
...
...
@@ -152,6 +159,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro
```js
letuploadTask;
letcontext;
letuploadConfig={
url:'http://patch',
header:{key1:"value1",key2:"value2"},
...
...
@@ -160,18 +168,22 @@ For details about the error codes, see [Upload and Download Error Codes](../erro
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
}
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
@@ -214,7 +226,7 @@ Uploads files. This API uses a promise to return the result.
request.upload(uploadConfig).then((data)=>{
uploadTask=data;
}).catch((err)=>{
console.error('Failed to request the upload. Cause: '+JSON.stringify(err));
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
})
```
...
...
@@ -255,7 +267,7 @@ Uploads files. This API uses an asynchronous callback to return the result.
};
request.upload(uploadConfig,(err,data)=>{
if(err){
console.error('Failed to request the upload. Cause: '+JSON.stringify(err));
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
return;
}
uploadTask=data;
...
...
@@ -392,7 +404,7 @@ Unsubscribes from upload progress events. This API uses a callback to return the
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).|
| callback | function | No| Callback used to return the result.<br>**uploadedSize**: size of the uploaded files, in bytes.<br>**totalSize**: Total size of the files to upload, in bytes. |
| callback | function | No| Callback used to return the result.<br>**uploadedSize**: size of the uploaded files, in B.<br>**totalSize**: Total size of the files to upload, in B.|
**Example**
...
...
@@ -487,12 +499,12 @@ Deletes this upload task. This API uses a promise to return the result.
console.info('Succeeded in removing the upload task.');
}else{
console.error('Failed to remove the upload task.');
console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
}
});
```
...
...
@@ -640,7 +652,7 @@ Describes the list of files in [UploadConfig](#uploadconfig).
| -------- | -------- | -------- | -------- |
| filename | string | Yes| File name in the header when **multipart** is used.|
| name | string | Yes| Name of a form item when **multipart** is used. The default value is **file**.|
| uri | string | Yes| Local path for storing files.<br>Only the **internal** protocol type is supported. In the value, **internal://cache/** is mandatory. Example:<br>internal://cache/path/to/file.txt |
| uri | string | Yes| Local path for storing files.<br>Only the **internal** protocol type is supported. In the value, **"internal://cache/"** must be included. Example:<br>internal://cache/path/to/file.txt |
| type | string | Yes| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.|
...
...
@@ -681,29 +693,35 @@ Downloads files. This API uses a promise to return the result. You can use [on('
| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
}
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
## request.downloadFile<sup>9+</sup>
...
...
@@ -725,32 +743,38 @@ Downloads files. This API uses an asynchronous callback to return the result. Yo
| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
}
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
console.info('Succeeded in querying the download mimeType.');
}
});
```
...
...
@@ -1558,12 +1581,12 @@ Pauses this download task. This API uses a promise to return the result.
```js
downloadTask.pause().then((result)=>{
if(result){
console.info('Download task paused. ');
console.info('Succeeded in pausing the download task.');
}else{
console.error('Failed to pause the download task. Cause:'+JSON.stringify(result));
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
}
}).catch((err)=>{
console.error('Failed to pause the download task. Cause:'+JSON.stringify(err));
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
});
```
...
...
@@ -1593,13 +1616,13 @@ Pauses this download task. This API uses an asynchronous callback to return the
```js
downloadTask.pause((err,result)=>{
if(err){
console.error('Failed to pause the download task. Cause:'+JSON.stringify(err));
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
if(result){
console.info('Download task paused. ');
console.info('Succeeded in pausing the download task.');
}else{
console.error('Failed to pause the download task. Cause:'+JSON.stringify(result));
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
}
});
```
...
...
@@ -1630,13 +1653,13 @@ Resumes this download task. This API uses a promise to return the result.
```js
downloadTask.resume().then((result)=>{
if(result){
console.info('Download task resumed.')
console.info('Succeeded in resuming the download task.')
}else{
console.error('Failed to resume the download task. ');
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
}
console.info('Download task resumed.')
console.info('Succeeded in resuming the download task.')
}).catch((err)=>{
console.error('Failed to resume the download task. Cause:'+err);
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
});
```
...
...
@@ -1666,13 +1689,13 @@ Resumes this download task. This API uses an asynchronous callback to return the
```js
downloadTask.resume((err,result)=>{
if(err){
console.error('Failed to resume the download task. Cause:'+err);
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
if(result){
console.info('Download task resumed.');
console.info('Succeeded in resuming the download task.');
}else{
console.error('Failed to resume the download task.');
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
}
});
```
...
...
@@ -1693,7 +1716,7 @@ Defines the download task configuration.
| enableRoaming | boolean | No| Whether download is allowed on a roaming network. The default value is **false**.<br>- **true**: allowed<br>- **false**: not allowed|
| description | string | No| Description of the download session.|
| filePath<sup>7+</sup> | string | No| Path where the downloaded file is stored.<br>- In the FA model, use [context](js-apis-inner-app-context.md#contextgetcachedir) to obtain the cache directory of the application, for example, **\${featureAbility.getContext().getFilesDir()}/test.txt\**, and store the file in this directory.<br>- In the stage model, use [AbilityContext](js-apis-inner-application-context.md) to obtain the file path, for example, **\${globalThis.abilityContext.tempDir}/test.txt\**, and store the file in this path.|
| networkType | number | No| Network type allowed for download. The default value is **NETWORK_MOBILE and NETWORK_WIFI**.<br>- NETWORK_MOBILE: 0x00000001<br>- NETWORK_WIFI: 0x00010000|
| networkType | number | No| Network type allowed for the download. The default value is **NETWORK_MOBILE and NETWORK_WIFI**.<br>- NETWORK_MOBILE: 0x00000001<br>- NETWORK_WIFI: 0x00010000|
| title | string | No| Download task name.|
| background<sup>9+</sup> | boolean | No| Whether to enable background task notification so that the download status is displayed in the notification panel. The default value is false.|
...
...
@@ -1706,7 +1729,7 @@ Defines the download task information, which is the callback parameter of the [g
| path | string | Yes| File path. The options are as follows:<br>- Relative path in the cache folder of the invoker.<br>- URI (applicable when the application has the permission to access the URI).|
| mimeType | string | No| MIME type of the file. The default value is as follows:<br>- During an upload, the value is obtained from the file name or URI suffix.<br>- During a download, the value is **Content-Type** when there is response and **octet-stream** otherwise.|
| filename | string | No| File name. The default value is obtained from the file path.|
| extras | Object | No| Additional information of the file.|
| url | string | Yes| Resource URL. The value contains a maximum of 2048 characters.|
| title | string | No| Task title. The value contains a maximum of 256 characters. This parameter is left blank by default.|
| description | string | No| Task description. The value contains a maximum of 1024 characters. The default value is a null string.|
| mode | [Mode](#mode10) | No| Task mode. The default mode is background.<br>- For a foreground task, a callback is used for notification.<br>- For a background task, the system notification and network connection features (detection, recovery, and automatic retry) are provided.|
| overwrite | boolean | No| Whether to overwrite an existing file during the download. The default value is **false**.<br>- **true**: Overwrite the existing file.<br>- **false**: Do not overwrite the existing file. In this case, the download fails.|
| method | string | No| Standard HTTP method for the task. The value can be **GET**, **POST**, or **PUT**, which is case-insensitive.<br>- If the task is an upload, use **PUT** or **POST**. The default value is **PUT**.<br>- If the task is a download, use **GET** or **POST**. The default value is **GET**.|
| headers | object | No| HTTPS headers to be included in the task.<br>- If the task is an upload, the default **Content-Type** is **multipart/form-data**.<br>- If the task is a download, the default **Content-Type** is **application/json**.|
| data | string \| Array<[FormItem](#formitem10)> | No| Task data.<br>- If the task is a download, the value is a string, typically in JSON format (an object will be converted to a JSON string); the default value is null.<br>- If the task is an upload, the value is Array<[FormItem](#formitem10)>; the default value is null.|
| saveas | string | No| Path for storing downloaded files. The options are as follows:<br>- Relative path in the cache folder of the invoker, for example, ./xxx/yyy/zzz.html and xxx/yyy/zzz.html.<br>- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. Currently, this type is not supported.<br>The default value is a relative path in the cache folder of the application.|
| network | [Network](#network10) | No| Network used for the task. The default value is **ANY** (Wi-Fi or cellular).|
| metered | boolean | No| Whether the task is allowed on a metered connection. The default value is **false**.|
| roaming | boolean | No| Whether the task is allowed on a roaming network. The default value is **true**.|
| retry | boolean | No| Whether automatic retry is enabled for background tasks. The default value is **true**.|
| redirect | boolean | No| Whether redirection is allowed. The default value is **true**.|
| index | number | No| Path index of the task. It is usually used for resumable downloads. The default value is **0**.|
| begins | number | No| File start point of the task. It is usually used for resumable downloads. The default value is **0**. The value is a closed interval.<br>- If the task is a download, the value is obtained by sending an HTTP range request to read the start position when the server starts to download files.<br>- If the task is an upload, the value is obtained at the beginning of the upload.|
| ends | number | No| File end point of the task. It is usually used for resumable downloads. The default value is **-1**. The value is a closed interval.<br>- If the task is a download, the value is obtained by sending an HTTP range request to read the end position when the server starts to download files.<br>- If the task is an upload, the value is obtained at the end of the upload.|
| gauge | boolean | No| Whether to send progress notifications. This parameter applies only to background tasks. The default value is **false**.<br>- **false**: Progress notifications are not sent. This means that a notification is sent only to indicate the result of the total task.<br>- **true**: Progress notifications are sent to indicate the result of each file.|
| precise | boolean | No| - If this parameter is set to **true**, the task fails when the file size cannot be obtained.<br>- If this parameter is set to **false**, the task continues when the file size is set to **-1**.<br>The default value is **false**.|
| token | string | No| Token of the task. If the task has a token configured, this token is required for query of the task. The value contains 8 to 2048 bytes. This parameter is left empty by default.|
| extras | object | No| Additional information of the task. This parameter is left blank by default.|
| uid | string | No| UID of the application. It is only available for query by system applications.<br>**System API**: This is a system API.|
| bundle | string | No| Bundle name of the application. It is only available for query by system applications.<br>**System API**: This is a system API.|
| url | string | No| Task URL. It is only available for query by non-system applications. An empty string is returned for query by system applications.|
| data | string \| Array<[FormItem](#formitem10)> | No| Task value.|
| gauge | boolean | Yes| Whether to send progress notifications. This parameter applies only to background tasks.|
| ctime | string | Yes| Date and time when a task is created in UTC mode. The value is generated by the system of the current device.|
| mtime | string | Yes| Date and time when a task is modified in UTC mode. The value is generated by the system of the current device.|
| retry | boolean | Yes| Whether automatic retry is enabled for the task. This parameter applies only to background tasks.|
| tries | number | Yes| Number of retries of the task.|
| broken | [Broken](#broken10) | Yes| Failure cause of the task.<br>- **OTHERS**: other fault.<br>- **DISCONNECT**: network disconnection.<br>- **TIMEOUT**: timeout.<br>- **PROTOCOL**: protocol error.<br>- **FSIO**: file system I/O error.|
| reason | string | Yes| Reason why the task is waiting, failed, stopped, or paused.|
| extras | string | No| Extra information of the task|
## Task<sup>10+</sup>
Implements an upload or download task. Before using this API, you must obtain a **Task** object, from a promise through [request.agent.create<sup>10+</sup>](#requestagentcreate10-1) or from a callback through [request.agent.create<sup>10+</sup>](#requestagentcreate10).
### Attributes
Task attributes include the task ID and task configuration.
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.|
| callback | function | Yes| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOnTest",
value:{
filename:"taskOnTest.avi",
mimetype:"application/octet-stream",
path:"./taskOnTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOnTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOnCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('progress',createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.|
| callback | function | Yes| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOnTest",
value:{
filename:"taskOnTest.avi",
mimetype:"application/octet-stream",
path:"./taskOnTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOnTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOnCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('completed',createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.|
| callback | function | Yes| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOnTest",
value:{
filename:"taskOnTest.avi",
mimetype:"application/octet-stream",
path:"./taskOnTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOnTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOnCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('failed',createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'progress'**, indicating the task progress.|
| callback | function | No| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOffTest",
value:{
filename:"taskOffTest.avi",
mimetype:"application/octet-stream",
path:"./taskOffTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOffTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOffCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('progress',createOffCallback);
task.off('progress',createOffCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'completed'**, indicating task completion.|
| callback | function | No| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOffTest",
value:{
filename:"taskOffTest.avi",
mimetype:"application/octet-stream",
path:"./taskOffTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOffTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOffCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('completed',createOffCallback);
task.off('completed',createOffCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
| event | string | Yes| Type of the event to subscribe to.<br>The value is **'failed'**, indicating task failure.|
| callback | function | No| Callback used to return the data structure of the task progress.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"taskOffTest",
value:{
filename:"taskOffTest.avi",
mimetype:"application/octet-stream",
path:"./taskOffTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'taskOffTest',
description:'Sample code for event listening',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
letcreateOffCallback=(progress)=>{
console.info('upload task completed.');
};
request.agent.create(context,conf).then((task)=>{
task.on('failed',createOffCallback);
task.off('failed',createOffCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
### start<sup>10+</sup>
start(callback: AsyncCallback<void>): void
Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result.
| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900007 | task state error. |
**Example**
```js
letcontext;
letconf={
action:request.agent.Action.DOWNLOAD,
url:'http://127.0.0.1',
title:'taskStartTest',
description:'Sample code for start the download task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"GET",
data:"",
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
task.start((err)=>{
if(err){
console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in starting a download task.`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
### start<sup>10+</sup>
start(): Promise<void>
Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result.
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900007 | task state error. |
**Example**
```js
letcontext;
letconf={
action:request.agent.Action.DOWNLOAD,
url:'http://127.0.0.1',
title:'taskStartTest',
description:'Sample code for start the download task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"GET",
data:"",
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
task.start().then(()=>{
console.info(`Succeeded in starting a download task.`);
}).catch((err)=>{
console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
### pause<sup>10+</sup>
pause(callback: AsyncCallback<void>): void
Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses an asynchronous callback to return the result.
| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900005 | task mode error. |
| 21900007 | task state error. |
**Example**
```js
letcontext;
letconf={
action:request.agent.Action.DOWNLOAD,
url:'http://127.0.0.1',
title:'taskPauseTest',
description:'Sample code for pause the download task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"GET",
data:"",
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
task.pause((err)=>{
if(err){
console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in pausing a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
### pause<sup>10+</sup>
pause(): Promise<void>
Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses a promise to return the result.
| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900005 | task mode error. |
| 21900007 | task state error. |
**Example**
```js
letcontext;
letconf={
action:request.agent.Action.DOWNLOAD,
url:'http://127.0.0.1',
title:'taskResumeTest',
description:'Sample code for resume the download task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"GET",
data:"",
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
task.resume((err)=>{
if(err){
console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in resuming a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
### resume<sup>10+</sup>
resume(): Promise<void>
Resumes this task. This API can be used to resume a paused background task. This API uses a promise to return the result.
| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900007 | task state error. |
**Example**
```js
letcontext;
letconf={
action:request.agent.Action.DOWNLOAD,
url:'http://127.0.0.1',
title:'taskStopTest',
description:'Sample code for stop the download task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"GET",
data:"",
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
task.stop((err)=>{
if(err){
console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in stopping a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
### stop<sup>10+</sup>
stop(): Promise<void>
Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result.
Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 tasks, and a maximum of 300 tasks can be carried. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<[Task](#task10)> | Yes| Callback used to return the configuration about the created task.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400001 | file operation error. |
| 13400003 | task service ability error. |
| 21900004 | application task queue full error. |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"reeateTest",
value:{
filename:"reeateTest.avi",
mimetype:"application/octet-stream",
path:"./reeateTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'reeateTest',
description:'Sample code for reeate task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf,(err,task)=>{
if(err){
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in creating a download task. result: ${task.conf}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 tasks, and a maximum of 300 tasks can be carried. This API uses a promise to return the result.
| Promise<[Task](#task10)> | Promise used to return the configuration about the created task.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400001 | file operation error. |
| 13400003 | task service ability error. |
| 21900004 | application task queue full error. |
| 21900005 | task mode error. |
**Example**
```js
letcontext;
letattachments=[{
name:"reeateTest",
value:{
filename:"reeateTest.avi",
mimetype:"application/octet-stream",
path:"./reeateTest.avi",
}
}];
letconf={
action:request.agent.Action.UPLOAD,
url:'http://127.0.0.1',
title:'reeateTest',
description:'Sample code for reeate task',
mode:request.agent.Mode.BACKGROUND,
overwrite:false,
method:"PUT",
data:attachments,
saveas:"./",
network:request.agent.Network.CELLULAR,
metered:false,
roaming:true,
retry:true,
redirect:true,
index:0,
begins:0,
ends:-1,
gauge:false,
precise:false,
token:"it is a secret"
};
request.agent.create(context,conf).then((task)=>{
console.info(`Succeeded in creating a download task. result: ${task.conf}`);
}).catch((err)=>{
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
```
> **NOTE**
>
> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md).
| ID| Error Message|
| -------- | -------- |
| 13400003 | task service ability error. |
| 21900006 | task not found error. |
**Example**
```js
request.agent.remove("id",(err)=>{
if(err){
console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in creating a download task.`);
});
```
## request.agent.remove<sup>10+</sup>
remove(id: string): Promise<void>
Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses a promise to return the result.
| top | boolean | Yes | Whether to jump to the top of the page. The value **true** means to jump to the top of the page; and **false** means to scroll the page up by half the viewport.|
| top | boolean | Yes | Whether to jump to the top of the page. The value **true** means to jump to the top of the page; and **false** means to scroll the page up by half the viewport.|
**Error codes**
...
...
@@ -3564,7 +3564,7 @@ struct WebComponent {
pageDown(bottom:boolean): void
Scrolls the page down by half the viewport or jumps to the bottom of the page.
Scrolls the page down by half the viewport or jumps to the bottom of the page.
| bottom | boolean | Yes | Whether to jump to the bottom of the page. The value **true** means to jump to the bottom of the page; and **false** means to scroll the page down by half the viewport.|
| bottom | boolean | Yes | Whether to jump to the bottom of the page. The value **true** means to jump to the bottom of the page; and **false** means to scroll the page down by half the viewport.|
@@ -36,7 +36,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
| Name| Type| Default Value| Description|
| -------- | -------- | -------- | -------- |
| viewPort | {<br>x?: number \| string,<br>y?: number \| string,<br>width?: number \| string,<br>height?: number \| string<br>} | { x:0, y:0, width:0, height:0 } | Viewport of the shape.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>If of the string type, the value cannot be a percentage.|
| viewPort | {<br>x?: number \| string,<br>y?: number \| string,<br>width?: number \| string,<br>height?: number \| string<br>} | { x:0, y:0, width:0, height:0 } | Viewport of the shape.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>If of the string type, the value cannot be a percentage.|
| fill | [ResourceColor](ts-types.md) | Color.Black | Color of the fill area.<br>Since API version 9, this API is supported in ArkTS widgets.|
| fillOpacity | number \| string \|[Resource](ts-types.md#resource)| 1 | Opacity of the fill area.<br>Since API version 9, this API is supported in ArkTS widgets.|
| stroke | [ResourceColor](ts-types.md) | - | Stroke color. If this attribute is not set, the component does not have any stroke.<br>Since API version 9, this API is supported in ArkTS widgets.|
