提交 d583fc28 编写于 作者: E ester.zhou

update docs

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 c7e07a2f
# Input Method Framework # Input Method Framework
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
...@@ -40,16 +40,18 @@ Obtains an [InputMethodController](#InputMethodController) instance. ...@@ -40,16 +40,18 @@ Obtains an [InputMethodController](#InputMethodController) instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| [InputMethodController](#InputMethodController) | Returns the current **InputMethodController** instance.| | [InputMethodController](#InputMethodController) | Returns the current **InputMethodController** instance.|
**Example**
```
var InputMethodController = inputMethod.getInputMethodController();
```
- Example
```
var InputMethodController = inputMethod.getInputMethodController();
```
## inputMethod.getInputMethodSetting<sup>8+</sup><a name="getInputMethodSetting"></a> ## inputMethod.getInputMethodSetting<sup>8+</sup><a name="getInputMethodSetting"></a>
getInputMethodSetting(): InputMethodSetting getInputMethodSetting(): InputMethodSetting
...@@ -58,17 +60,17 @@ Obtains an [InputMethodSetting](#InputMethodSetting) instance. ...@@ -58,17 +60,17 @@ Obtains an [InputMethodSetting](#InputMethodSetting) instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description | | Type | Description |
| ----------------------------------------- | ---------------------------- | | ----------------------------------------- | ---------------------------- |
| [InputMethodSetting](#InputMethodSetting) | Returns the current **InputMethodSetting** instance.| | [InputMethodSetting](#InputMethodSetting) | Returns the current **InputMethodSetting** instance.|
**Example**
- Example ```js
``` var InputMethodSetting = inputMethod.getInputMethodSetting();
var InputMethodSetting = inputMethod.getInputMethodSetting(); ```
```
## InputMethodController<a name="InputMethodController"></a> ## InputMethodController<a name="InputMethodController"></a>
...@@ -82,15 +84,15 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ...@@ -82,15 +84,15 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return whether the keyboard is successfully hidden.| | callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return whether the keyboard is successfully hidden.|
- Example **Example**
``` ```js
InputMethodController.stopInput((error)=>{ InputMethodController.stopInput((error)=>{
console.info('stopInput'); console.info('stopInput');
}); });
...@@ -104,16 +106,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ...@@ -104,16 +106,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return whether the keyboard is successfully hidden.| | Promise&lt;boolean&gt; | Promise used to return whether the keyboard is successfully hidden.|
- Example **Example**
``` ```js
var isSuccess = InputMethodController.stopInput(); var isSuccess = InputMethodController.stopInput();
console.info('stopInput isSuccess = ' + isSuccess); console.info('stopInput isSuccess = ' + isSuccess);
``` ```
...@@ -130,20 +132,22 @@ Obtains the list of installed input methods. This API uses an asynchronous callb ...@@ -130,20 +132,22 @@ Obtains the list of installed input methods. This API uses an asynchronous callb
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ---------------------- | | Name | Type | Mandatory| Description |
| callback | Array<[InputMethodProperty](#InputMethodProperty)> | Yes | Callback used to return the list of installed input methods.| | -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | Array<[InputMethodProperty](#InputMethodProperty)> | Yes | Callback used to return the list of installed input methods.|
- Example
``` **Example**
InputMethodSetting.listInputMethod((properties)=>{
for (var i = 0;i < properties.length; i++) { ```js
var property = properties[i]; InputMethodSetting.listInputMethod((properties)=>{
console.info(property.packageName + "/" + property.methodId); for (var i = 0;i < properties.length; i++) {
} var property = properties[i];
}); console.info(property.packageName + "/" + property.methodId);
``` }
});
```
### listInputMethod ### listInputMethod
...@@ -153,19 +157,21 @@ Obtains the list of installed input methods. This API uses an asynchronous callb ...@@ -153,19 +157,21 @@ Obtains the list of installed input methods. This API uses an asynchronous callb
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description |
| ----------------------------------------------------------- | ---------------------- |
| Promise<Array<[InputMethodProperty](#InputMethodProperty)>> | Promise used to return the list of installed input methods.|
- Example | Type | Description |
``` | ----------------------------------------------------------- | ---------------------- |
var properties = InputMethodSetting.listInputMethod(); | Promise<Array<[InputMethodProperty](#InputMethodProperty)>> | Promise used to return the list of installed input methods.|
for (var i = 0;i < properties.length; i++) {
var property = properties[i]; **Example**
console.info(property.packageName + "/" + property.methodId);
} ```js
``` var properties = InputMethodSetting.listInputMethod();
for (var i = 0;i < properties.length; i++) {
var property = properties[i];
console.info(property.packageName + "/" + property.methodId);
}
```
### displayOptionalInputMethod ### displayOptionalInputMethod
...@@ -181,12 +187,12 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono ...@@ -181,12 +187,12 @@ Displays a dialog box for selecting an input method. This API uses an asynchrono
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|
- Example **Example**
``` ```js
InputMethodSetting.displayOptionalInputMethod(()=>{ InputMethodSetting.displayOptionalInputMethod(()=>{
console.info('displayOptionalInputMethod is called'); console.info('displayOptionalInputMethod is called');
}); });
``` ```
### displayOptionalInputMethod ### displayOptionalInputMethod
...@@ -194,15 +200,16 @@ displayOptionalInputMethod(): Promise&lt;void&gt; ...@@ -194,15 +200,16 @@ displayOptionalInputMethod(): Promise&lt;void&gt;
Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result. Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the execution result.| | Promise&lt;void&gt; | Promise used to return the execution result.|
- Example **Example**
```
InputMethodSetting.displayOptionalInputMethod(); ```js
``` InputMethodSetting.displayOptionalInputMethod();
```
\ No newline at end of file
# Input Method Engine # Input Method Engine
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
...@@ -52,17 +52,17 @@ Obtains an **InputMethodEngine** instance. ...@@ -52,17 +52,17 @@ Obtains an **InputMethodEngine** instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | ------------ | | --------------------------------------- | ------------ |
| [InputMethodEngine](#InputMethodEngine) | **InputMethodEngine** instance obtained.| | [InputMethodEngine](#InputMethodEngine) | **InputMethodEngine** instance obtained.|
- Example **Example**
``` ```js
var InputMethodEngine = inputMethodEngine.getInputMethodEngine(); var InputMethodEngine = inputMethodEngine.getInputMethodEngine();
``` ```
## inputMethodEngine.createKeyboardDelegate<a name="createKeyboardDelegate"></a> ## inputMethodEngine.createKeyboardDelegate<a name="createKeyboardDelegate"></a>
...@@ -72,17 +72,17 @@ Obtains a **KeyboardDelegate** instance. ...@@ -72,17 +72,17 @@ Obtains a **KeyboardDelegate** instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description | | Type | Description |
| ------------------------------------- | ---------------- | | ------------------------------------- | ---------------- |
| [KeyboardDelegate](#KeyboardDelegate) | **KeyboardDelegate** instance obtained.| | [KeyboardDelegate](#KeyboardDelegate) | **KeyboardDelegate** instance obtained.|
- Example **Example**
``` ```js
var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate(); var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate();
``` ```
## InputMethodEngine<a name="InputMethodEngine"></a> ## InputMethodEngine<a name="InputMethodEngine"></a>
...@@ -96,21 +96,21 @@ Listens for the input method binding event. This API uses a callback to return t ...@@ -96,21 +96,21 @@ Listens for the input method binding event. This API uses a callback to return t
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | | -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.| | type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.|
| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | Yes| Callback used to return the result.| | callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | Yes| Callback used to return the result.|
- Example **Example**
``` ```js
InputMethodEngine.on('inputStart', (kbController, textInputClient) => { InputMethodEngine.on('inputStart', (kbController, textInputClient) => {
KeyboardController = kbController; KeyboardController = kbController;
TextInputClient = textInputClient; TextInputClient = textInputClient;
}); });
``` ```
### off('inputStart') ### off('inputStart')
...@@ -120,20 +120,18 @@ Cancels listening for the input method binding event. ...@@ -120,20 +120,18 @@ Cancels listening for the input method binding event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.|
| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | No| Callback used to return the result.|
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'inputStart'**, which indicates listening for the input method binding event.|
| callback | [KeyboardController](#KeyboardController), [TextInputClient](#TextInputClient) | No| Callback used to return the result.|
- Example **Example**
``` ```js
InputMethodEngine.off('inputStart'); InputMethodEngine.off('inputStart');
``` ```
### on('keyboardShow'|'keyboardHide') ### on('keyboardShow'|'keyboardHide')
...@@ -143,20 +141,20 @@ Listens for an input method event. ...@@ -143,20 +141,20 @@ Listens for an input method event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ | | -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>-&nbsp;The value **'keyboardShow'** means to listen for displaying of the input method.<br>-&nbsp;The value **'keyboardHide'** means to listen for hiding of the input method.| | type | string | Yes | Listening type.<br>- The value **'keyboardShow'** means to listen for displaying of the input method.<br>- The value **'keyboardHide'** means to listen for hiding of the input method.|
| callback | void | No | Callback used to return the result. | | callback | void | No | Callback used to return the result. |
- Example **Example**
``` ```js
InputMethodEngine.on('keyboardShow', (err) => { InputMethodEngine.on('keyboardShow', (err) => {
console.info('keyboardShow'); console.info('keyboardShow');
}); });
``` ```
### off('keyboardShow'|'keyboardHide') ### off('keyboardShow'|'keyboardHide')
...@@ -166,19 +164,18 @@ Cancels listening for an input method event. ...@@ -166,19 +164,18 @@ Cancels listening for an input method event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ | | -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>-&nbsp;The value **'keyboardShow'** means to listen for displaying of the input method.<br>-&nbsp;The value **'keyboardHide'** means to listen for hiding of the input method.| | type | string | Yes | Listening type.<br>- The value **'keyboardShow'** means to listen for displaying of the input method.<br>- The value **'keyboardHide'** means to listen for hiding of the input method.|
| callback | void | No | Callback used to return the result. | | callback | void | No | Callback used to return the result. |
- Example **Example**
``` ```js
InputMethodEngine.off('keyboardShow'); InputMethodEngine.off('keyboardShow');
``` ```
## KeyboardDelegate<a name="KeyboardDelegate"></a> ## KeyboardDelegate<a name="KeyboardDelegate"></a>
...@@ -192,22 +189,20 @@ Listens for a hard keyboard even. This API uses a callback to return the key inf ...@@ -192,22 +189,20 @@ Listens for a hard keyboard even. This API uses a callback to return the key inf
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>-&nbsp;The value **'keyDown'** means to listen for pressing of a key.<br>-&nbsp;The value **'keyUp'** means to listen for releasing of a key.|
| callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.|
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.|
| callback | [KeyEvent](#KeyEvent) | Yes| Callback used to return the key information.|
- Example **Example**
``` ```js
KeyboardDelegate.on('keyDown', (event) => { KeyboardDelegate.on('keyDown', (event) => {
console.info('keyDown'); console.info('keyDown');
}); });
``` ```
### off('keyDown'|'keyUp') ### off('keyDown'|'keyUp')
...@@ -217,18 +212,18 @@ Cancels listening for a hard keyboard even. ...@@ -217,18 +212,18 @@ Cancels listening for a hard keyboard even.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------- | ---- | ------------------------------------------------------------ | | -------- | --------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>-&nbsp;The value **'keyDown'** means to listen for pressing of a key.<br>-&nbsp;The value **'keyUp'** means to listen for releasing of a key.| | type | string | Yes | Listening type.<br>- The value **'keyDown'** means to listen for pressing of a key.<br>- The value **'keyUp'** means to listen for releasing of a key.|
| callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. | | callback | [KeyEvent](#KeyEvent) | No | Callback used to return the key information. |
- Example **Example**
``` ```js
KeyboardDelegate.off('keyDown'); KeyboardDelegate.off('keyDown');
``` ```
### on('cursorContextChange') ### on('cursorContextChange')
...@@ -236,24 +231,22 @@ on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) = ...@@ -236,24 +231,22 @@ on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) =
Listens for cursor context changes. This API uses a callback to return the cursor information. Listens for cursor context changes. This API uses a callback to return the cursor information.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name | Type | Mandatory| Description | **Parameters**
| -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.|
| callback | number | Yes | Callback used to return the cursor information. |
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.|
| callback | number | Yes | Callback used to return the cursor information. |
**Example**
- Example ```js
KeyboardDelegate.on('cursorContextChange', (x, y, height) => {
``` console.info('cursorContextChange');
KeyboardDelegate.on('cursorContextChange', (x, y, height) => { });
console.info('cursorContextChange'); ```
});
```
### off('cursorContextChange') ### off('cursorContextChange')
...@@ -263,19 +256,19 @@ Cancels listening for cursor context changes. ...@@ -263,19 +256,19 @@ Cancels listening for cursor context changes.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ | | -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.| | type | string | Yes | Listening type.<br>Set it to **'cursorContextChange'**, which indicates listening for cursor context changes.|
| callback | number | No| Callback used to return the cursor information.| | callback | number | No| Callback used to return the cursor information.|
**Example**
- Example ```js
KeyboardDelegate.off('cursorContextChange');
```
```
KeyboardDelegate.off('cursorContextChange');
```
### on('selectionChange') ### on('selectionChange')
on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void
...@@ -284,20 +277,20 @@ Listens for text selection changes. This API uses a callback to return the text ...@@ -284,20 +277,20 @@ Listens for text selection changes. This API uses a callback to return the text
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.|
| callback | number | Yes | Callback used to return the text selection information. |
| Name | Type | Mandatory| Description | **Example**
| -------- | ------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.|
| callback | number | Yes | Callback used to return the text selection information. |
- Example ```js
KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => {
``` console.info('selectionChange');
KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => { });
console.info('selectionChange'); ```
});
```
### off('selectionChange') ### off('selectionChange')
...@@ -307,18 +300,18 @@ Cancels listening for text selection changes. ...@@ -307,18 +300,18 @@ Cancels listening for text selection changes.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ | | -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.| | type | string | Yes | Listening type.<br>Set it to **'selectionChange'**, which indicates listening for text selection changes.|
| callback | number | No| Callback used to return the text selection information.| | callback | number | No| Callback used to return the text selection information.|
- Example **Example**
``` ```js
KeyboardDelegate.off('selectionChange'); KeyboardDelegate.off('selectionChange');
``` ```
### on('textChange') ### on('textChange')
...@@ -329,20 +322,20 @@ Listens for text changes. This API uses a callback to return the current text co ...@@ -329,20 +322,20 @@ Listens for text changes. This API uses a callback to return the current text co
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | | -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.| | type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.|
| callback | string | Yes| Callback used to return the current text content.| | callback | string | Yes| Callback used to return the current text content.|
- Example **Example**
``` ```js
KeyboardDelegate.on('textChange', (text) => { KeyboardDelegate.on('textChange', (text) => {
console.info('textChange'); console.info('textChange');
}); });
``` ```
### off('textChange') ### off('textChange')
...@@ -352,18 +345,18 @@ Cancels listening for text changes. ...@@ -352,18 +345,18 @@ Cancels listening for text changes.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ | | -------- | -------------------- | ---- | ------------------------ |
| type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.| | type | string | Yes | Listening type.<br>Set it to **'textChange'**, which indicates listening for text changes.|
| callback | string | No| Callback used to return the current text content.| | callback | string | No| Callback used to return the current text content.|
- Example **Example**
``` ```js
KeyboardDelegate.off('textChange'); KeyboardDelegate.off('textChange');
``` ```
## KeyboardController<a name="KeyboardController"></a> ## KeyboardController<a name="KeyboardController"></a>
...@@ -377,16 +370,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result. ...@@ -377,16 +370,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- | | -------- | ---------------------- | ---- | -------- |
| callback | AsyncCallback&lt;void> | No | Callback used to return the result.| | callback | AsyncCallback&lt;void> | No | Callback used to return the result.|
- Example **Example**
``` ```js
KeyboardController.hideKeyboard(()=>{ KeyboardController.hideKeyboard(()=>{
}); });
``` ```
...@@ -399,16 +392,16 @@ Hides the keyboard. This API uses a promise to return the result. ...@@ -399,16 +392,16 @@ Hides the keyboard. This API uses a promise to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description: | | Type | Description: |
| ---------------- | -------- | | ---------------- | -------- |
| Promise&lt;void> | Promise used to return the result.| | Promise&lt;void> | Promise used to return the result.|
- Example **Example**
``` ```js
KeyboardController.hideKeyboard(); KeyboardController.hideKeyboard();
``` ```
...@@ -424,19 +417,20 @@ Obtains the specific-length text before the cursor. This API uses an asynchronou ...@@ -424,19 +417,20 @@ Obtains the specific-length text before the cursor. This API uses an asynchronou
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;string&gt; | Yes| Text returned.|
| Name| Type| Mandatory| Description| **Example**
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;string&gt; | Yes| Text returned.|
- Example ```js
``` TextInputClient.getForward(5,(text) =>{
TextInputClient.getForward(5,(text) =>{ console.info("text = " + text);
console.info("text = " + text); });
}); ```
```
### getForward ### getForward
...@@ -446,22 +440,24 @@ Obtains the specific-length text before the cursor. This API uses a promise to r ...@@ -446,22 +440,24 @@ Obtains the specific-length text before the cursor. This API uses a promise to r
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
- Return value **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
- Example | Type | Description |
``` | ------------------------------- | ------------------------------------------------------------ |
var text = TextInputClient.getForward(5); | Promise&lt;string&gt; | Text returned. |
console.info("text = " + text);
``` **Example**
```js
var text = TextInputClient.getForward(5);
console.info("text = " + text);
```
### getBackward ### getBackward
...@@ -471,19 +467,20 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous ...@@ -471,19 +467,20 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
| callback | AsyncCallback&lt;string&gt; | Yes| Text returned.| | callback | AsyncCallback&lt;string&gt; | Yes| Text returned.|
- Example **Example**
```
TextInputClient.getBackward(5,(text)=>{ ```js
console.info("text = " + text); TextInputClient.getBackward(5,(text)=>{
}); console.info("text = " + text);
``` });
```
### getBackward ### getBackward
...@@ -493,22 +490,24 @@ Obtains the specific-length text after the cursor. This API uses a promise to re ...@@ -493,22 +490,24 @@ Obtains the specific-length text after the cursor. This API uses a promise to re
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
- Return value **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
- Example | Type | Description |
``` | ------------------------------- | ------------------------------------------------------------ |
var text = TextInputClient.getBackward(5); | Promise&lt;string&gt; | Text returned. |
console.info("text = " + text);
``` **Example**
```js
var text = TextInputClient.getBackward(5);
console.info("text = " + text);
```
### deleteForward ### deleteForward
...@@ -518,19 +517,21 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c ...@@ -518,19 +517,21 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.| | callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
**Example**
```js
TextInputClient.deleteForward(5,(isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
- Example
```
TextInputClient.deleteForward(5,(isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
### deleteForward ### deleteForward
deleteForward(length:number): Promise&lt;boolean&gt; deleteForward(length:number): Promise&lt;boolean&gt;
...@@ -539,23 +540,25 @@ Deletes the fixed-length text before the cursor. This API uses a promise to retu ...@@ -539,23 +540,25 @@ Deletes the fixed-length text before the cursor. This API uses a promise to retu
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
- Return value **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ | | Type | Description |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. | | ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
- Example
``` **Example**
var isSuccess = TextInputClient.deleteForward(5);
console.info("isSuccess = " + isSuccess); ```js
``` var isSuccess = TextInputClient.deleteForward(5);
console.info("isSuccess = " + isSuccess);
```
### deleteBackward ### deleteBackward
deleteBackward(length:number, callback: AsyncCallback&lt;boolean&gt;): void deleteBackward(length:number, callback: AsyncCallback&lt;boolean&gt;): void
...@@ -564,19 +567,20 @@ Deletes the fixed-length text after the cursor. This API uses an asynchronous ca ...@@ -564,19 +567,20 @@ Deletes the fixed-length text after the cursor. This API uses an asynchronous ca
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.| | length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.| | callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
- Example **Example**
```
TextInputClient.deleteBackward(5, (isSuccess)=>{ ```js
console.info("isSuccess = " + isSuccess); TextInputClient.deleteBackward(5, (isSuccess)=>{
}); console.info("isSuccess = " + isSuccess);
``` });
```
### deleteBackward ### deleteBackward
...@@ -586,22 +590,25 @@ Deletes the fixed-length text after the cursor. This API uses a promise to retur ...@@ -586,22 +590,25 @@ Deletes the fixed-length text after the cursor. This API uses a promise to retur
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | Name| Type| Mandatory| Description|
| length | number | Yes| Text length.| | -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
- Return value **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
- Example | Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
**Example**
```js
var isSuccess = TextInputClient.deleteBackward(5);
console.info("isSuccess = " + isSuccess);
```
```
var isSuccess = TextInputClient.deleteBackward(5);
console.info("isSuccess = " + isSuccess);
```
### sendKeyFunction ### sendKeyFunction
sendKeyFunction(action:number, callback: AsyncCallback&lt;boolean&gt;): void sendKeyFunction(action:number, callback: AsyncCallback&lt;boolean&gt;): void
...@@ -610,19 +617,20 @@ Sets the Enter key to send the text to its target. This API uses an asynchronous ...@@ -610,19 +617,20 @@ Sets the Enter key to send the text to its target. This API uses an asynchronous
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.| | action | number | Yes| Edit box attribute.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.| | callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
- Example **Example**
```
TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{ ```js
console.info("isSuccess = " + isSuccess); TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{
}); console.info("isSuccess = " + isSuccess);
``` });
```
### sendKeyFunction ### sendKeyFunction
...@@ -632,23 +640,25 @@ Sets the Enter key to send the text to its target. This API uses a promise to re ...@@ -632,23 +640,25 @@ Sets the Enter key to send the text to its target. This API uses a promise to re
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.|
- Return value | Name| Type| Mandatory| Description|
| Type | Description | | -------- | -------- | -------- | -------- |
| ------------------------------- | ------------------------------------------------------------ | | action | number | Yes| Edit box attribute.|
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
- Example **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
**Example**
```js
var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT);
console.info("isSuccess = " + isSuccess);
```
```
var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT);
console.info("isSuccess = " + isSuccess);
```
### insertText ### insertText
insertText(text:string, callback: AsyncCallback&lt;boolean&gt;): void insertText(text:string, callback: AsyncCallback&lt;boolean&gt;): void
...@@ -657,19 +667,20 @@ Inserts text. This API uses an asynchronous callback to return the result. ...@@ -657,19 +667,20 @@ Inserts text. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.| | text | string | Yes| Text to insert.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.| | callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
- Example **Example**
```
TextInputClient.insertText("test", (isSuccess)=>{ ```js
console.info("isSuccess = " + isSuccess); TextInputClient.insertText("test", (isSuccess)=>{
}); console.info("isSuccess = " + isSuccess);
``` });
```
### insertText ### insertText
...@@ -679,23 +690,25 @@ Inserts text. This API uses a promise to return the result. ...@@ -679,23 +690,25 @@ Inserts text. This API uses a promise to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
- Return value | Name| Type| Mandatory| Description|
| Type | Description | | -------- | -------- | -------- | -------- |
| ------------------------------- | ------------------------------------------------------------ | | text | string | Yes| Text to insert.|
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
- Example **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
**Example**
```js
var isSuccess = TextInputClient.insertText("test");
console.info("isSuccess = " + isSuccess);
```
```
var isSuccess = TextInputClient.insertText("test");
console.info("isSuccess = " + isSuccess);
```
### getEditorAttribute ### getEditorAttribute
getEditorAttribute(callback: AsyncCallback&lt;EditorAttribute&gt;): void getEditorAttribute(callback: AsyncCallback&lt;EditorAttribute&gt;): void
...@@ -704,16 +717,18 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to ...@@ -704,16 +717,18 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | Name | Type | Mandatory | Description |
| callback | AsyncCallback&lt;[EditorAttribute](#EditorAttribute)&gt; | Yes| Attribute of the edit box. | | ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;[EditorAttribute](#EditorAttribute)&gt; | Yes| Attribute of the edit box. |
**Example**
- Example ```js
``` TextInputClient.getEditorAttribute((EditorAttribute)=>{
TextInputClient.getEditorAttribute((EditorAttribute)=>{ });
}); ```
```
### getEditorAttribute ### getEditorAttribute
...@@ -723,15 +738,17 @@ Obtains the attribute of the edit box. This API uses a promise to return the res ...@@ -723,15 +738,17 @@ Obtains the attribute of the edit box. This API uses a promise to return the res
**System capability**: SystemCapability.Miscservices.InputMethodFramework **System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value **Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ | | Type | Description |
| Promise&lt;[EditorAttribute](#EditorAttribute)&gt; | Returns the attribute of the edit box. | | ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;[EditorAttribute](#EditorAttribute)&gt; | Returns the attribute of the edit box. |
- Example **Example**
```
var EditorAttribute = TextInputClient.getEditorAttribute(); ```js
``` var EditorAttribute = TextInputClient.getEditorAttribute();
```
## EditorAttribute<a name="EditorAttribute"></a> ## EditorAttribute<a name="EditorAttribute"></a>
......
# Pasteboard # Pasteboard
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
...@@ -19,11 +19,11 @@ import pasteboard from '@ohos.pasteboard'; ...@@ -19,11 +19,11 @@ import pasteboard from '@ohos.pasteboard';
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| MAX_RECORD_NUM<sup>7+</sup> | number | Yes | No | Maximum&nbsp;number&nbsp;of&nbsp;records&nbsp;allowed&nbsp;in&nbsp;a&nbsp;**PasteData**&nbsp;object. | | MAX_RECORD_NUM<sup>7+</sup> | number | Yes | No | Maximum number of records allowed in a **PasteData** object. |
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;HTML&nbsp;text. | | MIMETYPE_TEXT_HTML<sup>7+</sup> | string | Yes | No | MIME type of the HTML text. |
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;Want&nbsp;text. | | MIMETYPE_TEXT_WANT<sup>7+</sup> | string | Yes | No | MIME type of the Want text. |
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;plain&nbsp;text. | | MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | Yes | No | MIME type of the plain text. |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;URI&nbsp;text. | | MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes | No | MIME type of the URI text. |
## pasteboard.createPlainTextData ## pasteboard.createPlainTextData
...@@ -34,21 +34,23 @@ Creates a **PasteData** object for plain text. ...@@ -34,21 +34,23 @@ Creates a **PasteData** object for plain text.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain&nbsp;text. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | text | string | Yes | Plain text. |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
- Example **Return value**
``` | Type | Description |
var pasteData = pasteboard.createPlainTextData("content"); | -------- | -------- |
``` | [PasteData](#pastedata) | **PasteData** object with the specified content. |
**Example**
```js
var pasteData = pasteboard.createPlainTextData("content");
```
## pasteboard.createHtmlData<sup>7+</sup> ## pasteboard.createHtmlData<sup>7+</sup>
...@@ -59,22 +61,24 @@ Creates a **PasteData** object for HTML text. ...@@ -59,22 +61,24 @@ Creates a **PasteData** object for HTML text.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| htmlText | string | Yes | HTML&nbsp;text. | | -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
- Example | Type | Description |
| -------- | -------- |
``` | [PasteData](#pastedata) | **PasteData** object with the specified content. |
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html); **Example**
```
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
```
## pasteboard.createWantData<sup>7+</sup> ## pasteboard.createWantData<sup>7+</sup>
...@@ -85,25 +89,27 @@ Creates a **PasteData** object for Want text. ...@@ -85,25 +89,27 @@ Creates a **PasteData** object for Want text.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;text. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | want | [Want](js-apis-application-Want.md) | Yes | Want text. |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
- Example **Return value**
``` | Type | Description |
var object = { | -------- | -------- |
bundleName: "com.example.aafwk.test", | [PasteData](#pastedata) | **PasteData** object with the specified content. |
abilityName: "com.example.aafwk.test.TwoAbility"
}; **Example**
var pasteData = pasteboard.createWantData(object);
``` ```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
```
## pasteboard.createUriData<sup>7+</sup> ## pasteboard.createUriData<sup>7+</sup>
...@@ -114,21 +120,23 @@ Creates a **PasteData** object for URI text. ...@@ -114,21 +120,23 @@ Creates a **PasteData** object for URI text.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| uri | string | Yes | URI&nbsp;text. | | -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
- Example | Type | Description |
| -------- | -------- |
``` | [PasteData](#pastedata) | **PasteData** object with the specified content. |
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
``` **Example**
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
```
## pasteboard.createPlainTextRecord<sup>7+</sup> ## pasteboard.createPlainTextRecord<sup>7+</sup>
...@@ -139,21 +147,23 @@ Creates a **PasteDataRecord** object of the plain text type. ...@@ -139,21 +147,23 @@ Creates a **PasteDataRecord** object of the plain text type.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| text | string | Yes | Plain&nbsp;text. | | -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;plain&nbsp;text&nbsp;record. |
- Example | Type | Description |
| -------- | -------- |
``` | [PasteDataRecord](#pastedatarecord7) | New plain text record. |
var record = pasteboard.createPlainTextRecord("hello");
``` **Example**
```js
var record = pasteboard.createPlainTextRecord("hello");
```
## pasteboard.createHtmlTextRecord<sup>7+</sup> ## pasteboard.createHtmlTextRecord<sup>7+</sup>
...@@ -164,22 +174,24 @@ Creates a **PasteDataRecord** object of the HTML text type. ...@@ -164,22 +174,24 @@ Creates a **PasteDataRecord** object of the HTML text type.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| htmlText | string | Yes | HTML&nbsp;text. | | -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
**Return value**
- Return values | Type | Description |
| Type | Description | | -------- | -------- |
| -------- | -------- | | [PasteDataRecord](#pastedatarecord7) | New HTML record. |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;HTML&nbsp;record. |
- Example **Example**
``` ```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var record = pasteboard.createHtmlTextRecord(html); var record = pasteboard.createHtmlTextRecord(html);
``` ```
## pasteboard.createWantRecord<sup>7+</sup> ## pasteboard.createWantRecord<sup>7+</sup>
...@@ -190,25 +202,27 @@ Creates a **PasteDataRecord** object of the Want text type. ...@@ -190,25 +202,27 @@ Creates a **PasteDataRecord** object of the Want text type.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;text. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | want | [Want](js-apis-application-Want.md) | Yes | Want text. |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;Want&nbsp;record. |
- Example **Return value**
``` | Type | Description |
var object = { | -------- | -------- |
bundleName: "com.example.aafwk.test", | [PasteDataRecord](#pastedatarecord7) | New Want record. |
abilityName: "com.example.aafwk.test.TwoAbility"
}; **Example**
var record = pasteboard.createWantRecord(object);
``` ```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var record = pasteboard.createWantRecord(object);
```
## pasteboard.createUriRecord<sup>7+</sup> ## pasteboard.createUriRecord<sup>7+</sup>
...@@ -219,21 +233,23 @@ Creates a **PasteDataRecord** object of the URI text type. ...@@ -219,21 +233,23 @@ Creates a **PasteDataRecord** object of the URI text type.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI&nbsp;text. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | uri | string | Yes | URI text. |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;URI&nbsp;record. |
- Example **Return value**
``` | Type | Description |
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); | -------- | -------- |
``` | [PasteDataRecord](#pastedatarecord7) | New URI record. |
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
```
## PasteDataProperty<sup>7+</sup> ## PasteDataProperty<sup>7+</sup>
...@@ -244,11 +260,11 @@ Defines the properties of all data records on the pasteboard, including the time ...@@ -244,11 +260,11 @@ Defines the properties of all data records on the pasteboard, including the time
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| additions | {[key:&nbsp;string]:&nbsp;object} | Yes | Yes | Additional&nbsp;property&nbsp;data. | | additions | {[key: string]: object} | Yes | Yes | Additional property data. |
| mimeTypes | Array&lt;string&gt; | Yes | No | Non-repeating&nbsp;data&nbsp;types&nbsp;of&nbsp;the&nbsp;data&nbsp;records&nbsp;on&nbsp;the&nbsp;pasteboard. | | mimeTypes | Array&lt;string&gt; | Yes | No | Non-repeating data types of the data records on the pasteboard. |
| tag | string | Yes | Yes | User-defined&nbsp;tag. | | tag | string | Yes | Yes | User-defined tag. |
| timestamp | number | Yes | No | Timestamp&nbsp;at&nbsp;which&nbsp;the&nbsp;data&nbsp;is&nbsp;written&nbsp;to&nbsp;the&nbsp;pasteboard,&nbsp;in&nbsp;milliseconds. | | timestamp | number | Yes | No | Timestamp at which the data is written to the pasteboard, in milliseconds. |
| localOnly | boolean | Yes | Yes | Whether&nbsp;local&nbsp;access&nbsp;only&nbsp;is&nbsp;set&nbsp;for&nbsp;the&nbsp;pasteboard.<br/>-&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**true**.<br/>-&nbsp;**true**:&nbsp;The&nbsp;**PasteData**&nbsp;is&nbsp;set&nbsp;for&nbsp;local&nbsp;access&nbsp;only.<br/>-&nbsp;**false**:&nbsp;The&nbsp;**PasteData**&nbsp;can&nbsp;be&nbsp;shared&nbsp;between&nbsp;devices. | | localOnly | boolean | Yes | Yes | Whether local access only is set for the pasteboard.<br/>- The default value is **true**.<br/>- **true**: The **PasteData** is set for local access only.<br/>- **false**: The **PasteData** can be shared between devices. |
## PasteDataRecord<sup>7+</sup> ## PasteDataRecord<sup>7+</sup>
...@@ -262,63 +278,65 @@ A data record is an abstract definition of the content on the pasteboard. The pa ...@@ -262,63 +278,65 @@ A data record is an abstract definition of the content on the pasteboard. The pa
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| htmlText<sup>7+</sup> | string | Yes | No | HTML&nbsp;text. | | htmlText<sup>7+</sup> | string | Yes | No | HTML text. |
| want<sup>7+</sup> | [Want](js-apis-featureAbility.md#want) | Yes | No | Want&nbsp;text. | | want<sup>7+</sup> | [Want](js-apis-featureAbility.md#want) | Yes | No | Want text. |
| mimeType<sup>7+</sup> | string | Yes | No | Data&nbsp;type. | | mimeType<sup>7+</sup> | string | Yes | No | Data type. |
| plainText<sup>7+</sup> | string | Yes | No | Plain&nbsp;text. | | plainText<sup>7+</sup> | string | Yes | No | Plain text. |
| uri<sup>7+</sup> | string | Yes | No | URI&nbsp;text. | | uri<sup>7+</sup> | string | Yes | No | URI text. |
### convertToText<sup>7+</sup> ### convertToText<sup>7+</sup>
convertToText(): Promise&lt;string&gt; convertToText(): Promise&lt;string&gt;
Forcibly converts the content in this **PasteData** object to the plain text. This method uses a promise to return the result. Forcibly converts the content in this **PasteData** object to the plain text. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;plain&nbsp;text&nbsp;content&nbsp;after&nbsp;conversion&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the plain text content after conversion is returned. Otherwise, error information is returned. |
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText().then((data) => { **Example**
console.info('convertToText success data : ' + JSON.stringify(data));
}).catch((error) => { ```js
console.error('convertToText failed because ' + JSON.stringify(error)); var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
}); record.convertToText().then((data) => {
``` console.info('convertToText success data : ' + JSON.stringify(data));
}).catch((error) => {
console.error('convertToText failed because ' + JSON.stringify(error));
});
```
### convertToText<sup>7+</sup> ### convertToText<sup>7+</sup>
convertToText(callback: AsyncCallback&lt;string&gt;): void convertToText(callback: AsyncCallback&lt;string&gt;): void
Forcibly converts the content in this **PasteData** object to the plain text. This method uses an asynchronous callback to return the result. Forcibly converts the content in this **PasteData** object to the plain text. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;this&nbsp;callback&nbsp;is&nbsp;successful,&nbsp;the&nbsp;plain&nbsp;text&nbsp;content&nbsp;after&nbsp;conversion&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return the result. If this callback is successful, the plain text content after conversion is returned. Otherwise, error information is returned. |
- Example
**Example**
```
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); ```js
record.convertToText((err, data) => { var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
if (err) { record.convertToText((err, data) => {
console.error('convertToText failed because ' + JSON.stringify(err)); if (err) {
return; console.error('convertToText failed because ' + JSON.stringify(err));
} return;
console.info('convertToText success data : ' + JSON.stringify(data)); }
}); console.info('convertToText success data : ' + JSON.stringify(data));
``` });
```
## PasteData ## PasteData
...@@ -339,22 +357,19 @@ Obtains the plain text of the primary record. ...@@ -339,22 +357,19 @@ Obtains the plain text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
- Parameters
None
| Type | Description |
| -------- | -------- |
| string | Plain text. |
- Return values **Example**
| Type | Description |
| -------- | -------- |
| string | Plain&nbsp;text. |
- Example ```js
var pasteData = pasteboard.createPlainTextData("hello");
``` var plainText = pasteData.getPrimaryText();
var pasteData = pasteboard.createPlainTextData("hello"); ```
var plainText = pasteData.getPrimaryText();
```
### getPrimaryHtml<sup>7+</sup> ### getPrimaryHtml<sup>7+</sup>
...@@ -365,18 +380,19 @@ Obtains the HTML text of the primary record. ...@@ -365,18 +380,19 @@ Obtains the HTML text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| string | HTML&nbsp;text. |
- Example | Type | Description |
| -------- | -------- |
``` | string | HTML text. |
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html); **Example**
var htmlText = pasteData.getPrimaryHtml();
``` ```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
var htmlText = pasteData.getPrimaryHtml();
```
### getPrimaryWant<sup>7+</sup> ### getPrimaryWant<sup>7+</sup>
...@@ -387,21 +403,22 @@ Obtains the **Want** object of the primary record. ...@@ -387,21 +403,22 @@ Obtains the **Want** object of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| [Want](js-apis-featureAbility.md#want) | Want&nbsp;object. | | -------- | -------- |
| [Want](js-apis-application-Want.md) | Want object. |
**Example**
- Example ```js
var object = {
``` bundleName: "com.example.aafwk.test",
var object = { abilityName: "com.example.aafwk.test.TwoAbility"
bundleName: "com.example.aafwk.test", };
abilityName: "com.example.aafwk.test.TwoAbility" var pasteData = pasteboard.createWantData(object);
}; var want = pasteData.getPrimaryWant();
var pasteData = pasteboard.createWantData(object); ```
var want = pasteData.getPrimaryWant();
```
### getPrimaryUri<sup>7+</sup> ### getPrimaryUri<sup>7+</sup>
...@@ -412,17 +429,18 @@ Obtains the URI text of the primary record. ...@@ -412,17 +429,18 @@ Obtains the URI text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| string | URI&nbsp;text. | | -------- | -------- |
| string | URI text. |
- Example **Example**
``` ```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var uri = pasteData.getPrimaryUri(); var uri = pasteData.getPrimaryUri();
``` ```
### addTextRecord<sup>7+</sup> ### addTextRecord<sup>7+</sup>
...@@ -435,17 +453,18 @@ The pasteboard supports a maximum number of 128 data records. ...@@ -435,17 +453,18 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain&nbsp;text. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | text | string | Yes | Plain text. |
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good"); **Example**
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");
```
### addHtmlRecord<sup>7+</sup> ### addHtmlRecord<sup>7+</sup>
...@@ -458,18 +477,19 @@ The pasteboard supports a maximum number of 128 data records. ...@@ -458,18 +477,19 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| htmlText | string | Yes | HTML&nbsp;text. | | -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
**Example**
- Example ```js
var pasteData = pasteboard.createPlainTextData("hello");
``` var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createPlainTextData("hello"); pasteData.addHtmlRecord(html);
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; ```
pasteData.addHtmlRecord(html);
```
### addWantRecord<sup>7+</sup> ### addWantRecord<sup>7+</sup>
...@@ -482,21 +502,22 @@ The pasteboard supports a maximum number of 128 data records. ...@@ -482,21 +502,22 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;object. | | -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want object. |
- Example **Example**
``` ```js
var pasteData = pasteboard.createPlainTextData("hello"); var pasteData = pasteboard.createPlainTextData("hello");
var object = { var object = {
bundleName: "com.example.aafwk.test", bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility" abilityName: "com.example.aafwk.test.TwoAbility"
}; };
pasteData.addWantRecord(object); pasteData.addWantRecord(object);
``` ```
### addUriRecord<sup>7+</sup> ### addUriRecord<sup>7+</sup>
...@@ -509,17 +530,18 @@ The pasteboard supports a maximum number of 128 data records. ...@@ -509,17 +530,18 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI&nbsp;text. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | uri | string | Yes | URI text. |
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt"); **Example**
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt");
```
### addRecord<sup>7+</sup> ### addRecord<sup>7+</sup>
...@@ -532,21 +554,22 @@ The pasteboard supports a maximum number of 128 data records. ...@@ -532,21 +554,22 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | Record&nbsp;to&nbsp;add. | | -------- | -------- | -------- | -------- |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | Record to add. |
**Example**
- Example ```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
``` var textRecord = pasteboard.createPlainTextRecord("hello");
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt"); var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>";
var textRecord = pasteboard.createPlainTextRecord("hello"); var htmlRecord = pasteboard.createHtmlTextRecord(html);
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; pasteData.addRecord(textRecord);
var htmlRecord = pasteboard.createHtmlTextRecord(html); pasteData.addRecord(htmlRecord);
pasteData.addRecord(textRecord); ```
pasteData.addRecord(htmlRecord);
```
### getMimeTypes<sup>7+</sup> ### getMimeTypes<sup>7+</sup>
...@@ -557,17 +580,18 @@ Obtains **mimeTypes** in [PasteDataProperty](#pastedataproperty7) from this past ...@@ -557,17 +580,18 @@ Obtains **mimeTypes** in [PasteDataProperty](#pastedataproperty7) from this past
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| Array&lt;string&gt; | List&nbsp;of&nbsp;non-duplicate&nbsp;MIME&nbsp;types. | | -------- | -------- |
| Array&lt;string&gt; | List of non-duplicate MIME types. |
- Example **Example**
``` ```js
var pasteData = pasteboard.createPlainTextData("hello"); var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes(); var types = pasteData.getMimeTypes();
``` ```
### getPrimaryMimeType<sup>7+</sup> ### getPrimaryMimeType<sup>7+</sup>
...@@ -578,17 +602,18 @@ Obtains the data type of the primary record. ...@@ -578,17 +602,18 @@ Obtains the data type of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| string | Data&nbsp;type&nbsp;of&nbsp;the&nbsp;primary&nbsp;record. |
- Example | Type | Description |
| -------- | -------- |
``` | string | Data type of the primary record. |
var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType(); **Example**
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType();
```
### getProperty<sup>7+</sup> ### getProperty<sup>7+</sup>
...@@ -599,17 +624,18 @@ Obtains the property description object. ...@@ -599,17 +624,18 @@ Obtains the property description object.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| [PasteDataProperty](#pastedataproperty7) | Property&nbsp;description&nbsp;object. | | -------- | -------- |
| [PasteDataProperty](#pastedataproperty7) | Property description object. |
**Example**
- Example ```js
var pasteData = pasteboard.createPlainTextData("hello");
``` var property = pasteData.getProperty();
var pasteData = pasteboard.createPlainTextData("hello"); ```
var property = pasteData.getProperty();
```
### getRecordAt<sup>7+</sup> ### getRecordAt<sup>7+</sup>
...@@ -620,22 +646,24 @@ Obtains the record with the specified index. ...@@ -620,22 +646,24 @@ Obtains the record with the specified index.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| index | number | Yes | Index&nbsp;of&nbsp;the&nbsp;specified&nbsp;record. | | -------- | -------- | -------- | -------- |
| index | number | Yes | Index of the specified record. |
**Return value**
- Return values | Type | Description |
| Type | Description | | -------- | -------- |
| -------- | -------- | | [PasteDataRecord](#pastedatarecord7) | Record with the specified index. |
| [PasteDataRecord](#pastedatarecord7) | Record&nbsp;with&nbsp;the&nbsp;specified&nbsp;index. |
- Example **Example**
``` ```js
var pasteData = pasteboard.createPlainTextData("hello"); var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0); var record = pasteData.getRecordAt(0);
``` ```
### getRecordCount<sup>7+</sup> ### getRecordCount<sup>7+</sup>
...@@ -646,17 +674,18 @@ Obtains the number of data records in this pasteboard. ...@@ -646,17 +674,18 @@ Obtains the number of data records in this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| number | Number&nbsp;of&nbsp;records. |
- Example | Type | Description |
| -------- | -------- |
``` | number | Number of records. |
var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount(); **Example**
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount();
```
### getTag<sup>7+</sup> ### getTag<sup>7+</sup>
...@@ -667,17 +696,18 @@ Obtains the user-defined tag content. If the tag content is not set, null is ret ...@@ -667,17 +696,18 @@ Obtains the user-defined tag content. If the tag content is not set, null is ret
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| string | User-defined&nbsp;tag&nbsp;content&nbsp;if&nbsp;obtained&nbsp;and&nbsp;null&nbsp;if&nbsp;no&nbsp;tag&nbsp;is&nbsp;set. |
- Example | Type | Description |
| -------- | -------- |
``` | string | User-defined tag content if obtained and null if no tag is set. |
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag(); **Example**
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
### hasMimeType<sup>7+</sup> ### hasMimeType<sup>7+</sup>
...@@ -688,22 +718,24 @@ Checks whether the content of this pasteboard contains the specified data type. ...@@ -688,22 +718,24 @@ Checks whether the content of this pasteboard contains the specified data type.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| mimeType | string | Yes | Type&nbsp;of&nbsp;the&nbsp;data&nbsp;to&nbsp;query. | | -------- | -------- | -------- | -------- |
| mimeType | string | Yes | Type of the data to query. |
**Return value**
- Return values | Type | Description |
| Type | Description | | -------- | -------- |
| -------- | -------- | | boolean | Returns **true** if the specified data type exists; returns **false** otherwise. |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;specified&nbsp;data&nbsp;type&nbsp;exists;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example **Example**
``` ```js
var pasteData = pasteboard.createPlainTextData("hello"); var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
``` ```
### removeRecordAt<sup>7+</sup> ### removeRecordAt<sup>7+</sup>
...@@ -714,22 +746,24 @@ Removes the data record with a specified index from this pasteboard. ...@@ -714,22 +746,24 @@ Removes the data record with a specified index from this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified&nbsp;index. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | index | number | Yes | Specified index. |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example **Return value**
``` | Type | Description |
var pasteData = pasteboard.createPlainTextData("hello"); | -------- | -------- |
var isRemove = pasteData.removeRecordAt(0); | boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
```
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
### replaceRecordAt<sup>7+</sup> ### replaceRecordAt<sup>7+</sup>
...@@ -740,24 +774,26 @@ Replaces the data record with a specified index in this pasteboard. ...@@ -740,24 +774,26 @@ Replaces the data record with a specified index in this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified&nbsp;index. |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | New&nbsp;record. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | index | number | Yes | Specified index. |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful;&nbsp;returns&nbsp;**false**&nbsp;otherwise. | | record | [PasteDataRecord](#pastedatarecord7) | Yes | New record. |
- Example **Return value**
``` | Type | Description |
var pasteData = pasteboard.createPlainTextData("hello"); | -------- | -------- |
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt"); | boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
var isReplace = pasteData.replaceRecordAt(0, record);
``` **Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```
## pasteboard.getSystemPasteboard ## pasteboard.getSystemPasteboard
...@@ -768,21 +804,22 @@ Obtains the system pasteboard. ...@@ -768,21 +804,22 @@ Obtains the system pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| [SystemPasteboard](#systempasteboard) | System&nbsp;pasteboard. |
- Example | Type | Description |
| -------- | -------- |
``` | [SystemPasteboard](#systempasteboard) | System pasteboard. |
var systemPasteboard = pasteboard.getSystemPasteboard();
``` **Example**
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
```
## SystemPasteboard ## SystemPasteboard
Before calling any **SystemPasteboard** method, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard). Before calling any **SystemPasteboard** method, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard).
``` ```
var systemPasteboard = pasteboard.getSystemPasteboard(); var systemPasteboard = pasteboard.getSystemPasteboard();
...@@ -793,112 +830,117 @@ var systemPasteboard = pasteboard.getSystemPasteboard(); ...@@ -793,112 +830,117 @@ var systemPasteboard = pasteboard.getSystemPasteboard();
setPasteData(data:PasteData, callback:AsyncCallback&lt;void&gt;): void setPasteData(data:PasteData, callback:AsyncCallback&lt;void&gt;): void
Writes data to a pasteboard. This method uses an asynchronous callback to return the result. Writes data to a pasteboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| data | [PasteData](#pastedata) | Yes | **PasteData**&nbsp;object. | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;data&nbsp;write&nbsp;result. | | data | [PasteData](#pastedata) | Yes | **PasteData** object. |
| callback | AsyncCallback&lt;void> | Yes | Callback used to return the data write result. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("content"); ```js
var systemPasteboard = pasteboard.getSystemPasteboard(); var pasteData = pasteboard.createPlainTextData("content");
systemPasteboard.setPasteData(pasteData, (error, data) => { var systemPasteboard = pasteboard.getSystemPasteboard();
if (error) { systemPasteboard.setPasteData(pasteData, (error, data) => {
console.error('Failed to setPasteData. Cause: ' + error.message); if (error) {
return; console.error('Failed to setPasteData. Cause: ' + error.message);
} return;
console.info('setPasteData successfully.'); }
}); console.info('setPasteData successfully.');
``` });
```
### setPasteData ### setPasteData
setPasteData(data:PasteData): Promise&lt;void&gt; setPasteData(data:PasteData): Promise&lt;void&gt;
Writes data to a pasteboard. This method uses a promise to return the result. Writes data to a pasteboard. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Description |
| -------- | -------- | -------- | | Name | Type | Description |
| data | [PasteData](#pastedata) | **PasteData**&nbsp;object. | | -------- | -------- | -------- |
| data | [PasteData](#pastedata) | **PasteData** object. |
- Return values
| Type | Description | **Return value**
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;data&nbsp;write&nbsp;result. | | Type | Description |
| -------- | -------- |
- Example | Promise&lt;void&gt; | Promise used to return the data write result. |
``` **Example**
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard(); ```js
systemPasteboard.setPasteData(pasteData).then((data) => { var pasteData = pasteboard.createPlainTextData("content");
console.info('setPasteData success.'); var systemPasteboard = pasteboard.getSystemPasteboard();
}).catch((error) => { systemPasteboard.setPasteData(pasteData).then((data) => {
console.error('Failed to setPasteData. Cause: ' + error.message); console.info('setPasteData success.');
}); }).catch((error) => {
``` console.error('Failed to setPasteData. Cause: ' + error.message);
});
```
### getPasteData ### getPasteData
getPasteData( callback:AsyncCallback&lt;PasteData&gt;): void getPasteData( callback:AsyncCallback&lt;PasteData&gt;): void
Reads the system pasteboard content. This method uses an asynchronous callback to return the result. Reads the system pasteboard content. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;system&nbsp;pasteboard&nbsp;data. | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | Yes | Callback used to return the system pasteboard data. |
- Example
**Example**
```
var systemPasteboard = pasteboard.getSystemPasteboard(); ```js
systemPasteboard.getPasteData((error, pasteData) => { var systemPasteboard = pasteboard.getSystemPasteboard();
if (error) { systemPasteboard.getPasteData((error, pasteData) => {
console.error('Failed to getPasteData. Cause: ' + error.message); if (error) {
return; console.error('Failed to getPasteData. Cause: ' + error.message);
} return;
var text = pasteData.getPrimaryText(); }
}); var text = pasteData.getPrimaryText();
``` });
```
### getPasteData ### getPasteData
getPasteData(): Promise&lt;PasteData&gt; getPasteData(): Promise&lt;PasteData&gt;
Reads the system pasteboard content. This method uses a promise to return the result. Reads the system pasteboard content. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;system&nbsp;pasteboard&nbsp;data. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;[PasteData](#pastedata)&gt; | Promise used to return the system pasteboard data. |
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => { **Example**
var text = pasteData.getPrimaryText();
}).catch((error) => { ```js
console.error('Failed to getPasteData. Cause: ' + error.message); var systemPasteboard = pasteboard.getSystemPasteboard();
}) systemPasteboard.getPasteData().then((pasteData) => {
``` var text = pasteData.getPrimaryText();
}).catch((error) => {
console.error('Failed to getPasteData. Cause: ' + error.message);
})
```
### on('update')<sup>7+</sup> ### on('update')<sup>7+</sup>
...@@ -909,21 +951,22 @@ Subscribes to the content change event of the system pasteboard. If the pasteboa ...@@ -909,21 +951,22 @@ Subscribes to the content change event of the system pasteboard. If the pasteboa
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Data&nbsp;type.&nbsp;The&nbsp;value&nbsp;**update**&nbsp;indicates&nbsp;the&nbsp;pasteboard&nbsp;content&nbsp;has&nbsp;changed. |
| callback | function | Yes | Callback&nbsp;invoked&nbsp;when&nbsp;the&nbsp;pasteboard&nbsp;content&nbsp;changes. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | type | string | Yes | Data type. The value **update** indicates the pasteboard content has changed. |
var systemPasteboard = pasteboard.getSystemPasteboard(); | callback | function | Yes | Callback invoked when the pasteboard content changes. |
var listener = ()=>{
console.info('The system pasteboard has changed'); **Example**
};
systemPasteboard.on('update', listener); ```js
``` var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = ()=>{
console.info('The system pasteboard has changed');
};
systemPasteboard.on('update', listener);
```
### off('update')<sup>7+</sup> ### off('update')<sup>7+</sup>
...@@ -934,114 +977,119 @@ Unsubscribes from the system pasteboard content change event. ...@@ -934,114 +977,119 @@ Unsubscribes from the system pasteboard content change event.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| type | string | Yes | Data&nbsp;type.&nbsp;The&nbsp;value&nbsp;**update**&nbsp;indicates&nbsp;the&nbsp;pasteboard&nbsp;content&nbsp;has&nbsp;changed. | | -------- | -------- | -------- | -------- |
| callback | function | No | Callback&nbsp;invoked&nbsp;when&nbsp;the&nbsp;pasteboard&nbsp;content&nbsp;changes. | | type | string | Yes | Data type. The value **update** indicates the pasteboard content has changed. |
| callback | function | No | Callback invoked when the pasteboard content changes. |
- Example **Example**
``` ```js
systemPasteboard.off('update', listener); systemPasteboard.off('update', listener);
``` ```
### hasPasteData<sup>7+</sup> ### hasPasteData<sup>7+</sup>
hasPasteData(callback: AsyncCallback&lt;boolean&gt;): void hasPasteData(callback: AsyncCallback&lt;boolean&gt;): void
Checks whether the system pasteboard contains content. This method uses an asynchronous callback to return the result. Checks whether the system pasteboard contains content. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;pasteboard&nbsp;contains&nbsp;content;&nbsp;returns&nbsp;**false**&nbsp;otherwise. | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
- Example
**Example**
```
systemPasteboard.hasPasteData((err, data) => { ```js
if (err) { systemPasteboard.hasPasteData((err, data) => {
console.error('failed to hasPasteData because ' + JSON.stringify(err)); if (err) {
return; console.error('failed to hasPasteData because ' + JSON.stringify(err));
} return;
console.info('success hasPasteData : ' + JSON.stringify(data)); }
}); console.info('success hasPasteData : ' + JSON.stringify(data));
``` });
```
### hasPasteData<sup>7+</sup> ### hasPasteData<sup>7+</sup>
hasPasteData(): Promise&lt;boolean&gt; hasPasteData(): Promise&lt;boolean&gt;
Checks whether the system pasteboard contains content. This method uses a promise to return the result. Checks whether the system pasteboard contains content. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| Promise&lt;boolean&gt; | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;pasteboard&nbsp;contains&nbsp;content;&nbsp;returns&nbsp;**false**&nbsp;otherwise. | | -------- | -------- |
| Promise&lt;boolean&gt; | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
**Example**
- Example ```js
systemPasteboard.hasPasteData().then((data) => {
``` console.info('Operation succeeded. ' + JSON.stringify(data));
systemPasteboard.hasPasteData().then((data) => { }).catch((error) => {
console.info('Operation succeeded. ' + JSON.stringify(data)); console.error('failed to hasPasteData because ' + JSON.stringify(error));
}).catch((error) => { });
console.error('failed to hasPasteData because ' + JSON.stringify(error)); ```
});
```
### clear<sup>7+</sup> ### clear<sup>7+</sup>
clear(callback: AsyncCallback&lt;void&gt;): void clear(callback: AsyncCallback&lt;void&gt;): void
Clears the system pasteboard content. This method uses an asynchronous callback to return the result. Clears the system pasteboard content. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. | | -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
- Example
**Example**
```
systemPasteboard.clear((err, data) => { ```js
if (err) { systemPasteboard.clear((err, data) => {
console.error('failed to clear because ' + JSON.stringify(err)); if (err) {
return; console.error('failed to clear because ' + JSON.stringify(err));
} return;
console.info('success clear'); }
}); console.info('success clear');
``` });
```
### clear<sup>7+</sup> ### clear<sup>7+</sup>
clear(): Promise&lt;void&gt; clear(): Promise&lt;void&gt;
Clears the system pasteboard content. This method uses a promise to return the result. Clears the system pasteboard content. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Pasteboard **System capability**: SystemCapability.MiscServices.Pasteboard
- Return values **Return value**
| Type | Description |
| -------- | -------- | | Type | Description |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. | | -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. |
- Example
**Example**
```
systemPasteboard.clear().then((data) => { ```js
console.info('success clear'); systemPasteboard.clear().then((data) => {
}).catch((error) => { console.info('success clear');
console.error('failed to clear because ' + JSON.stringify(error)); }).catch((error) => {
}); console.error('failed to clear because ' + JSON.stringify(error));
``` });
```
\ No newline at end of file
# Upload and Download # Upload and Download
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
...@@ -37,56 +37,58 @@ import request from '@ohos.request'; ...@@ -37,56 +37,58 @@ import request from '@ohos.request';
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| NETWORK_MOBILE | number | Yes | No | Whether&nbsp;download&nbsp;is&nbsp;allowed&nbsp;when&nbsp;the&nbsp;cellular&nbsp;network&nbsp;is&nbsp;used. | | NETWORK_MOBILE | number | Yes | No | Whether download is allowed when the cellular network is used. |
| NETWORK_WIFI | number | Yes | No | Whether&nbsp;download&nbsp;is&nbsp;allowed&nbsp;when&nbsp;the&nbsp;WLAN&nbsp;is&nbsp;used. | | NETWORK_WIFI | number | Yes | No | Whether download is allowed when the WLAN is used. |
| ERROR_CANNOT_RESUME<sup>7+</sup> | number | Yes | No | Failure&nbsp;to&nbsp;resume&nbsp;the&nbsp;download&nbsp;due&nbsp;to&nbsp;an&nbsp;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&nbsp;to&nbsp;find&nbsp;a&nbsp;storage&nbsp;device&nbsp;such&nbsp;as&nbsp;an&nbsp;SD&nbsp;card. | | ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes | No | Failure to find a storage device such as an SD card. |
| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | Yes | No | Failure&nbsp;to&nbsp;download&nbsp;the&nbsp;file&nbsp;because&nbsp;it&nbsp;already&nbsp;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&nbsp;operation&nbsp;failure. | | ERROR_FILE_ERROR<sup>7+</sup> | number | Yes | No | File operation failure. |
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP&nbsp;transmission&nbsp;failure. | | ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP transmission failure. |
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes | No | Insufficient&nbsp;storage&nbsp;space. | | ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes | No | Insufficient storage space. |
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | Yes | No | Error&nbsp;caused&nbsp;by&nbsp;too&nbsp;many&nbsp;network&nbsp;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&nbsp;HTTP&nbsp;code. | | ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes | No | Unidentified HTTP code. |
| ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown&nbsp;error. | | ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown error. |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes | No | Download&nbsp;paused&nbsp;and&nbsp;queuing&nbsp;for&nbsp;WLAN&nbsp;connection,&nbsp;because&nbsp;the&nbsp;file&nbsp;size&nbsp;exceeds&nbsp;the&nbsp;maximum&nbsp;value&nbsp;allowed&nbsp;by&nbsp;a&nbsp;cellular&nbsp;network&nbsp;session. | | PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes | No | Download paused and queuing for 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&nbsp;paused&nbsp;due&nbsp;to&nbsp;unknown&nbsp;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&nbsp;paused&nbsp;due&nbsp;to&nbsp;a&nbsp;network&nbsp;connection&nbsp;problem,&nbsp;for&nbsp;example,&nbsp;network&nbsp;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&nbsp;paused&nbsp;and&nbsp;then&nbsp;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&nbsp;failure&nbsp;without&nbsp;retry. | | SESSION_FAILED<sup>7+</sup> | number | Yes | No | Download failure without retry. |
| SESSION_PAUSED<sup>7+</sup> | number | Yes | No | Download&nbsp;paused. | | SESSION_PAUSED<sup>7+</sup> | number | Yes | No | Download paused. |
| SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download&nbsp;pending. | | SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download pending. |
| SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download&nbsp;in&nbsp;progress. | | SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download in progress. |
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful&nbsp;download. | | SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful download. |
## request.upload ## request.upload
upload(config: UploadConfig): Promise&lt;UploadTask&gt; upload(config: UploadConfig): Promise&lt;UploadTask&gt;
Uploads files. This method uses a promise to return the result. Uploads files. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;upload. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
| Promise&lt;[UploadTask](#uploadtask)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;**UploadTask**&nbsp;object. |
- Example **Return value**
``` | Type | Description |
request.upload({ url: 'https://patch' }).then((data) => { | -------- | -------- |
uploadTask = data; | Promise&lt;[UploadTask](#uploadtask)&gt; | Promise used to return the **UploadTask** object. |
}).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); **Example**
})
```js
request.upload({ url: 'https://patch' }).then((data) => {
uploadTask = data;
}).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
})
``` ```
...@@ -94,28 +96,29 @@ Uploads files. This method uses a promise to return the result. ...@@ -94,28 +96,29 @@ Uploads files. This method uses a promise to return the result.
upload(config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void upload(config: UploadConfig, callback: AsyncCallback&lt;UploadTask&gt;): void
Uploads files. This method uses an asynchronous callback to return the result. Uploads files. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;upload. |
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;**UploadTask**&nbsp;object. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
request.upload({ url: 'https://patch' }, (err, data) => { | callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No | Callback used to return the **UploadTask** object. |
if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); **Example**
return;
} ```js
uploadTask = data; request.upload({ url: 'https://patch' }, (err, data) => {
}); if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return;
}
uploadTask = data;
});
``` ```
...@@ -128,32 +131,33 @@ Implements file uploads. Before using a method of this class, you must obtain an ...@@ -128,32 +131,33 @@ Implements file uploads. Before using a method 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 method uses an asynchronous callback to return the result. Subscribes to the upload progress event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;subscribe&nbsp;to.&nbsp;The&nbsp;value&nbsp;is&nbsp;**progress**&nbsp;(upload&nbsp;progress). |
| callback | function | Yes | Callback&nbsp;for&nbsp;the&nbsp;upload&nbsp;progress&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size&nbsp;of&nbsp;the&nbsp;uploaded&nbsp;files,&nbsp;in&nbsp;KB. |
| totalSize | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;files&nbsp;to&nbsp;upload,&nbsp;in&nbsp;KB. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | uploadedSize | number | Yes | Size of the uploaded files, in KB. |
uploadTask.on('progress', function callback(uploadedSize, totalSize) { | totalSize | number | Yes | Total size of the files to upload, in KB. |
console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize);
} **Example**
);
```js
uploadTask.on('progress', function callback(uploadedSize, totalSize) {
console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize);
}
);
``` ```
...@@ -161,31 +165,32 @@ Subscribes to the upload progress event. This method uses an asynchronous callba ...@@ -161,31 +165,32 @@ Subscribes to the upload progress event. This method uses an asynchronous callba
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 method uses an asynchronous callback to return the result. 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.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;subscribe&nbsp;to.&nbsp;The&nbsp;value&nbsp;is&nbsp;**headerReceive**&nbsp;(response&nbsp;header). |
| callback | function | Yes | Callback&nbsp;for&nbsp;the&nbsp;HTTP&nbsp;Response&nbsp;Header&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP&nbsp;Response&nbsp;Header. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | header | object | Yes | HTTP Response Header. |
uploadTask.on('headerReceive', function callback(headers){
console.info("upOnHeader headers:" + JSON.stringify(headers)); **Example**
}
); ```js
uploadTask.on('headerReceive', function callback(headers){
console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);
``` ```
...@@ -193,32 +198,33 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo ...@@ -193,32 +198,33 @@ 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 method uses an asynchronous callback to return the result. Unsubscribes from the upload progress event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;unsubscribe&nbsp;from.&nbsp;The&nbsp;value&nbsp;is&nbsp;**progress**&nbsp;(upload&nbsp;progress). |
| callback | function | No | Callback&nbsp;for&nbsp;the&nbsp;upload&nbsp;progress&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size&nbsp;of&nbsp;the&nbsp;uploaded&nbsp;files,&nbsp;in&nbsp;KB. |
| totalSize | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;files&nbsp;to&nbsp;upload,&nbsp;in&nbsp;KB. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | uploadedSize | number | Yes | Size of the uploaded files, in KB. |
uploadTask.off('progress', function callback(uploadedSize, totalSize) { | totalSize | number | Yes | Total size of the files to upload, in KB. |
console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize);
} **Example**
);
```js
uploadTask.off('progress', function callback(uploadedSize, totalSize) {
console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize);
}
);
``` ```
...@@ -226,31 +232,32 @@ Unsubscribes from the upload progress event. This method uses an asynchronous ca ...@@ -226,31 +232,32 @@ Unsubscribes from the upload progress event. This method uses an asynchronous ca
off(type: 'headerReceive', callback?: (header: object) =&gt; void): void off(type: 'headerReceive', callback?: (header: object) =&gt; void): void
Unsubscribes from the **headerReceive** event. This method uses an asynchronous callback to return the result. Unsubscribes from the **headerReceive** event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;unsubscribe&nbsp;from.&nbsp;The&nbsp;value&nbsp;is&nbsp;**headerReceive**&nbsp;(response&nbsp;header). |
| callback | function | No | Callback&nbsp;for&nbsp;the&nbsp;HTTP&nbsp;Response&nbsp;Header&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP&nbsp;Response&nbsp;Header. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | header | object | Yes | HTTP Response Header. |
uploadTask.off('headerReceive', function callback(headers) {
console.info("upOnHeader headers:" + JSON.stringify(headers)); **Example**
}
); ```js
uploadTask.off('headerReceive', function callback(headers) {
console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);
``` ```
...@@ -258,29 +265,30 @@ Unsubscribes from the **headerReceive** event. This method uses an asynchronous ...@@ -258,29 +265,30 @@ Unsubscribes from the **headerReceive** event. This method uses an asynchronous
remove(): Promise&lt;boolean&gt; remove(): Promise&lt;boolean&gt;
Removes this upload task. This method uses a promise to return the result. Removes this upload task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;task&nbsp;removal&nbsp;result.&nbsp;If&nbsp;**true**&nbsp;is&nbsp;returned,&nbsp;the&nbsp;task&nbsp;is&nbsp;removed.&nbsp;If&nbsp;**false**&nbsp;is&nbsp;returned,&nbsp;the&nbsp;task&nbsp;fails&nbsp;to&nbsp;be&nbsp;removed. |
- Example | 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. |
uploadTask.remove().then((result) => {
if (result) { **Example**
console.info('Upload task removed successfully. ');
} else { ```js
console.error('Failed to remove the upload task. '); uploadTask.remove().then((result) => {
} if (result) {
}).catch((err) => { console.info('Upload task removed successfully. ');
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); } else {
}); console.error('Failed to remove the upload task. ');
}
}).catch((err) => {
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});
``` ```
...@@ -288,31 +296,32 @@ Removes this upload task. This method uses a promise to return the result. ...@@ -288,31 +296,32 @@ Removes this upload task. This method uses a promise to return the result.
remove(callback: AsyncCallback&lt;boolean&gt;): void remove(callback: AsyncCallback&lt;boolean&gt;): void
Removes this upload task. This method uses an asynchronous callback to return the result. Removes this upload task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload **System capability**: SystemCapability.MiscServices.Upload
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. |
uploadTask.remove((err, result) => {
if (err) { **Example**
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
return; ```js
} uploadTask.remove((err, result) => {
if (result) { if (err) {
console.info('Upload task removed successfully.'); console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
} else { return;
console.error('Failed to remove the upload task.'); }
} if (result) {
}); console.info('Upload task removed successfully.');
} else {
console.error('Failed to remove the upload task.');
}
});
``` ```
...@@ -322,11 +331,11 @@ Removes this upload task. This method uses an asynchronous callback to return th ...@@ -322,11 +331,11 @@ Removes this upload task. This method uses an asynchronous callback to return th
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | Yes | Resource&nbsp;URL. | | url | string | Yes | Resource URL. |
| header | object | No | HTTP&nbsp;or&nbsp;HTTPS&nbsp;header&nbsp;added&nbsp;to&nbsp;an&nbsp;upload&nbsp;request. | | header | object | No | HTTP or HTTPS header added to an upload request. |
| method | string | No | Request&nbsp;methods&nbsp;available:&nbsp;**POST**&nbsp;and&nbsp;**PUT**.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**POST**. | | method | string | No | Request methods available: **POST** and **PUT**. The default value is **POST**. |
| files | Array&lt;[File](#file)&gt; | Yes | List&nbsp;of&nbsp;files&nbsp;to&nbsp;upload,&nbsp;which&nbsp;is&nbsp;submitted&nbsp;through&nbsp;**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; | No | Form&nbsp;data&nbsp;in&nbsp;the&nbsp;request&nbsp;body. | | data | Array&lt;[RequestData](#requestdata)&gt; | No | Form data in the request body. |
## File ## File
...@@ -335,10 +344,10 @@ Removes this upload task. This method uses an asynchronous callback to return th ...@@ -335,10 +344,10 @@ Removes this upload task. This method uses an asynchronous callback to return th
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| filename | string | No | File&nbsp;name&nbsp;in&nbsp;the&nbsp;header&nbsp;when&nbsp;**multipart**&nbsp;is&nbsp;used. | | filename | string | No | File name in the header when **multipart** is used. |
| name | string | No | Name&nbsp;of&nbsp;a&nbsp;form&nbsp;item&nbsp;when&nbsp;**multipart**&nbsp;is&nbsp;used.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**file**. | | name | string | No | Name of a form item when **multipart** is used. The default value is **file**. |
| uri | string | Yes | Local&nbsp;path&nbsp;for&nbsp;storing&nbsp;files.<br/>The&nbsp;**dataability**&nbsp;and&nbsp;**internal**&nbsp;protocol&nbsp;types&nbsp;are&nbsp;supported.&nbsp;However,&nbsp;the&nbsp;**internal**&nbsp;protocol&nbsp;type&nbsp;supports&nbsp;only&nbsp;temporary&nbsp;directories.&nbsp;The&nbsp;following&nbsp;is&nbsp;an&nbsp;example:<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. The following is an example:<br/>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br/>internal://cache/path/to/file.txt |
| type | string | No | Type&nbsp;of&nbsp;the&nbsp;file&nbsp;content.&nbsp;By&nbsp;default,&nbsp;the&nbsp;type&nbsp;is&nbsp;obtained&nbsp;based&nbsp;on&nbsp;the&nbsp;extension&nbsp;of&nbsp;the&nbsp;file&nbsp;name&nbsp;or&nbsp;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
...@@ -347,68 +356,71 @@ Removes this upload task. This method uses an asynchronous callback to return th ...@@ -347,68 +356,71 @@ Removes this upload task. This method uses an asynchronous callback to return th
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| name | string | Yes | Name&nbsp;of&nbsp;a&nbsp;form&nbsp;element. | | name | string | Yes | Name of a form element. |
| value | string | Yes | Value&nbsp;of&nbsp;a&nbsp;form&nbsp;element. | | value | string | Yes | Value of a form element. |
## request.download ## request.download
download(config: DownloadConfig): Promise&lt;DownloadTask&gt; download(config: DownloadConfig): Promise&lt;DownloadTask&gt;
Downloads files. This method uses a promise to return the result. Downloads files. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;download. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example **Return value**
``` | Type | Description |
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { | -------- | -------- |
downloadTask = data; | Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise used to return the result. |
}).catch((err) => {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); **Example**
})
``` ```js
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
downloadTask = data;
}).catch((err) => {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})
```
## request.download ## request.download
download(config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): void download(config: DownloadConfig, callback: AsyncCallback&lt;DownloadTask&gt;): void
Downloads files. This method uses an asynchronous callback to return the result. Downloads files. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;download. |
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
request.download({ url: 'https://xxxx/xxxxx.hap', | callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No | Callback used to return the result. |
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
if (err) { **Example**
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
return; ```js
} request.download({ url: 'https://xxxx/xxxxx.hap',
downloadTask = data; filePath: 'xxx/xxxxx.hap'}, (err, data) => {
}); if (err) {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
return;
}
downloadTask = data;
});
``` ```
...@@ -421,28 +433,29 @@ Implements file downloads. ...@@ -421,28 +433,29 @@ 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 method uses an asynchronous callback to return the result. Subscribes to the download progress event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;subscribe&nbsp;to.&nbsp;The&nbsp;value&nbsp;is&nbsp;**progress**&nbsp;(download&nbsp;progress). | | -------- | -------- | -------- | -------- |
| callback | function | Yes | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;progress&nbsp;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. |
Parameters of the callback function Parameters of the callback function
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;files,&nbsp;in&nbsp;KB. | | receivedSize | number | Yes | Size of the downloaded files, in KB. |
| totalSize | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;files&nbsp;to&nbsp;download,&nbsp;in&nbsp;KB. | | totalSize | number | Yes | Total size of the files to download, in KB. |
- Example **Example**
``` ```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) { if (err) {
console.error('Failed to request download. Cause:' + err); console.error('Failed to request download. Cause:' + err);
...@@ -461,39 +474,40 @@ Subscribes to the download progress event. This method uses an asynchronous call ...@@ -461,39 +474,40 @@ Subscribes to the download progress event. This method uses an asynchronous call
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 method uses an asynchronous callback to return the result. Unsubscribes from the download progress event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;unsubscribe&nbsp;from.&nbsp;The&nbsp;value&nbsp;is&nbsp;**progress**&nbsp;(download&nbsp;progress). |
| callback | function | No | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;progress&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;files,&nbsp;in&nbsp;KB. |
| totalSize | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;files&nbsp;to&nbsp;download,&nbsp;in&nbsp;KB. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | receivedSize | number | Yes | Size of the downloaded files, in KB. |
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { | totalSize | number | Yes | Total size of the files to download, in KB. |
if (err) {
console.error('Failed to request download. Cause:' + err); **Example**
return;
} ```js
downloadTask = data; request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
downloadTask .off('progress', function download_callback(receivedSize, totalSize) { if (err) {
console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); console.error('Failed to request download. Cause:' + err);
} return;
); }
}); downloadTask = data;
downloadTask .off('progress', function download_callback(receivedSize, totalSize) {
console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);
});
``` ```
...@@ -501,32 +515,33 @@ Unsubscribes from the download progress event. This method uses an asynchronous ...@@ -501,32 +515,33 @@ Unsubscribes from the download progress event. This method uses an asynchronous
on(type: 'complete'|'pause'|'remove', callback:() =&gt; void): void on(type: 'complete'|'pause'|'remove', callback:() =&gt; void): void
Subscribes to a download event. This method uses an asynchronous callback to return the result. Subscribes to a download event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Event&nbsp;type.<br/>-&nbsp;**complete**:&nbsp;download&nbsp;task&nbsp;completion&nbsp;event.<br/>-&nbsp;**pause**:&nbsp;download&nbsp;task&nbsp;pause&nbsp;event.<br/>-&nbsp;**remove**:&nbsp;download&nbsp;task&nbsp;removal&nbsp;event. |
| callback | function | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | 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. |
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { | callback | function | Yes | Callback used to return the result. |
if (err) {
console.error('Failed to request download. Cause:' + err); **Example**
return;
} ```js
downloadTask= data; request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
downloadTask.on('complete', function callback() { if (err) {
console.info('Download task completed.'); console.error('Failed to request download. Cause:' + err);
} return;
); }
}); downloadTask= data;
downloadTask.on('complete', function callback() {
console.info('Download task completed.');
}
);
});
``` ```
...@@ -534,32 +549,33 @@ Subscribes to a download event. This method uses an asynchronous callback to ret ...@@ -534,32 +549,33 @@ Subscribes to a download event. This method uses an asynchronous callback to ret
off(type: 'complete'|'pause'|'remove', callback?:() =&gt; void): void off(type: 'complete'|'pause'|'remove', callback?:() =&gt; void): void
Unsubscribes from the download event. This method uses an asynchronous callback to return the result. Unsubscribes from the download event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Event&nbsp;type.<br/>-&nbsp;**complete**:&nbsp;download&nbsp;task&nbsp;completion&nbsp;event.<br/>-&nbsp;**pause**:&nbsp;download&nbsp;task&nbsp;pause&nbsp;event.<br/>-&nbsp;**remove**:&nbsp;download&nbsp;task&nbsp;removal&nbsp;event. |
| callback | function | No | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | 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. |
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { | callback | function | No | Callback used to return the result. |
if (err) {
console.error('Failed to request download. Cause:' + JSON.stringify(err)); **Example**
return;
} ```js
downloadTask = data; request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
downloadTask.off('complete', function callback() { if (err) {
console.info('Download task completed.'); console.error('Failed to request download. Cause:' + JSON.stringify(err));
} return;
); }
}); downloadTask = data;
downloadTask.off('complete', function callback() {
console.info('Download task completed.');
}
);
});
``` ```
...@@ -567,38 +583,39 @@ Unsubscribes from the download event. This method uses an asynchronous callback ...@@ -567,38 +583,39 @@ Unsubscribes from the download event. This method uses an asynchronous callback
on(type: 'fail', callback: (err: number) =&gt; void): void on(type: 'fail', callback: (err: number) =&gt; void): void
Subscribes to the download task failure event. This method uses an asynchronous callback to return the result. Subscribes to the download task failure event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;subscribed&nbsp;event.&nbsp;The&nbsp;value&nbsp;is&nbsp;**fail**&nbsp;(download&nbsp;failure). |
| callback | function | Yes | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;task&nbsp;failure&nbsp;event. |
Parameters of the callback function | 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. |
| Name | Type | Mandatory | Description | Parameters of the callback function
| -------- | -------- | -------- | -------- |
| err | number | Yes | Error&nbsp;code&nbsp;of&nbsp;the&nbsp;download&nbsp;failure.&nbsp;For&nbsp;details&nbsp;about&nbsp;the&nbsp;error&nbsp;cause,&nbsp;see&nbsp;[ERROR_*](#constants). |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). |
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) { **Example**
console.error('Failed to request download. Cause:' + err);
return; ```js
} request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
downloadTask = data; if (err) {
downloadTask.on('fail', function callBack(err) { console.error('Failed to request download. Cause:' + err);
console.info('Download task failed. Cause:' + err); return;
} }
); downloadTask = data;
}); downloadTask.on('fail', function callBack(err) {
console.info('Download task failed. Cause:' + err);
}
);
});
``` ```
...@@ -606,27 +623,28 @@ Subscribes to the download task failure event. This method uses an asynchronous ...@@ -606,27 +623,28 @@ Subscribes to the download task failure event. This method uses an asynchronous
off(type: 'fail', callback?: (err: number) =&gt; void): void off(type: 'fail', callback?: (err: number) =&gt; void): void
Unsubscribes from the download task failure event. This method uses an asynchronous callback to return the result. Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;unsubscribe&nbsp;from.&nbsp;The&nbsp;value&nbsp;is&nbsp;**fail**&nbsp;(download&nbsp;failure). | | -------- | -------- | -------- | -------- |
| callback | function | No | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;task&nbsp;failure&nbsp;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. |
Parameters of the callback function Parameters of the callback function
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| err | number | Yes | Error&nbsp;code&nbsp;of&nbsp;the&nbsp;download&nbsp;failure.&nbsp;For&nbsp;details&nbsp;about&nbsp;the&nbsp;error&nbsp;cause,&nbsp;see&nbsp;[ERROR_*](#constants). | | err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). |
- Example **Example**
``` ```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> { request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) { if (err) {
console.error('Failed to request download. Cause:' + err); console.error('Failed to request download. Cause:' + err);
...@@ -645,20 +663,21 @@ Unsubscribes from the download task failure event. This method uses an asynchron ...@@ -645,20 +663,21 @@ Unsubscribes from the download task failure event. This method uses an asynchron
remove(): Promise&lt;boolean&gt; remove(): Promise&lt;boolean&gt;
Removes this download task. This method uses a promise to return the result. Removes this download task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;task&nbsp;removal&nbsp;result. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;boolean&gt; | Promise used to return the task removal result. |
**Example**
```js
downloadTask.remove().then((result) => { downloadTask.remove().then((result) => {
if (result) { if (result) {
console.info('Download task removed.'); console.info('Download task removed.');
...@@ -675,31 +694,32 @@ Removes this download task. This method uses a promise to return the result. ...@@ -675,31 +694,32 @@ Removes this download task. This method uses a promise to return the result.
remove(callback: AsyncCallback&lt;boolean&gt;): void remove(callback: AsyncCallback&lt;boolean&gt;): void
Removes this download task. This method uses an asynchronous callback to return the result. Removes this download task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;task&nbsp;removal&nbsp;result. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the task removal result. |
downloadTask.remove((err, result)=>{
if(err) { **Example**
console.error('Failed to remove the download task.');
return; ```js
} downloadTask.remove((err, result)=>{
if (result) { if(err) {
console.info('Download task removed.'); console.error('Failed to remove the download task.');
} else { return;
console.error('Failed to remove the download task.'); }
} if (result) {
}); console.info('Download task removed.');
} else {
console.error('Failed to remove the download task.');
}
});
``` ```
...@@ -707,25 +727,26 @@ Removes this download task. This method uses an asynchronous callback to return ...@@ -707,25 +727,26 @@ Removes this download task. This method uses an asynchronous callback to return
query(): Promise&lt;DownloadInfo&gt; query(): Promise&lt;DownloadInfo&gt;
Queries this download task. This method uses a promise to return the result. Queries this download task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;download&nbsp;task&nbsp;information. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information. |
downloadTask.query().then((downloadInfo) => {
console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) **Example**
}) .catch((err) => {
console.error('Failed to query the download task. Cause:' + err) ```js
}); downloadTask.query().then((downloadInfo) => {
console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
console.error('Failed to query the download task. Cause:' + err)
});
``` ```
...@@ -733,27 +754,28 @@ Queries this download task. This method uses a promise to return the result. ...@@ -733,27 +754,28 @@ Queries this download task. This method uses a promise to return the result.
query(callback: AsyncCallback&lt;DownloadInfo&gt;): void query(callback: AsyncCallback&lt;DownloadInfo&gt;): void
Queries this download task. This method uses an asynchronous callback to return the result. Queries this download task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;download&nbsp;task&nbsp;information. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | Yes | Callback used to return the download task information. |
downloadTask.query((err, downloadInfo)=>{
if(err) { **Example**
console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else { ```js
console.info('download query success. data:'+ JSON.stringify(downloadInfo)); downloadTask.query((err, downloadInfo)=>{
} if(err) {
}); console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else {
console.info('download query success. data:'+ JSON.stringify(downloadInfo));
}
});
``` ```
...@@ -761,25 +783,26 @@ Queries this download task. This method uses an asynchronous callback to return ...@@ -761,25 +783,26 @@ Queries this download task. This method uses an asynchronous callback to return
queryMimeType(): Promise&lt;string&gt; queryMimeType(): Promise&lt;string&gt;
Queries **MimeType** of this download task. This method uses a promise to return the result. Queries **MimeType** of this download task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;string&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;**MimeType**&nbsp;of&nbsp;the&nbsp;download&nbsp;task. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;string&gt; | Promise used to return **MimeType** of the download task. |
downloadTask.queryMimeType().then((data) => {
console.info('Download task queried. Data:' + JSON.stringify(data)); **Example**
}).catch((err) => {
console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) ```js
}); downloadTask.queryMimeType().then((data) => {
console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});
``` ```
...@@ -787,27 +810,28 @@ Queries **MimeType** of this download task. This method uses a promise to return ...@@ -787,27 +810,28 @@ Queries **MimeType** of this download task. This method uses a promise to return
queryMimeType(callback: AsyncCallback&lt;string&gt;): void; queryMimeType(callback: AsyncCallback&lt;string&gt;): void;
Queries **MimeType** of this download task. This method uses an asynchronous callback to return the result. Queries **MimeType** of this download task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;**MimeType**&nbsp;of&nbsp;the&nbsp;download&nbsp;task. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return **MimeType** of the download task. |
downloadTask.queryMimeType((err, data)=>{
if(err) { **Example**
console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else { ```js
console.info('Download task queried. data:' + JSON.stringify(data)); downloadTask.queryMimeType((err, data)=>{
} if(err) {
}); console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
} else {
console.info('Download task queried. data:' + JSON.stringify(data));
}
});
``` ```
...@@ -815,29 +839,30 @@ Queries **MimeType** of this download task. This method uses an asynchronous cal ...@@ -815,29 +839,30 @@ Queries **MimeType** of this download task. This method uses an asynchronous cal
pause(): Promise&lt;void&gt; pause(): Promise&lt;void&gt;
Pauses this download task. This method uses a promise to return the result. Pauses this download task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;download&nbsp;task&nbsp;pause&nbsp;result. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;void&gt; | Promise used to return the download task pause result. |
downloadTask.pause().then((result) => {
if (result) { **Example**
console.info('Download task paused. ');
} else { ```js
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); downloadTask.pause().then((result) => {
} if (result) {
}).catch((err) => { console.info('Download task paused. ');
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); } else {
}); console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
}
}).catch((err) => {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});
``` ```
...@@ -845,31 +870,32 @@ Pauses this download task. This method uses a promise to return the result. ...@@ -845,31 +870,32 @@ Pauses this download task. This method uses a promise to return the result.
pause(callback: AsyncCallback&lt;void&gt;): void pause(callback: AsyncCallback&lt;void&gt;): void
Pauses this download task. This method uses an asynchronous callback to return the result. Pauses this download task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
downloadTask.pause((err, result)=>{
if(err) { **Example**
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
return; ```js
} downloadTask.pause((err, result)=>{
if (result) { if(err) {
console.info('Download task paused. '); console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
} else { return;
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); }
} if (result) {
}); console.info('Download task paused. ');
} else {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
}
});
``` ```
...@@ -877,30 +903,31 @@ Pauses this download task. This method uses an asynchronous callback to return t ...@@ -877,30 +903,31 @@ Pauses this download task. This method uses an asynchronous callback to return t
resume(): Promise&lt;void&gt; resume(): Promise&lt;void&gt;
Resumes this download task. This method uses a promise to return the result. Resumes this download task. This API uses a promise to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;void&gt; | Promise used to return the result. |
downloadTask.resume().then((result) => {
if (result) { **Example**
console.info('Download task resumed.')
} else { ```js
console.error('Failed to resume the download task. '); downloadTask.resume().then((result) => {
} if (result) {
console.info('Download task resumed.') console.info('Download task resumed.')
}).catch((err) => { } else {
console.error('Failed to resume the download task. Cause:' + err); console.error('Failed to resume the download task. ');
}); }
console.info('Download task resumed.')
}).catch((err) => {
console.error('Failed to resume the download task. Cause:' + err);
});
``` ```
...@@ -908,31 +935,32 @@ Resumes this download task. This method uses a promise to return the result. ...@@ -908,31 +935,32 @@ Resumes this download task. This method uses a promise to return the result.
resume(callback: AsyncCallback&lt;void&gt;): void resume(callback: AsyncCallback&lt;void&gt;): void
Resumes this download task. This method uses an asynchronous callback to return the result. Resumes this download task. This API uses an asynchronous callback to return the result.
**Required permission**: ohos.permission.INTERNET **Required permission**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download **System capability**: SystemCapability.MiscServices.Download
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
downloadTask.resume((err, result)=>{
if (err) { **Example**
console.error('Failed to resume the download task. Cause:' + err);
return; ```js
} downloadTask.resume((err, result)=>{
if (result) { if (err) {
console.info('Download task resumed.'); console.error('Failed to resume the download task. Cause:' + err);
} else { return;
console.error('Failed to resume the download task.'); }
} if (result) {
}); console.info('Download task resumed.');
} else {
console.error('Failed to resume the download task.');
}
});
``` ```
...@@ -942,14 +970,14 @@ Resumes this download task. This method uses an asynchronous callback to return ...@@ -942,14 +970,14 @@ Resumes this download task. This method uses an asynchronous callback to return
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| url | string | Yes | Resource&nbsp;URL. | | url | string | Yes | Resource URL. |
| header | object | No | HTTP&nbsp;or&nbsp;HTTPS&nbsp;header&nbsp;added&nbsp;to&nbsp;a&nbsp;download&nbsp;request. | | header | object | No | HTTP or HTTPS header added to a download request. |
| enableMetered | boolean | No | Download&nbsp;allowed&nbsp;in&nbsp;metered&nbsp;connections. | | enableMetered | boolean | No | Download allowed in metered connections. |
| enableRoaming | boolean | No | Download&nbsp;allowed&nbsp;on&nbsp;a&nbsp;roaming&nbsp;network. | | enableRoaming | boolean | No | Download allowed on a roaming network. |
| description | string | No | Description&nbsp;of&nbsp;the&nbsp;download&nbsp;session. | | description | string | No | Description of the download session. |
| filePath<sup>7+</sup> | string | No | Download&nbsp;path.&nbsp;(The&nbsp;default&nbsp;path&nbsp;is&nbsp;[ERROR:Invalid&nbsp;link:en-us_topic_0000001135742582.xml#xref8132147102215,link:en-us_topic_0000001127125012.xml#section1856519365229](en-us_topic_0000001127125012.xml#section1856519365229)).<br/>-&nbsp;filePath:'workspace/test.txt':&nbsp;The&nbsp;**workspace**&nbsp;directory&nbsp;is&nbsp;created&nbsp;in&nbsp;the&nbsp;default&nbsp;path&nbsp;to&nbsp;store&nbsp;files.<br/>-&nbsp;filePath:'test.txt':&nbsp;Files&nbsp;are&nbsp;stored&nbsp;in&nbsp;the&nbsp;default&nbsp;path.<br/>-&nbsp;filePath:'workspace/':&nbsp;The&nbsp;**workspace**&nbsp;directory&nbsp;is&nbsp;created&nbsp;in&nbsp;the&nbsp;default&nbsp;path&nbsp;to&nbsp;store&nbsp;files. | | filePath<sup>7+</sup> | string | No | Download path. (The default path is [ERROR:Invalid link:en-us_topic_0000001135742582.xml#xref8132147102215,link:en-us_topic_0000001127125012.xml#section1856519365229](en-us_topic_0000001127125012.xml#section1856519365229)).<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&nbsp;type&nbsp;allowed&nbsp;for&nbsp;download. | | networkType | number | No | Network type allowed for download. |
| title | string | No | Title&nbsp;of&nbsp;the&nbsp;download&nbsp;session. | | title | string | No | Title of the download session. |
## DownloadInfo<sup>7+</sup> ## DownloadInfo<sup>7+</sup>
...@@ -958,14 +986,14 @@ Resumes this download task. This method uses an asynchronous callback to return ...@@ -958,14 +986,14 @@ Resumes this download task. This method uses an asynchronous callback to return
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| downloadId | number | Yes | ID&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. | | downloadId | number | Yes | ID of the downloaded file. |
| failedReason | number | No | Download&nbsp;failure&nbsp;cause,&nbsp;which&nbsp;can&nbsp;be&nbsp;any&nbsp;constant&nbsp;of&nbsp;[ERROR_*](#constants). | | failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). |
| fileName | string | Yes | Name&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. | | fileName | string | Yes | Name of the downloaded file. |
| filePath | string | Yes | URI&nbsp;of&nbsp;the&nbsp;saved&nbsp;file. | | filePath | string | Yes | URI of the saved file. |
| pausedReason | number | No | Reason&nbsp;for&nbsp;session&nbsp;pause,&nbsp;which&nbsp;can&nbsp;be&nbsp;any&nbsp;constant&nbsp;of&nbsp;[PAUSED_*](#constants). | | pausedReason | number | No | Reason for session pause, which can be any constant of [PAUSED_*](#constants). |
| status | number | Yes | Download&nbsp;status&nbsp;code,&nbsp;which&nbsp;can&nbsp;be&nbsp;any&nbsp;constant&nbsp;of&nbsp;[SESSION_*](#constants). | | status | number | Yes | Download status code, which can be any constant of [SESSION_*](#constants). |
| targetURI | string | Yes | URI&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. | | targetURI | string | Yes | URI of the downloaded file. |
| downloadTitle | string | Yes | Title&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. | | downloadTitle | string | Yes | Title of the downloaded file. |
| downloadTotalBytes | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file&nbsp;(int&nbsp;bytes). | | downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). |
| description | string | Yes | Description&nbsp;of&nbsp;the&nbsp;file&nbsp;to&nbsp;download. | | description | string | Yes | Description of the file to download. |
| downloadedBytes | number | Yes | Size&nbsp;of&nbsp;the&nbsp;files&nbsp;downloaded&nbsp;(int&nbsp;bytes). | | downloadedBytes | number | Yes | Size of the files downloaded (int bytes). |
# Setting the System Time # Setting the System Time
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
``` ```
import systemTime from '@ohos.systemTime'; import systemTime from '@ohos.systemTime';
``` ```
...@@ -22,16 +22,17 @@ Sets the system time. This API uses an asynchronous callback to return the resul ...@@ -22,16 +22,17 @@ Sets the system time. This API uses an asynchronous callback to return the resul
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | time | number | Yes| Timestamp to set, in milliseconds.|
// Set the system time to 2021-01-20 02:36:25. | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
**Example**
```js
// Set the system time to 2021-01-20 02:36:25.
var time = 1611081385000; var time = 1611081385000;
systemTime.setTime(time, (error, data) => { systemTime.setTime(time, (error, data) => {
if (error) { if (error) {
...@@ -53,26 +54,28 @@ Sets the system time. This API uses a promise to return the result. ...@@ -53,26 +54,28 @@ Sets the system time. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | time | number | Yes| Timestamp to set, in milliseconds.|
| Promise&lt;void&gt; | Promise used to return the result.|
- Example **Return value**
``` | Type| Description|
// Set the system time to 2021-01-20 02:36:25. | -------- | -------- |
var time = 1611081385000; | Promise&lt;void&gt; | Promise used to return the result.|
systemTime.setTime(time).then((data) => {
console.log(`systemTime.setTime success data : ` + JSON.stringify(data)); **Example**
}).catch((error) => {
console.error(`failed to systemTime.setTime because ` + JSON.stringify(error)); ```js
}); // Set the system time to 2021-01-20 02:36:25.
var time = 1611081385000;
systemTime.setTime(time).then((data) => {
console.log(`systemTime.setTime success data : ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to systemTime.setTime because ` + JSON.stringify(error));
});
``` ```
...@@ -84,15 +87,16 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal ...@@ -84,15 +87,16 @@ Obtains the time elapsed since the Unix epoch. This API uses an asynchronous cal
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
**Example**
```js
systemTime.getCurrentTime(true, (error, data) => { systemTime.getCurrentTime(true, (error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error)); console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error));
...@@ -111,19 +115,21 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return ...@@ -111,19 +115,21 @@ Obtains the time elapsed since the Unix epoch. This API uses a promise to return
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| Promise&lt;number&gt; | Promise used to return the time.|
- Example **Return value**
``` | Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getCurrentTime().then((data) => { systemTime.getCurrentTime().then((data) => {
console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data)); console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
...@@ -140,15 +146,16 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -140,15 +146,16 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
**Example**
```js
systemTime.getRealActiveTime(true, (error, data) => { systemTime.getRealActiveTime(true, (error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error)); console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error));
...@@ -167,19 +174,21 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This ...@@ -167,19 +174,21 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| Promise&lt;number&gt; | Promise used to return the time.|
- Example **Return value**
``` | Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getCurrentTime().then((data) => { systemTime.getCurrentTime().then((data) => {
console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data)); console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
...@@ -196,15 +205,16 @@ Obtains the time elapsed since system start, including the deep sleep time. This ...@@ -196,15 +205,16 @@ Obtains the time elapsed since system start, including the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|
**Example**
```js
systemTime.getRealTime(true, (error, data) => { systemTime.getRealTime(true, (error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error)); console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error));
...@@ -223,19 +233,21 @@ Obtains the time elapsed since system start, including the deep sleep time. This ...@@ -223,19 +233,21 @@ Obtains the time elapsed since system start, including the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| Promise&lt;number&gt; | Promise used to return the time.|
- Example **Return value**
``` | Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getRealTime().then((data) => { systemTime.getRealTime().then((data) => {
console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data)); console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
...@@ -254,15 +266,16 @@ Sets the system date. This API uses an asynchronous callback to return the resul ...@@ -254,15 +266,16 @@ Sets the system date. This API uses an asynchronous callback to return the resul
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | date | Date | Yes| Target date to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
**Example**
```js
var data = new Date("October 13, 2020 11:13:00"); var data = new Date("October 13, 2020 11:13:00");
systemTime.setDate(data,(error, data) => { systemTime.setDate(data,(error, data) => {
if (error) { if (error) {
...@@ -284,19 +297,21 @@ Sets the system date. This API uses a promise to return the result. ...@@ -284,19 +297,21 @@ Sets the system date. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | date | Date | Yes| Target date to set.|
| Promise&lt;void&gt; | Promise used to return the result.|
- Example **Return value**
``` | Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
var data = new Date("October 13, 2020 11:13:00"); var data = new Date("October 13, 2020 11:13:00");
systemTime.setDate(data).then((value) => { systemTime.setDate(data).then((value) => {
console.log(`systemTime.setDate success data : ` + JSON.stringify(value)); console.log(`systemTime.setDate success data : ` + JSON.stringify(value));
...@@ -314,14 +329,15 @@ Obtains the current system date. This API uses an asynchronous callback to retur ...@@ -314,14 +329,15 @@ Obtains the current system date. This API uses an asynchronous callback to retur
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Date&gt; | Yes| Callback used to return the current system date.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;Date&gt; | Yes| Callback used to return the current system date.|
**Example**
```js
systemTime.getDate((error, data) => { systemTime.getDate((error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.getDate because ` + JSON.stringify(error)); console.error(`failed to systemTime.getDate because ` + JSON.stringify(error));
...@@ -340,14 +356,15 @@ Obtains the current system date. This API uses a promise to return the result. ...@@ -340,14 +356,15 @@ Obtains the current system date. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- Return value **Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;Date&gt; | Promise used to return the current system date.|
- Example | Type| Description|
| -------- | -------- |
``` | Promise&lt;Date&gt; | Promise used to return the current system date.|
**Example**
```js
systemTime.getDate().then((data) => { systemTime.getDate().then((data) => {
console.log(`systemTime.getDate success data : ` + JSON.stringify(data)); console.log(`systemTime.getDate success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
...@@ -366,15 +383,16 @@ Sets the system time zone. This API uses an asynchronous callback to return the ...@@ -366,15 +383,16 @@ Sets the system time zone. This API uses an asynchronous callback to return the
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | timezone | string | Yes| System time zone to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|
**Example**
```js
systemTime.setTimezone('Asia/Shanghai', (error, data) => { systemTime.setTimezone('Asia/Shanghai', (error, data) => {
if (error) { if (error) {
console.error('failed to systemTime.setTimezone because ' + JSON.stringify(error)); console.error('failed to systemTime.setTimezone because ' + JSON.stringify(error));
...@@ -395,19 +413,21 @@ Sets the system time zone. This API uses a promise to return the result. ...@@ -395,19 +413,21 @@ Sets the system time zone. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
- Return value | Name| Type| Mandatory| Description|
| Type| Description| | -------- | -------- | -------- | -------- |
| -------- | -------- | | timezone | string | Yes| System time zone to set.|
| Promise&lt;void&gt; | Promise used to return the result.|
- Example **Return value**
``` | Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
systemTime.setTimezone('Asia/Shanghai').then((data) => { systemTime.setTimezone('Asia/Shanghai').then((data) => {
console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data)); console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
...@@ -424,14 +444,15 @@ Obtains the system time zone. This API uses an asynchronous callback to return t ...@@ -424,14 +444,15 @@ Obtains the system time zone. This API uses an asynchronous callback to return t
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- **Parameters** **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the system time zone.|
- Example | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the system time zone.|
**Example**
```js
systemTime.getTimezone((error, data) => { systemTime.getTimezone((error, data) => {
if (error) { if (error) {
console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error)); console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error));
...@@ -450,14 +471,15 @@ Obtains the system time zone. This API uses a promise to return the result. ...@@ -450,14 +471,15 @@ Obtains the system time zone. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time **System capability**: SystemCapability.MiscServices.Time
- Return value **Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return the system time zone.|
- Example | Type| Description|
| -------- | -------- |
``` | Promise&lt;string&gt; | Promise used to return the system time zone.|
**Example**
```js
systemTime.getTimezone().then((data) => { systemTime.getTimezone().then((data) => {
console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data)); console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
......
# Wallpaper # Wallpaper
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**<br>The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. >
## Modules to Import ## Modules to Import
...@@ -21,8 +21,8 @@ Defines the wallpaper type. ...@@ -21,8 +21,8 @@ Defines the wallpaper type.
| Name | Description | | Name | Description |
| -------- | -------- | | -------- | -------- |
| WALLPAPER_LOCKSCREEN | Lock&nbsp;screen&nbsp;wallpaper. | | WALLPAPER_LOCKSCREEN | Lock screen wallpaper. |
| WALLPAPER_SYSTEM | Home&nbsp;screen&nbsp;wallpaper. | | WALLPAPER_SYSTEM | Home screen wallpaper. |
## wallpaper.getColors ## wallpaper.getColors
...@@ -36,12 +36,12 @@ Obtains the main color information of the wallpaper of a specified type. ...@@ -36,12 +36,12 @@ Obtains the main color information of the wallpaper of a specified type.
- Parameters - Parameters
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;main&nbsp;color&nbsp;information&nbsp;of&nbsp;the&nbsp;wallpaper. | | callback | AsyncCallback&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes | Callback used to return the main color information of the wallpaper. |
- Example - Example
``` ```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) { if (error) {
console.error(`failed to getColors because: ` + JSON.stringify(error)); console.error(`failed to getColors because: ` + JSON.stringify(error));
...@@ -60,25 +60,27 @@ Obtains the main color information of the wallpaper of a specified type. ...@@ -60,25 +60,27 @@ Obtains the main color information of the wallpaper of a specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| Promise&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;main&nbsp;color&nbsp;information&nbsp;of&nbsp;the&nbsp;wallpaper. |
- Example **Return value**
``` | Type | Description |
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { | -------- | -------- |
console.log(`success to getColors.`); | Promise&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Promise used to return the main color information of the wallpaper. |
}).catch((error) => {
console.error(`failed to getColors because: ` + JSON.stringify(error)); **Example**
});
``` ```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getColors.`);
}).catch((error) => {
console.error(`failed to getColors because: ` + JSON.stringify(error));
});
```
## wallpaper.getId ## wallpaper.getId
...@@ -89,23 +91,24 @@ Obtains the ID of the wallpaper of the specified type. ...@@ -89,23 +91,24 @@ Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;wallpaper&nbsp;ID.&nbsp;If&nbsp;the&nbsp;wallpaper&nbsp;of&nbsp;the&nbsp;specified&nbsp;type&nbsp;is&nbsp;configured,&nbsp;a&nbsp;number&nbsp;greater&nbsp;than&nbsp;or&nbsp;equal&nbsp;to&nbsp;**0**&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;**-1**&nbsp;is&nbsp;returned.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;-1&nbsp;to&nbsp;2^31-1. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the wallpaper ID. If the wallpaper of the specified type is configured, a number greater than or equal to **0** is returned. Otherwise, **-1** is returned. The value ranges from -1 to 2^31-1. |
if (error) {
console.error(`failed to getId because: ` + JSON.stringify(error)); **Example**
return;
} ```js
console.log(`success to getId: ` + JSON.stringify(data)); wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
}); if (error) {
``` console.error(`failed to getId because: ` + JSON.stringify(error));
return;
}
console.log(`success to getId: ` + JSON.stringify(data));
});
```
## wallpaper.getId ## wallpaper.getId
...@@ -116,26 +119,27 @@ Obtains the ID of the wallpaper of the specified type. ...@@ -116,26 +119,27 @@ Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
- Parameters | Name | Type | Mandatory | Description |
| Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;number&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;wallpaper&nbsp;ID.&nbsp;If&nbsp;this&nbsp;type&nbsp;of&nbsp;wallpaper&nbsp;is&nbsp;configured,&nbsp;a&nbsp;number&nbsp;greater&nbsp;than&nbsp;or&nbsp;equal&nbsp;to&nbsp;**0**&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;**-1**&nbsp;is&nbsp;returned.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;-1&nbsp;to&nbsp;2^31-1. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;number&gt; | Promise used to return the wallpaper ID. If this type of wallpaper is configured, a number greater than or equal to **0** is returned. Otherwise, **-1** is returned. The value ranges from -1 to 2^31-1. |
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getId: ` + JSON.stringify(data)); **Example**
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error)); ```js
}); wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
``` console.log(`success to getId: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error));
});
```
## wallpaper.getMinHeight ## wallpaper.getMinHeight
...@@ -146,22 +150,23 @@ Obtains the minimum height of the wallpaper. ...@@ -146,22 +150,23 @@ Obtains the minimum height of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;minimum&nbsp;wallpaper&nbsp;height,&nbsp;in&nbsp;pixels.&nbsp;If&nbsp;the&nbsp;return&nbsp;value&nbsp;is&nbsp;**0**,&nbsp;no&nbsp;wallpaper&nbsp;is&nbsp;set.&nbsp;In&nbsp;this&nbsp;case,&nbsp;the&nbsp;default&nbsp;height&nbsp;should&nbsp;be&nbsp;used&nbsp;instead. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead. |
wallpaper.getMinHeight((error, data) => {
if (error) { **Example**
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
return; ```js
} wallpaper.getMinHeight((error, data) => {
console.log(`success to getMinHeight: ` + JSON.stringify(data)); if (error) {
}); console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
``` return;
}
console.log(`success to getMinHeight: ` + JSON.stringify(data));
});
```
## wallpaper.getMinHeight ## wallpaper.getMinHeight
...@@ -172,21 +177,21 @@ Obtains the minimum height of the wallpaper. ...@@ -172,21 +177,21 @@ Obtains the minimum height of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
**Return value**
- Return values | Type | Description |
| Type | Description | | -------- | -------- |
| -------- | -------- | | Promise&lt;number&gt; | Promise used to return the minimum wallpaper height, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default height should be used instead. |
| Promise&lt;number&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;minimum&nbsp;wallpaper&nbsp;height,&nbsp;in&nbsp;pixels.&nbsp;If&nbsp;the&nbsp;return&nbsp;value&nbsp;is&nbsp;**0**,&nbsp;no&nbsp;wallpaper&nbsp;is&nbsp;set.&nbsp;In&nbsp;this&nbsp;case,&nbsp;the&nbsp;default&nbsp;height&nbsp;should&nbsp;be&nbsp;used&nbsp;instead. |
- Example **Example**
``` ```js
wallpaper.getMinHeight().then((data) => { wallpaper.getMinHeight().then((data) => {
console.log(`success to getMinHeight: ` + JSON.stringify(data)); console.log(`success to getMinHeight: ` + JSON.stringify(data));
}).catch((error) => { }).catch((error) => {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error)); console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
}); });
``` ```
## wallpaper.getMinWidth ## wallpaper.getMinWidth
...@@ -197,23 +202,23 @@ Obtains the minimum width of the wallpaper. ...@@ -197,23 +202,23 @@ Obtains the minimum width of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
- Parameters | Name | Type | Mandatory | Description |
| Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- | | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;minimum&nbsp;wallpaper&nbsp;width,&nbsp;in&nbsp;pixels.&nbsp;If&nbsp;the&nbsp;return&nbsp;value&nbsp;is&nbsp;**0**,&nbsp;no&nbsp;wallpaper&nbsp;is&nbsp;set.&nbsp;In&nbsp;this&nbsp;case,&nbsp;the&nbsp;default&nbsp;width&nbsp;should&nbsp;be&nbsp;used&nbsp;instead. |
- Example **Example**
``` ```js
wallpaper.getMinWidth((error, data) => { wallpaper.getMinWidth((error, data) => {
if (error) { if (error) {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error)); console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
return; return;
} }
console.log(`success to getMinWidth: ` + JSON.stringify(data)); console.log(`success to getMinWidth: ` + JSON.stringify(data));
}); });
``` ```
## wallpaper.getMinWidth ## wallpaper.getMinWidth
...@@ -224,20 +229,21 @@ Obtains the minimum width of the wallpaper. ...@@ -224,20 +229,21 @@ Obtains the minimum width of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;number&gt; | Promised&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;minimum&nbsp;wallpaper&nbsp;width,&nbsp;in&nbsp;pixels.&nbsp;If&nbsp;the&nbsp;return&nbsp;value&nbsp;is&nbsp;**0**,&nbsp;no&nbsp;wallpaper&nbsp;is&nbsp;set.&nbsp;In&nbsp;this&nbsp;case,&nbsp;the&nbsp;default&nbsp;width&nbsp;should&nbsp;be&nbsp;used&nbsp;instead. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;number&gt; | Promised used to return the minimum wallpaper width, in pixels. If the return value is **0**, no wallpaper is set. In this case, the default width should be used instead. |
wallpaper.getMinWidth().then((data) => {
console.log(`success to getMinWidth: ` + JSON.stringify(data)); **Example**
}).catch((error) => {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error)); ```js
}); wallpaper.getMinWidth().then((data) => {
``` console.log(`success to getMinWidth: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
});
```
## wallpaper.isChangePermitted ## wallpaper.isChangePermitted
...@@ -248,22 +254,23 @@ Checks whether to allow the application to change the wallpaper for the current ...@@ -248,22 +254,23 @@ Checks whether to allow the application to change the wallpaper for the current
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;queried&nbsp;result.&nbsp;Returns&nbsp;**true**&nbsp;if&nbsp;it&nbsp;is&nbsp;allowed;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the queried result. Returns **true** if it is allowed; returns **false** otherwise. |
wallpaper.isChangePermitted((error, data) => {
if (error) { **Example**
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
return; ```js
} wallpaper.isChangePermitted((error, data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data)); if (error) {
}); console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
``` return;
}
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
});
```
## wallpaper.isChangePermitted ## wallpaper.isChangePermitted
...@@ -274,20 +281,21 @@ Checks whether to allow the application to change the wallpaper for the current ...@@ -274,20 +281,21 @@ Checks whether to allow the application to change the wallpaper for the current
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;whether&nbsp;to&nbsp;allow&nbsp;the&nbsp;application&nbsp;to&nbsp;change&nbsp;the&nbsp;wallpaper&nbsp;for&nbsp;the&nbsp;current&nbsp;user.&nbsp;Returns&nbsp;**true**&nbsp;if&nbsp;it&nbsp;is&nbsp;allowed;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;boolean&gt; | Promise used to return whether to allow the application to change the wallpaper for the current user. Returns **true** if it is allowed; returns **false** otherwise. |
wallpaper.isChangePermitted().then((data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data)); **Example**
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error)); ```js
}); wallpaper.isChangePermitted().then((data) => {
``` console.log(`success to isChangePermitted: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
});
```
## wallpaper.isOperationAllowed ## wallpaper.isOperationAllowed
...@@ -298,22 +306,23 @@ Checks whether the user is allowed to set wallpapers. ...@@ -298,22 +306,23 @@ Checks whether the user is allowed to set wallpapers.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;whether&nbsp;the&nbsp;user&nbsp;is&nbsp;allowed&nbsp;to&nbsp;set&nbsp;wallpapers.&nbsp;Returns&nbsp;**true**&nbsp;if&nbsp;it&nbsp;is&nbsp;allowed;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return whether the user is allowed to set wallpapers. Returns **true** if it is allowed; returns **false** otherwise. |
wallpaper.isOperationAllowed((error, data) => {
if (error) { **Example**
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
return; ```js
} wallpaper.isOperationAllowed((error, data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data)); if (error) {
}); console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
``` return;
}
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
});
```
## wallpaper.isOperationAllowed ## wallpaper.isOperationAllowed
...@@ -324,20 +333,21 @@ Checks whether the user is allowed to set wallpapers. ...@@ -324,20 +333,21 @@ Checks whether the user is allowed to set wallpapers.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Return values **Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;whether&nbsp;the&nbsp;user&nbsp;is&nbsp;allowed&nbsp;to&nbsp;set&nbsp;wallpapers.&nbsp;Returns&nbsp;**true**&nbsp;if&nbsp;it&nbsp;is&nbsp;allowed;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
- Example | Type | Description |
| -------- | -------- |
``` | Promise&lt;boolean&gt; | Promise used to return whether the user is allowed to set wallpapers. Returns **true** if it is allowed; returns **false** otherwise. |
wallpaper.isOperationAllowed().then((data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data)); **Example**
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error)); ```js
}); wallpaper.isOperationAllowed().then((data) => {
``` console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
});
```
## wallpaper.reset ## wallpaper.reset
...@@ -350,23 +360,24 @@ Removes a wallpaper of the specified type and restores the default one. ...@@ -350,23 +360,24 @@ Removes a wallpaper of the specified type and restores the default one.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;result&nbsp;of&nbsp;removal&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { | callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned. |
if (error) {
console.error(`failed to reset because: ` + JSON.stringify(error)); **Example**
return;
} ```js
console.log(`success to reset.`); wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
}); if (error) {
``` console.error(`failed to reset because: ` + JSON.stringify(error));
return;
}
console.log(`success to reset.`);
});
```
## wallpaper.reset ## wallpaper.reset
...@@ -379,25 +390,27 @@ Removes a wallpaper of the specified type and restores the default one. ...@@ -379,25 +390,27 @@ Removes a wallpaper of the specified type and restores the default one.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;result&nbsp;of&nbsp;removal&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
- Example **Return value**
``` | Type | Description |
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { | -------- | -------- |
console.log(`success to reset.`); | Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the result of removal is returned. Otherwise, error information is returned. |
}).catch((error) => {
console.error(`failed to reset because: ` + JSON.stringify(error)); **Example**
});
``` ```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to reset.`);
}).catch((error) => {
console.error(`failed to reset because: ` + JSON.stringify(error));
});
```
## wallpaper.setWallpaper ## wallpaper.setWallpaper
...@@ -410,47 +423,48 @@ Sets a specified source as the wallpaper of a specified type. ...@@ -410,47 +423,48 @@ Sets a specified source as the wallpaper of a specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- | | Name | Type | Mandatory | Description |
| source | string&nbsp;\| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri&nbsp;path&nbsp;of&nbsp;the&nbsp;JPEG&nbsp;or&nbsp;PNG&nbsp;file,&nbsp;or&nbsp;bitmap&nbsp;of&nbsp;the&nbsp;PNG&nbsp;file. | | -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. | | source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;setting&nbsp;result&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned. |
- Example
**Example**
```
//The source type is string. ```js
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; // The source type is string.
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
if (error) { wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); if (error) {
return; console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
} return;
console.log(`success to setWallpaper.`); }
}); console.log(`success to setWallpaper.`);
});
//The source type is image.PixelMap.
import image from '@ohos.multimedia.image'; // The source type is image.PixelMap.
let imageSource = image.createImageSource("file://" + wallpaperPath); import image from '@ohos.multimedia.image';
let opts = { let imageSource = image.createImageSource("file://" + wallpaperPath);
"desiredSize": { let opts = {
"height": 3648, "desiredSize": {
"width": 2736 "height": 3648,
} "width": 2736
}; }
imageSource.createPixelMap(opts).then((pixelMap) => { };
wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { imageSource.createPixelMap(opts).then((pixelMap) => {
if (error) { wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); if (error) {
return; console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
} return;
console.log(`success to setWallpaper.`); }
}); console.log(`success to setWallpaper.`);
}).catch((error) => { });
console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); }).catch((error) => {
}); console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
``` });
```
## wallpaper.setWallpaper ## wallpaper.setWallpaper
...@@ -463,47 +477,49 @@ Sets a specified source as the wallpaper of a specified type. ...@@ -463,47 +477,49 @@ Sets a specified source as the wallpaper of a specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| source | string&nbsp;\|&nbsp;[PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri&nbsp;path&nbsp;of&nbsp;the&nbsp;JPEG&nbsp;or&nbsp;PNG&nbsp;file,&nbsp;or&nbsp;bitmap&nbsp;of&nbsp;the&nbsp;PNG&nbsp;file. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;setting&nbsp;result&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Example **Return value**
``` | Type | Description |
//The source type is string. | -------- | -------- |
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg"; | Promise&lt;void&gt; | Promise used to return the result. If the operation is successful, the setting result is returned. Otherwise, error information is returned. |
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to setWallpaper.`); **Example**
}).catch((error) => {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); ```js
}); // The source type is string.
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
//The source type is image.PixelMap. wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
import image from '@ohos.multimedia.image'; console.log(`success to setWallpaper.`);
let imageSource = image.createImageSource("file://" + wallpaperPath); }).catch((error) => {
let opts = { console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
"desiredSize": { });
"height": 3648,
"width": 2736 // The source type is image.PixelMap.
} import image from '@ohos.multimedia.image';
}; let imageSource = image.createImageSource("file://" + wallpaperPath);
imageSource.createPixelMap(opts).then((pixelMap) => { let opts = {
wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { "desiredSize": {
console.log(`success to setWallpaper.`); "height": 3648,
}).catch((error) => { "width": 2736
console.error(`failed to setWallpaper because: ` + JSON.stringify(error)); }
}); };
}).catch((error) => { imageSource.createPixelMap(opts).then((pixelMap) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error)); wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
}); console.log(`success to setWallpaper.`);
``` }).catch((error) => {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
});
}).catch((error) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
});
```
## wallpaper.getFile<sup>8+</sup> ## wallpaper.getFile<sup>8+</sup>
...@@ -511,27 +527,28 @@ getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): vo ...@@ -511,27 +527,28 @@ getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): vo
Obtains the wallpaper of the specified type. Obtains the wallpaper of the specified type.
**Required permissions**: ohos.permission.GET_WALLPAPER and ohos.permission.READ_USER_STORAGE **Required permissions**: ohos.permission.SET_WALLPAPER and ohos.permission.READ_USER_STORAGE
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;file&nbsp;descriptor&nbsp;ID&nbsp;to&nbsp;the&nbsp;wallpaper&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => { | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned. |
if (error) {
console.error(`failed to getFile because: ` + JSON.stringify(error)); **Example**
return;
} ```js
console.log(`success to getFile: ` + JSON.stringify(data)); wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
}); if (error) {
``` console.error(`failed to getFile because: ` + JSON.stringify(error));
return;
}
console.log(`success to getFile: ` + JSON.stringify(data));
});
```
## wallpaper.getFile<sup>8+</sup> ## wallpaper.getFile<sup>8+</sup>
...@@ -543,25 +560,27 @@ Obtains the wallpaper of the specified type. ...@@ -543,25 +560,27 @@ Obtains the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
- Return values | Name | Type | Mandatory | Description |
| Type | Description | | -------- | -------- | -------- | -------- |
| -------- | -------- | | wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| Promise&lt;number&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result.&nbsp;If&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful,&nbsp;the&nbsp;file&nbsp;descriptor&nbsp;ID&nbsp;to&nbsp;the&nbsp;wallpaper&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
- Example **Return value**
``` | Type | Description |
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => { | -------- | -------- |
console.log(`success to getFile: ` + JSON.stringify(data)); | Promise&lt;number&gt; | Promise used to return the result. If the operation is successful, the file descriptor ID to the wallpaper is returned. Otherwise, error information is returned. |
}).catch((error) => {
console.error(`failed to getFile because: ` + JSON.stringify(error)); **Example**
});
``` ```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getFile: ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to getFile because: ` + JSON.stringify(error));
});
```
## wallpaper.on('colorChange') ## wallpaper.on('colorChange')
...@@ -572,20 +591,21 @@ Subscribes to the wallpaper color change event. ...@@ -572,20 +591,21 @@ Subscribes to the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;subscribe&nbsp;to.&nbsp;The&nbsp;value&nbsp;**colorChange**&nbsp;indicates&nbsp;subscribing&nbsp;to&nbsp;the&nbsp;wallpaper&nbsp;color&nbsp;change&nbsp;event. |
| callback | function | Yes | Callback&nbsp;triggered&nbsp;when&nbsp;the&nbsp;wallpaper&nbsp;color&nbsp;changes.&nbsp;The&nbsp;wallpaper&nbsp;type&nbsp;and&nbsp;main&nbsp;colors&nbsp;are&nbsp;returned.<br/>-&nbsp;colors<br/>&nbsp;&nbsp;Main&nbsp;color&nbsp;information&nbsp;of&nbsp;the&nbsp;wallpaper.&nbsp;For&nbsp;details,&nbsp;see&nbsp;[RgbaColor](#rgbacolor).<br/>-&nbsp;wallpaperType<br/>&nbsp;&nbsp;Wallpaper&nbsp;type. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | type | string | Yes | Type of the event to subscribe to. The value **colorChange** indicates subscribing to the wallpaper color change event. |
let listener = (colors, wallpaperType) => { | callback | function | Yes | Callback triggered when the wallpaper color changes. The wallpaper type and main colors are returned.<br/>- colors<br/> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br/>- wallpaperType<br/> Wallpaper type. |
console.log(`wallpaper color changed.`);
}; **Example**
wallpaper.on('colorChange', listener);
``` ```js
let listener = (colors, wallpaperType) => {
console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
```
## wallpaper.off('colorChange') ## wallpaper.off('colorChange')
...@@ -596,24 +616,25 @@ Unsubscribes from the wallpaper color change event. ...@@ -596,24 +616,25 @@ Unsubscribes from the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper **System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters **Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type&nbsp;of&nbsp;the&nbsp;event&nbsp;to&nbsp;unsubscribe&nbsp;from.&nbsp;The&nbsp;value&nbsp;**colorChange**&nbsp;indicates&nbsp;unsubscribing&nbsp;from&nbsp;the&nbsp;wallpaper&nbsp;color&nbsp;change&nbsp;event. |
| callback | function | No | &nbsp;&nbsp;Callback&nbsp;for&nbsp;the&nbsp;wallpaper&nbsp;color&nbsp;change&nbsp;event.&nbsp;If&nbsp;this&nbsp;parameter&nbsp;is&nbsp;not&nbsp;specified,&nbsp;all&nbsp;callbacks&nbsp;corresponding&nbsp;to&nbsp;the&nbsp;wallpaper&nbsp;color&nbsp;change&nbsp;event&nbsp;are&nbsp;invoked.<br/>-&nbsp;colors<br/>&nbsp;&nbsp;Main&nbsp;color&nbsp;information&nbsp;of&nbsp;the&nbsp;wallpaper.&nbsp;For&nbsp;details,&nbsp;see&nbsp;[RgbaColor](#rgbacolor).<br/>-&nbsp;wallpaperType<br/>&nbsp;&nbsp;Wallpaper&nbsp;type. |
- Example | Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
``` | type | string | Yes | Type of the event to unsubscribe from. The value **colorChange** indicates unsubscribing from the wallpaper color change event. |
let listener = (colors, wallpaperType) => { | callback | function | No | Callback for the wallpaper color change event. If this parameter is not specified, all callbacks corresponding to the wallpaper color change event are invoked.<br/>- colors<br/> Main color information of the wallpaper. For details, see [RgbaColor](#rgbacolor).<br/>- wallpaperType<br/> Wallpaper type. |
console.log(`wallpaper color changed.`);
}; **Example**
wallpaper.on('colorChange', listener);
// Unsubscribe from the listener. ```js
wallpaper.off('colorChange', listener); let listener = (colors, wallpaperType) => {
//Unsubscribe from all subscriptions of the colorChange type. console.log(`wallpaper color changed.`);
wallpaper.off('colorChange'); };
``` wallpaper.on('colorChange', listener);
// Unsubscribe from the listener.
wallpaper.off('colorChange', listener);
//Unsubscribe from all subscriptions of the colorChange type.
wallpaper.off('colorChange');
```
## RgbaColor ## RgbaColor
...@@ -622,7 +643,7 @@ Unsubscribes from the wallpaper color change event. ...@@ -622,7 +643,7 @@ Unsubscribes from the wallpaper color change event.
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- | -------- |
| red | number | Yes | Yes | Red&nbsp;color.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. | | red | number | Yes | Yes | Red color. The value ranges from 0 to 255. |
| green | number | Yes | Yes | Green&nbsp;color.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. | | green | number | Yes | Yes | Green color. The value ranges from 0 to 255. |
| blue | number | Yes | Yes | Blue&nbsp;color.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. | | blue | number | Yes | Yes | Blue color. The value ranges from 0 to 255. |
| alpha | number | Yes | Yes | Alpha&nbsp;value.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. | | alpha | number | Yes | Yes | Alpha value. The value ranges from 0 to 255. |
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册