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

update docs

Signed-off-by: Nester.zhou <ester.zhou@huawei.com>
上级 c7e07a2f
# Input Method Framework
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> 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.
> ![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.
>
## Modules to Import
......@@ -40,16 +40,18 @@ Obtains an [InputMethodController](#InputMethodController) instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type| Description|
| -------- | -------- |
| [InputMethodController](#InputMethodController) | Returns the current **InputMethodController** instance.|
| Type| Description|
| -------- | -------- |
| [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>
getInputMethodSetting(): InputMethodSetting
......@@ -58,17 +60,17 @@ Obtains an [InputMethodSetting](#InputMethodSetting) instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type | Description |
| ----------------------------------------- | ---------------------------- |
| [InputMethodSetting](#InputMethodSetting) | Returns the current **InputMethodSetting** instance.|
| Type | Description |
| ----------------------------------------- | ---------------------------- |
| [InputMethodSetting](#InputMethodSetting) | Returns the current **InputMethodSetting** instance.|
**Example**
- Example
```
var InputMethodSetting = inputMethod.getInputMethodSetting();
```
```js
var InputMethodSetting = inputMethod.getInputMethodSetting();
```
## InputMethodController<a name="InputMethodController"></a>
......@@ -82,15 +84,15 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return whether the keyboard is successfully hidden.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return whether the keyboard is successfully hidden.|
- Example
**Example**
```
```js
InputMethodController.stopInput((error)=>{
console.info('stopInput');
});
......@@ -104,16 +106,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return whether the keyboard is successfully hidden.|
| Type| Description|
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return whether the keyboard is successfully hidden.|
- Example
**Example**
```
```js
var isSuccess = InputMethodController.stopInput();
console.info('stopInput isSuccess = ' + isSuccess);
```
......@@ -130,20 +132,22 @@ Obtains the list of installed input methods. This API uses an asynchronous callb
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | Array<[InputMethodProperty](#InputMethodProperty)> | Yes | Callback used to return the list of installed input methods.|
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | Array<[InputMethodProperty](#InputMethodProperty)> | Yes | Callback used to return the list of installed input methods.|
**Example**
- Example
```
```js
InputMethodSetting.listInputMethod((properties)=>{
for (var i = 0;i < properties.length; i++) {
var property = properties[i];
console.info(property.packageName + "/" + property.methodId);
}
});
```
});
```
### listInputMethod
......@@ -153,19 +157,21 @@ Obtains the list of installed input methods. This API uses an asynchronous callb
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
| Type | Description |
| ----------------------------------------------------------- | ---------------------- |
| Promise<Array<[InputMethodProperty](#InputMethodProperty)>> | Promise used to return the list of installed input methods.|
**Return value**
| Type | Description |
| ----------------------------------------------------------- | ---------------------- |
| Promise<Array<[InputMethodProperty](#InputMethodProperty)>> | Promise used to return the list of installed input methods.|
- Example
```
**Example**
```js
var properties = InputMethodSetting.listInputMethod();
for (var i = 0;i < properties.length; i++) {
var property = properties[i];
console.info(property.packageName + "/" + property.methodId);
}
```
```
### displayOptionalInputMethod
......@@ -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.|
- Example
```
**Example**
```js
InputMethodSetting.displayOptionalInputMethod(()=>{
console.info('displayOptionalInputMethod is called');
});
```
```
### displayOptionalInputMethod
......@@ -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.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the execution result.|
- Example
```
**Example**
```js
InputMethodSetting.displayOptionalInputMethod();
```
```
\ No newline at end of file
# Input Method Engine
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> 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.
> ![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.
>
## Modules to Import
......@@ -52,17 +52,17 @@ Obtains an **InputMethodEngine** instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type | Description |
| --------------------------------------- | ------------ |
| [InputMethodEngine](#InputMethodEngine) | **InputMethodEngine** instance obtained.|
| Type | Description |
| --------------------------------------- | ------------ |
| [InputMethodEngine](#InputMethodEngine) | **InputMethodEngine** instance obtained.|
- Example
**Example**
```
var InputMethodEngine = inputMethodEngine.getInputMethodEngine();
```
```js
var InputMethodEngine = inputMethodEngine.getInputMethodEngine();
```
## inputMethodEngine.createKeyboardDelegate<a name="createKeyboardDelegate"></a>
......@@ -72,17 +72,17 @@ Obtains a **KeyboardDelegate** instance.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type | Description |
| ------------------------------------- | ---------------- |
| [KeyboardDelegate](#KeyboardDelegate) | **KeyboardDelegate** instance obtained.|
| Type | Description |
| ------------------------------------- | ---------------- |
| [KeyboardDelegate](#KeyboardDelegate) | **KeyboardDelegate** instance obtained.|
- Example
**Example**
```
var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate();
```
```js
var KeyboardDelegate = inputMethodEngine.createKeyboardDelegate();
```
## InputMethodEngine<a name="InputMethodEngine"></a>
......@@ -96,21 +96,21 @@ Listens for the input method binding event. This API uses a callback to return t
**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) | Yes| Callback used to return the result.|
- Example
**Example**
```
InputMethodEngine.on('inputStart', (kbController, textInputClient) => {
```js
InputMethodEngine.on('inputStart', (kbController, textInputClient) => {
KeyboardController = kbController;
TextInputClient = textInputClient;
});
```
});
```
### off('inputStart')
......@@ -120,20 +120,18 @@ Cancels listening for the input method binding event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- 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.|
**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.|
- Example
**Example**
```
InputMethodEngine.off('inputStart');
```
```js
InputMethodEngine.off('inputStart');
```
### on('keyboardShow'|'keyboardHide')
......@@ -143,20 +141,20 @@ Listens for an input method event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| 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.|
| callback | void | No | Callback used to return the result. |
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| 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. |
- Example
**Example**
```
InputMethodEngine.on('keyboardShow', (err) => {
```js
InputMethodEngine.on('keyboardShow', (err) => {
console.info('keyboardShow');
});
```
});
```
### off('keyboardShow'|'keyboardHide')
......@@ -166,19 +164,18 @@ Cancels listening for an input method event.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| 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.|
| callback | void | No | Callback used to return the result. |
- Example
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| 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. |
```
InputMethodEngine.off('keyboardShow');
```
**Example**
```js
InputMethodEngine.off('keyboardShow');
```
## 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
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- 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.|
**Parameters**
| 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**
```
KeyboardDelegate.on('keyDown', (event) => {
```js
KeyboardDelegate.on('keyDown', (event) => {
console.info('keyDown');
});
```
});
```
### off('keyDown'|'keyUp')
......@@ -217,18 +212,18 @@ Cancels listening for a hard keyboard even.
**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) | No | 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) | No | Callback used to return the key information. |
- Example
**Example**
```
KeyboardDelegate.off('keyDown');
```
```js
KeyboardDelegate.off('keyDown');
```
### on('cursorContextChange')
......@@ -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.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| 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. |
**System capability**: SystemCapability.Miscservices.InputMethodFramework
**Parameters**
| 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**
```
KeyboardDelegate.on('cursorContextChange', (x, y, height) => {
```js
KeyboardDelegate.on('cursorContextChange', (x, y, height) => {
console.info('cursorContextChange');
});
```
});
```
### off('cursorContextChange')
......@@ -263,19 +256,19 @@ Cancels listening for cursor context changes.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| 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.|
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| 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.|
**Example**
- Example
```js
KeyboardDelegate.off('cursorContextChange');
```
```
KeyboardDelegate.off('cursorContextChange');
```
### on('selectionChange')
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
**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 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| 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
**Example**
```
KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => {
```js
KeyboardDelegate.on('selectionChange', (oldBegin, oldEnd, newBegin, newEnd) => {
console.info('selectionChange');
});
```
});
```
### off('selectionChange')
......@@ -307,18 +300,18 @@ Cancels listening for text selection changes.
**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 | No| Callback used to return the text selection information.|
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| 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.|
- Example
**Example**
```
KeyboardDelegate.off('selectionChange');
```
```js
KeyboardDelegate.off('selectionChange');
```
### on('textChange')
......@@ -329,20 +322,20 @@ Listens for text changes. This API uses a callback to return the current text co
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
- Example
**Example**
```
KeyboardDelegate.on('textChange', (text) => {
```js
KeyboardDelegate.on('textChange', (text) => {
console.info('textChange');
});
```
});
```
### off('textChange')
......@@ -352,18 +345,18 @@ Cancels listening for text changes.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| 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.|
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| 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.|
- Example
**Example**
```
KeyboardDelegate.off('textChange');
```
```js
KeyboardDelegate.off('textChange');
```
## KeyboardController<a name="KeyboardController"></a>
......@@ -377,16 +370,16 @@ Hides the keyboard. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| callback | AsyncCallback&lt;void> | No | Callback used to return the result.|
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------- |
| callback | AsyncCallback&lt;void> | No | Callback used to return the result.|
- Example
**Example**
```
```js
KeyboardController.hideKeyboard(()=>{
});
```
......@@ -399,16 +392,16 @@ Hides the keyboard. This API uses a promise to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Return value
**Return value**
| Type | Description: |
| ---------------- | -------- |
| Promise&lt;void> | Promise used to return the result.|
| Type | Description: |
| ---------------- | -------- |
| Promise&lt;void> | Promise used to return the result.|
- Example
**Example**
```
```js
KeyboardController.hideKeyboard();
```
......@@ -424,19 +417,20 @@ Obtains the specific-length text before the cursor. This API uses an asynchronou
**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|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;string&gt; | Yes| Text returned.|
**Example**
- Example
```
```js
TextInputClient.getForward(5,(text) =>{
console.info("text = " + text);
});
```
```
### getForward
......@@ -446,22 +440,24 @@ Obtains the specific-length text before the cursor. This API uses a promise to r
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
**Example**
- Example
```
```js
var text = TextInputClient.getForward(5);
console.info("text = " + text);
```
```
### getBackward
......@@ -471,19 +467,20 @@ Obtains the specific-length text after the cursor. This API uses an asynchronous
**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|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;string&gt; | Yes| Text returned.|
**Example**
- Example
```
```js
TextInputClient.getBackward(5,(text)=>{
console.info("text = " + text);
});
```
});
```
### getBackward
......@@ -493,22 +490,24 @@ Obtains the specific-length text after the cursor. This API uses a promise to re
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;string&gt; | Text returned. |
**Example**
- Example
```
```js
var text = TextInputClient.getBackward(5);
console.info("text = " + text);
```
```
### deleteForward
......@@ -518,19 +517,21 @@ Deletes the fixed-length text before the cursor. This API uses an asynchronous c
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
**Example**
- Example
```
TextInputClient.deleteForward(5,(isSuccess)=>{
```js
TextInputClient.deleteForward(5,(isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
});
```
### deleteForward
deleteForward(length:number): Promise&lt;boolean&gt;
......@@ -539,22 +540,24 @@ Deletes the fixed-length text before the cursor. This API uses a promise to retu
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
**Return value**
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
- Example
```
**Example**
```js
var isSuccess = TextInputClient.deleteForward(5);
console.info("isSuccess = " + isSuccess);
```
```
### deleteBackward
......@@ -564,19 +567,20 @@ Deletes the fixed-length text after the cursor. This API uses an asynchronous ca
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
**Example**
- Example
```
```js
TextInputClient.deleteBackward(5, (isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
});
```
### deleteBackward
......@@ -586,22 +590,25 @@ Deletes the fixed-length text after the cursor. This API uses a promise to retur
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
**Parameters**
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| length | number | Yes| Text length.|
- Example
**Return value**
| 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(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
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
**Example**
- Example
```
```js
TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT,(isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
});
```
### sendKeyFunction
......@@ -632,22 +640,24 @@ Sets the Enter key to send the text to its target. This API uses a promise to re
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.|
**Parameters**
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| action | number | Yes| Edit box attribute.|
- Example
**Return value**
```
var isSuccess = TextInputClient.sendKeyFunction(inputMethod.ENTER_KEY_TYPE_NEXT);
console.info("isSuccess = " + isSuccess);
```
| 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);
```
### insertText
......@@ -657,19 +667,20 @@ Inserts text. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Returns whether the operation is successful.|
- Example
```
TextInputClient.insertText("test", (isSuccess)=>{
**Example**
```js
TextInputClient.insertText("test", (isSuccess)=>{
console.info("isSuccess = " + isSuccess);
});
```
});
```
### insertText
......@@ -679,22 +690,24 @@ Inserts text. This API uses a promise to return the result.
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
**Parameters**
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| text | string | Yes| Text to insert.|
- Example
**Return value**
```
var isSuccess = TextInputClient.insertText("test");
console.info("isSuccess = " + isSuccess);
```
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Returns whether the operation is successful. |
**Example**
```js
var isSuccess = TextInputClient.insertText("test");
console.info("isSuccess = " + isSuccess);
```
### getEditorAttribute
......@@ -704,16 +717,18 @@ Obtains the attribute of the edit box. This API uses an asynchronous callback to
**System capability**: SystemCapability.Miscservices.InputMethodFramework
- Parameters
| Name | Type | Mandatory | Description |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;[EditorAttribute](#EditorAttribute)&gt; | Yes| Attribute of the edit box. |
**Parameters**
| Name | Type | Mandatory | Description |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;[EditorAttribute](#EditorAttribute)&gt; | Yes| Attribute of the edit box. |
- Example
```
**Example**
```js
TextInputClient.getEditorAttribute((EditorAttribute)=>{
});
```
```
### getEditorAttribute
......@@ -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
- Return value
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;[EditorAttribute](#EditorAttribute)&gt; | Returns the attribute of the edit box. |
**Return value**
| Type | Description |
| ------------------------------- | ------------------------------------------------------------ |
| Promise&lt;[EditorAttribute](#EditorAttribute)&gt; | Returns the attribute of the edit box. |
- Example
```
var EditorAttribute = TextInputClient.getEditorAttribute();
```
**Example**
```js
var EditorAttribute = TextInputClient.getEditorAttribute();
```
## EditorAttribute<a name="EditorAttribute"></a>
......
# Pasteboard
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:**
> 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.
> ![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.
>
## Modules to Import
......@@ -19,11 +19,11 @@ import pasteboard from '@ohos.pasteboard';
| 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. |
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;HTML&nbsp;text. |
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;Want&nbsp;text. |
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;plain&nbsp;text. |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes | No | MIME&nbsp;type&nbsp;of&nbsp;the&nbsp;URI&nbsp;text. |
| 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 type of the HTML 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 type of the plain text. |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | Yes | No | MIME type of the URI text. |
## pasteboard.createPlainTextData
......@@ -34,21 +34,23 @@ Creates a **PasteData** object for plain text.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain&nbsp;text. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
- Example
**Return value**
```
var pasteData = pasteboard.createPlainTextData("content");
```
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
**Example**
```js
var pasteData = pasteboard.createPlainTextData("content");
```
## pasteboard.createHtmlData<sup>7+</sup>
......@@ -59,22 +61,24 @@ Creates a **PasteData** object for HTML text.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML&nbsp;text. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
- Example
**Return value**
```
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);
```
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
**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>
......@@ -85,25 +89,27 @@ Creates a **PasteData** object for Want text.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes | Want text. |
- Return values
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData** object with the specified content. |
```
var object = {
**Example**
```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
```
};
var pasteData = pasteboard.createWantData(object);
```
## pasteboard.createUriData<sup>7+</sup>
......@@ -114,21 +120,23 @@ Creates a **PasteData** object for URI text.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
- Return values
| Type | Description |
| -------- | -------- |
| [PasteData](#pastedata) | **PasteData**&nbsp;object&nbsp;with&nbsp;the&nbsp;specified&nbsp;content. |
**Return value**
- 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>
......@@ -139,21 +147,23 @@ Creates a **PasteDataRecord** object of the plain text type.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain&nbsp;text. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;plain&nbsp;text&nbsp;record. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
- Example
**Return value**
```
var record = pasteboard.createPlainTextRecord("hello");
```
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New plain text record. |
**Example**
```js
var record = pasteboard.createPlainTextRecord("hello");
```
## pasteboard.createHtmlTextRecord<sup>7+</sup>
......@@ -164,22 +174,24 @@ Creates a **PasteDataRecord** object of the HTML text type.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;HTML&nbsp;record. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New HTML record. |
```
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);
```
**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 record = pasteboard.createHtmlTextRecord(html);
```
## pasteboard.createWantRecord<sup>7+</sup>
......@@ -190,25 +202,27 @@ Creates a **PasteDataRecord** object of the Want text type.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-Want.md) | Yes | Want text. |
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;Want&nbsp;record. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New Want record. |
```
var object = {
**Example**
```js
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
var record = pasteboard.createWantRecord(object);
```
};
var record = pasteboard.createWantRecord(object);
```
## pasteboard.createUriRecord<sup>7+</sup>
......@@ -219,21 +233,23 @@ Creates a **PasteDataRecord** object of the URI text type.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New&nbsp;URI&nbsp;record. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | New URI record. |
```
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
```
**Example**
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
```
## PasteDataProperty<sup>7+</sup>
......@@ -244,11 +260,11 @@ Defines the properties of all data records on the pasteboard, including the time
| Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- |
| additions | {[key:&nbsp;string]:&nbsp;object} | Yes | Yes | Additional&nbsp;property&nbsp;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. |
| tag | string | Yes | Yes | User-defined&nbsp;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. |
| 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. |
| additions | {[key: string]: object} | Yes | Yes | Additional property data. |
| mimeTypes | Array&lt;string&gt; | Yes | No | Non-repeating data types of the data records on the pasteboard. |
| tag | string | Yes | Yes | User-defined tag. |
| timestamp | number | Yes | No | Timestamp at which the data is written to the pasteboard, in milliseconds. |
| 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>
......@@ -262,63 +278,65 @@ A data record is an abstract definition of the content on the pasteboard. The pa
| Name | Type | Readable | Writable | Description |
| -------- | -------- | -------- | -------- | -------- |
| htmlText<sup>7+</sup> | string | Yes | No | HTML&nbsp;text. |
| want<sup>7+</sup> | [Want](js-apis-featureAbility.md#want) | Yes | No | Want&nbsp;text. |
| mimeType<sup>7+</sup> | string | Yes | No | Data&nbsp;type. |
| plainText<sup>7+</sup> | string | Yes | No | Plain&nbsp;text. |
| uri<sup>7+</sup> | string | Yes | No | URI&nbsp;text. |
| htmlText<sup>7+</sup> | string | Yes | No | HTML text. |
| want<sup>7+</sup> | [Want](js-apis-featureAbility.md#want) | Yes | No | Want text. |
| mimeType<sup>7+</sup> | string | Yes | No | Data type. |
| plainText<sup>7+</sup> | string | Yes | No | Plain text. |
| uri<sup>7+</sup> | string | Yes | No | URI text. |
### convertToText<sup>7+</sup>
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
- Return values
| 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. |
**Return value**
| 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. |
- Example
**Example**
```
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText().then((data) => {
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText().then((data) => {
console.info('convertToText success data : ' + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error('convertToText failed because ' + JSON.stringify(error));
});
```
});
```
### convertToText<sup>7+</sup>
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
- Parameters
| 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| 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");
record.convertToText((err, data) => {
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText((err, data) => {
if (err) {
console.error('convertToText failed because ' + JSON.stringify(err));
return;
}
console.info('convertToText success data : ' + JSON.stringify(data));
});
```
});
```
## PasteData
......@@ -339,22 +357,19 @@ Obtains the plain text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
**Return value**
- Parameters
None
| Type | Description |
| -------- | -------- |
| string | Plain text. |
- Return values
| Type | Description |
| -------- | -------- |
| string | Plain&nbsp;text. |
**Example**
- Example
```
var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();
```
### getPrimaryHtml<sup>7+</sup>
......@@ -365,18 +380,19 @@ Obtains the HTML text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| string | HTML&nbsp;text. |
**Return value**
| Type | Description |
| -------- | -------- |
| string | HTML text. |
- Example
**Example**
```
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();
```
```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>
......@@ -387,21 +403,22 @@ Obtains the **Want** object of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| [Want](js-apis-featureAbility.md#want) | Want&nbsp;object. |
**Return value**
| Type | Description |
| -------- | -------- |
| [Want](js-apis-application-Want.md) | Want object. |
- Example
**Example**
```
var object = {
```js
var object = {
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>
......@@ -412,17 +429,18 @@ Obtains the URI text of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| string | URI&nbsp;text. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| string | URI text. |
```
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var uri = pasteData.getPrimaryUri();
```
**Example**
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var uri = pasteData.getPrimaryUri();
```
### addTextRecord<sup>7+</sup>
......@@ -435,17 +453,18 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| text | string | Yes | Plain text. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");
```
### addHtmlRecord<sup>7+</sup>
......@@ -458,18 +477,19 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| htmlText | string | Yes | HTML text. |
- Example
**Example**
```
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>";
pasteData.addHtmlRecord(html);
```
```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>";
pasteData.addHtmlRecord(html);
```
### addWantRecord<sup>7+</sup>
......@@ -482,21 +502,22 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want&nbsp;object. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#want) | Yes | Want object. |
```
var pasteData = pasteboard.createPlainTextData("hello");
var object = {
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var object = {
bundleName: "com.example.aafwk.test",
abilityName: "com.example.aafwk.test.TwoAbility"
};
pasteData.addWantRecord(object);
```
};
pasteData.addWantRecord(object);
```
### addUriRecord<sup>7+</sup>
......@@ -509,17 +530,18 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI&nbsp;text. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri | string | Yes | URI text. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt");
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt");
```
### addRecord<sup>7+</sup>
......@@ -532,21 +554,22 @@ The pasteboard supports a maximum number of 128 data records.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | Record&nbsp;to&nbsp;add. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | Record to add. |
- Example
**Example**
```
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var textRecord = pasteboard.createPlainTextRecord("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 htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);
```
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var textRecord = pasteboard.createPlainTextRecord("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 htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);
```
### getMimeTypes<sup>7+</sup>
......@@ -557,17 +580,18 @@ Obtains **mimeTypes** in [PasteDataProperty](#pastedataproperty7) from this past
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| Array&lt;string&gt; | List&nbsp;of&nbsp;non-duplicate&nbsp;MIME&nbsp;types. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| Array&lt;string&gt; | List of non-duplicate MIME types. |
```
var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();
```
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();
```
### getPrimaryMimeType<sup>7+</sup>
......@@ -578,17 +602,18 @@ Obtains the data type of the primary record.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| string | Data&nbsp;type&nbsp;of&nbsp;the&nbsp;primary&nbsp;record. |
**Return value**
- 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>
......@@ -599,17 +624,18 @@ Obtains the property description object.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataProperty](#pastedataproperty7) | Property&nbsp;description&nbsp;object. |
**Return value**
| Type | Description |
| -------- | -------- |
| [PasteDataProperty](#pastedataproperty7) | Property description object. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();
```
### getRecordAt<sup>7+</sup>
......@@ -620,22 +646,24 @@ Obtains the record with the specified index.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Index&nbsp;of&nbsp;the&nbsp;specified&nbsp;record. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | Record&nbsp;with&nbsp;the&nbsp;specified&nbsp;index. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Index of the specified record. |
- Example
**Return value**
```
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);
```
| Type | Description |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | Record with the specified index. |
**Example**
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);
```
### getRecordCount<sup>7+</sup>
......@@ -646,17 +674,18 @@ Obtains the number of data records in this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| number | Number&nbsp;of&nbsp;records. |
**Return value**
- 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>
......@@ -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
- Return values
| 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. |
**Return value**
| Type | Description |
| -------- | -------- |
| string | User-defined tag content if obtained and null if no tag is set. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
### hasMimeType<sup>7+</sup>
......@@ -688,22 +718,24 @@ Checks whether the content of this pasteboard contains the specified data type.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| mimeType | string | Yes | Type&nbsp;of&nbsp;the&nbsp;data&nbsp;to&nbsp;query. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| mimeType | string | Yes | Type of the data to query. |
**Return value**
- Return values
| Type | Description |
| -------- | -------- |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;specified&nbsp;data&nbsp;type&nbsp;exists;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
| Type | Description |
| -------- | -------- |
| boolean | Returns **true** if the specified data type exists; returns **false** otherwise. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
```
### removeRecordAt<sup>7+</sup>
......@@ -714,22 +746,24 @@ Removes the data record with a specified index from this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified&nbsp;index. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified index. |
**Return value**
- Return values
| Type | Description |
| -------- | -------- |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
| Type | Description |
| -------- | -------- |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
### replaceRecordAt<sup>7+</sup>
......@@ -740,24 +774,26 @@ Replaces the data record with a specified index in this pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified&nbsp;index. |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | New&nbsp;record. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| index | number | Yes | Specified index. |
| record | [PasteDataRecord](#pastedatarecord7) | Yes | New record. |
**Return value**
- Return values
| Type | Description |
| -------- | -------- |
| boolean | Returns&nbsp;**true**&nbsp;if&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful;&nbsp;returns&nbsp;**false**&nbsp;otherwise. |
| Type | Description |
| -------- | -------- |
| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```
```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```
## pasteboard.getSystemPasteboard
......@@ -768,21 +804,22 @@ Obtains the system pasteboard.
**System capability**: SystemCapability.MiscServices.Pasteboard
- Return values
| Type | Description |
| -------- | -------- |
| [SystemPasteboard](#systempasteboard) | System&nbsp;pasteboard. |
**Return value**
| Type | Description |
| -------- | -------- |
| [SystemPasteboard](#systempasteboard) | System pasteboard. |
- Example
**Example**
```
var systemPasteboard = pasteboard.getSystemPasteboard();
```
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
```
## 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();
......@@ -793,112 +830,117 @@ var systemPasteboard = pasteboard.getSystemPasteboard();
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
- Parameters
| 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| 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");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (error, data) => {
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (error, data) => {
if (error) {
console.error('Failed to setPasteData. Cause: ' + error.message);
return;
}
console.info('setPasteData successfully.');
});
```
});
```
### setPasteData
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
- Parameters
| Name | Type | Description |
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | **PasteData**&nbsp;object. |
**Parameters**
| Name | Type | Description |
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | **PasteData** object. |
**Return value**
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;data&nbsp;write&nbsp;result. |
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the data write result. |
- Example
**Example**
```
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
console.info('setPasteData success.');
}).catch((error) => {
}).catch((error) => {
console.error('Failed to setPasteData. Cause: ' + error.message);
});
```
});
```
### getPasteData
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
- Parameters
| 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | Yes | Callback used to return the system pasteboard data. |
- Example
**Example**
```
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((error, pasteData) => {
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((error, pasteData) => {
if (error) {
console.error('Failed to getPasteData. Cause: ' + error.message);
return;
}
var text = pasteData.getPrimaryText();
});
```
});
```
### getPasteData
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
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;system&nbsp;pasteboard&nbsp;data. |
**Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise used to return the system pasteboard data. |
- Example
**Example**
```
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => {
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => {
var text = pasteData.getPrimaryText();
}).catch((error) => {
}).catch((error) => {
console.error('Failed to getPasteData. Cause: ' + error.message);
})
```
})
```
### on('update')<sup>7+</sup>
......@@ -909,21 +951,22 @@ Subscribes to the content change event of the system pasteboard. If the pasteboa
**System capability**: SystemCapability.MiscServices.Pasteboard
- 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Data type. The value **update** indicates the pasteboard content has changed. |
| callback | function | Yes | Callback invoked when the pasteboard content changes. |
- Example
**Example**
```
var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = ()=>{
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = ()=>{
console.info('The system pasteboard has changed');
};
systemPasteboard.on('update', listener);
```
};
systemPasteboard.on('update', listener);
```
### off('update')<sup>7+</sup>
......@@ -934,114 +977,119 @@ Unsubscribes from the system pasteboard content change event.
**System capability**: SystemCapability.MiscServices.Pasteboard
- 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 | No | Callback&nbsp;invoked&nbsp;when&nbsp;the&nbsp;pasteboard&nbsp;content&nbsp;changes. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| 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**
```
systemPasteboard.off('update', listener);
```
```js
systemPasteboard.off('update', listener);
```
### hasPasteData<sup>7+</sup>
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
- Parameters
| 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
- Example
**Example**
```
systemPasteboard.hasPasteData((err, data) => {
```js
systemPasteboard.hasPasteData((err, data) => {
if (err) {
console.error('failed to hasPasteData because ' + JSON.stringify(err));
return;
}
console.info('success hasPasteData : ' + JSON.stringify(data));
});
```
});
```
### hasPasteData<sup>7+</sup>
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
- Return values
| 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. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Returns **true** if the pasteboard contains content; returns **false** otherwise. |
```
systemPasteboard.hasPasteData().then((data) => {
**Example**
```js
systemPasteboard.hasPasteData().then((data) => {
console.info('Operation succeeded. ' + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error('failed to hasPasteData because ' + JSON.stringify(error));
});
```
});
```
### clear<sup>7+</sup>
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
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
- Example
**Example**
```
systemPasteboard.clear((err, data) => {
```js
systemPasteboard.clear((err, data) => {
if (err) {
console.error('failed to clear because ' + JSON.stringify(err));
return;
}
console.info('success clear');
});
```
});
```
### clear<sup>7+</sup>
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
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Return value**
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. |
- Example
**Example**
```
systemPasteboard.clear().then((data) => {
```js
systemPasteboard.clear().then((data) => {
console.info('success clear');
}).catch((error) => {
}).catch((error) => {
console.error('failed to clear because ' + JSON.stringify(error));
});
```
});
```
\ No newline at end of file
# Upload and Download
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:**
> 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.
> ![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.
>
## Modules to Import
......@@ -37,56 +37,58 @@ import request from '@ohos.request';
| 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_WIFI | number | Yes | No | Whether&nbsp;download&nbsp;is&nbsp;allowed&nbsp;when&nbsp;the&nbsp;WLAN&nbsp;is&nbsp;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_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_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_ERROR<sup>7+</sup> | number | Yes | No | File&nbsp;operation&nbsp;failure. |
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP&nbsp;transmission&nbsp;failure. |
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes | No | Insufficient&nbsp;storage&nbsp;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_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes | No | Unidentified&nbsp;HTTP&nbsp;code. |
| ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown&nbsp;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_UNKNOWN<sup>7+</sup> | number | Yes | No | Download&nbsp;paused&nbsp;due&nbsp;to&nbsp;unknown&nbsp;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_TO_RETRY<sup>7+</sup> | number | Yes | No | Download&nbsp;paused&nbsp;and&nbsp;then&nbsp;retried. |
| SESSION_FAILED<sup>7+</sup> | number | Yes | No | Download&nbsp;failure&nbsp;without&nbsp;retry. |
| SESSION_PAUSED<sup>7+</sup> | number | Yes | No | Download&nbsp;paused. |
| SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download&nbsp;pending. |
| SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download&nbsp;in&nbsp;progress. |
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful&nbsp;download. |
| NETWORK_MOBILE | number | Yes | No | Whether download is allowed when the cellular network is 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 to resume the download due to an error. |
| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes | No | Failure to find a storage device such as an SD card. |
| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | Yes | No | Failure to download the file because it already exists. |
| ERROR_FILE_ERROR<sup>7+</sup> | number | Yes | No | File operation failure. |
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP transmission failure. |
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes | No | Insufficient storage space. |
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | Yes | No | Error caused by too many network redirections. |
| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes | No | Unidentified HTTP code. |
| ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown error. |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes | No | Download paused and queuing for WLAN connection, because the file size exceeds the maximum value allowed by a cellular network session. |
| PAUSED_UNKNOWN<sup>7+</sup> | number | Yes | No | Download paused due to unknown reasons. |
| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | Yes | No | Download paused due to a network connection problem, for example, network disconnection. |
| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | Yes | No | Download paused and then retried. |
| SESSION_FAILED<sup>7+</sup> | number | Yes | No | Download failure without retry. |
| SESSION_PAUSED<sup>7+</sup> | number | Yes | No | Download paused. |
| SESSION_PENDING<sup>7+</sup> | number | Yes | No | Download pending. |
| SESSION_RUNNING<sup>7+</sup> | number | Yes | No | Download in progress. |
| SESSION_SUCCESSFUL<sup>7+</sup> | number | Yes | No | Successful download. |
## request.upload
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
**System capability**: SystemCapability.MiscServices.Upload
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;upload. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;[UploadTask](#uploadtask)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;**UploadTask**&nbsp;object. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
- Example
**Return value**
```
request.upload({ url: 'https://patch' }).then((data) => {
| Type | Description |
| -------- | -------- |
| Promise&lt;[UploadTask](#uploadtask)&gt; | Promise used to return the **UploadTask** object. |
**Example**
```js
request.upload({ url: 'https://patch' }).then((data) => {
uploadTask = data;
}).catch((err) => {
}).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.
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
**System capability**: SystemCapability.MiscServices.Upload
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
| callback | AsyncCallback&lt;[UploadTask](#uploadtask)&gt; | No | Callback used to return the **UploadTask** object. |
```
request.upload({ url: 'https://patch' }, (err, data) => {
**Example**
```js
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
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
**System capability**: SystemCapability.MiscServices.Upload
- 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**
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 |
| -------- | -------- | -------- | -------- |
| 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. |
Parameters of the callback function
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
| totalSize | number | Yes | Total size of the files to upload, in KB. |
```
uploadTask.on('progress', function callback(uploadedSize, totalSize) {
**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
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
**System capability**: SystemCapability.MiscServices.Upload
- 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**
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 |
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP&nbsp;Response&nbsp;Header. |
Parameters of the callback function
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP Response Header. |
```
uploadTask.on('headerReceive', function callback(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
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
**System capability**: SystemCapability.MiscServices.Upload
- 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**
| 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. |
Parameters of the callback function
Parameters of the callback function
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| 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. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
| totalSize | number | Yes | Total size of the files to upload, in KB. |
- Example
**Example**
```
uploadTask.off('progress', function callback(uploadedSize, totalSize) {
```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
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
**System capability**: SystemCapability.MiscServices.Upload
- 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**
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 |
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP&nbsp;Response&nbsp;Header. |
Parameters of the callback function
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| header | object | Yes | HTTP Response Header. |
```
uploadTask.off('headerReceive', function callback(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
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
**System capability**: SystemCapability.MiscServices.Upload
- Return values
| 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. |
**Return value**
- 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) => {
**Example**
```js
uploadTask.remove().then((result) => {
if (result) {
console.info('Upload task removed successfully. ');
} else {
console.error('Failed to remove the upload task. ');
}
}).catch((err) => {
}).catch((err) => {
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});
});
```
......@@ -288,21 +296,22 @@ Removes this upload task. This method uses a promise to return the result.
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
**System capability**: SystemCapability.MiscServices.Upload
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. |
- Example
**Example**
```
uploadTask.remove((err, result) => {
```js
uploadTask.remove((err, result) => {
if (err) {
console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
return;
......@@ -312,7 +321,7 @@ Removes this upload task. This method uses an asynchronous callback to return th
} 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
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource&nbsp;URL. |
| header | object | No | HTTP&nbsp;or&nbsp;HTTPS&nbsp;header&nbsp;added&nbsp;to&nbsp;an&nbsp;upload&nbsp;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**. |
| 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**. |
| data | Array&lt;[RequestData](#requestdata)&gt; | No | Form&nbsp;data&nbsp;in&nbsp;the&nbsp;request&nbsp;body. |
| url | string | Yes | Resource URL. |
| header | object | No | HTTP or HTTPS header added to an upload request. |
| method | string | No | Request methods available: **POST** and **PUT**. The default value is **POST**. |
| files | Array&lt;[File](#file)&gt; | Yes | List of files to upload, which is submitted through **multipart/form-data**. |
| data | Array&lt;[RequestData](#requestdata)&gt; | No | Form data in the request body. |
## File
......@@ -335,10 +344,10 @@ Removes this upload task. This method uses an asynchronous callback to return th
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| filename | string | No | File&nbsp;name&nbsp;in&nbsp;the&nbsp;header&nbsp;when&nbsp;**multipart**&nbsp;is&nbsp;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**. |
| 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 |
| 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. |
| filename | string | No | File name in the header when **multipart** is used. |
| name | string | No | Name of a form item when **multipart** is used. The default value is **file**. |
| uri | string | Yes | Local path for storing files.<br/>The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. 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 of the file content. By default, the type is obtained based on the extension of the file name or URI. |
## RequestData
......@@ -347,68 +356,71 @@ Removes this upload task. This method uses an asynchronous callback to return th
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| name | string | Yes | Name&nbsp;of&nbsp;a&nbsp;form&nbsp;element. |
| value | string | Yes | Value&nbsp;of&nbsp;a&nbsp;form&nbsp;element. |
| name | string | Yes | Name of a form element. |
| value | string | Yes | Value of a form element. |
## request.download
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
**System capability**: SystemCapability.MiscServices.Download
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations&nbsp;of&nbsp;the&nbsp;download. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
- Example
**Return value**
```
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadTask](#downloadtask)&gt; | Promise used to return the result. |
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
downloadTask = data;
}).catch((err) => {
}).catch((err) => {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})
```
})
```
## request.download
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
| callback | AsyncCallback&lt;[DownloadTask](#downloadtask)&gt; | No | Callback used to return the result. |
```
request.download({ url: 'https://xxxx/xxxxx.hap',
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
**Example**
```js
request.download({ url: 'https://xxxx/xxxxx.hap',
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
if (err) {
console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
return;
}
downloadTask = data;
});
});
```
......@@ -421,28 +433,29 @@ Implements file downloads.
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
**System capability**: SystemCapability.MiscServices.Download
- 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;(download&nbsp;progress). |
| callback | function | Yes | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;progress&nbsp;event. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **progress** (download progress). |
| callback | function | Yes | Callback for the download progress event. |
Parameters of the callback function
Parameters of the callback function
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| 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. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. |
| totalSize | number | Yes | Total size of the files to download, in KB. |
- Example
**Example**
```
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) {
console.error('Failed to request download. Cause:' + err);
......@@ -461,29 +474,30 @@ Subscribes to the download progress event. This method uses an asynchronous call
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
**System capability**: SystemCapability.MiscServices.Download
- 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**
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 |
| -------- | -------- | -------- | -------- |
| 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. |
Parameters of the callback function
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| receivedSize | number | Yes | Size of the downloaded files, in KB. |
| totalSize | number | Yes | Total size of the files to download, in KB. |
```
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) {
console.error('Failed to request download. Cause:' + err);
return;
......@@ -492,8 +506,8 @@ Unsubscribes from the download progress event. This method uses an asynchronous
downloadTask .off('progress', function download_callback(receivedSize, totalSize) {
console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);
});
);
});
```
......@@ -501,22 +515,23 @@ Unsubscribes from the download progress event. This method uses an asynchronous
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
- 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. |
| callback | function | Yes | Callback used to return the result. |
```
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) {
console.error('Failed to request download. Cause:' + err);
return;
......@@ -525,8 +540,8 @@ Subscribes to a download event. This method uses an asynchronous callback to ret
downloadTask.on('complete', function callback() {
console.info('Download task completed.');
}
);
});
);
});
```
......@@ -534,22 +549,23 @@ Subscribes to a download event. This method uses an asynchronous callback to ret
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
- 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. |
| callback | function | No | Callback used to return the result. |
```
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) {
console.error('Failed to request download. Cause:' + JSON.stringify(err));
return;
......@@ -558,8 +574,8 @@ Unsubscribes from the download event. This method uses an asynchronous callback
downloadTask.off('complete', function callback() {
console.info('Download task completed.');
}
);
});
);
});
```
......@@ -567,28 +583,29 @@ Unsubscribes from the download event. This method uses an asynchronous callback
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
**System capability**: SystemCapability.MiscServices.Download
- 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**
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 |
| -------- | -------- | -------- | -------- |
| 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). |
Parameters of the callback function
- 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)=> {
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (err) {
console.error('Failed to request download. Cause:' + err);
return;
......@@ -597,8 +614,8 @@ Subscribes to the download task failure event. This method uses an asynchronous
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
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
**System capability**: SystemCapability.MiscServices.Download
- 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;**fail**&nbsp;(download&nbsp;failure). |
| callback | function | No | Callback&nbsp;for&nbsp;the&nbsp;download&nbsp;task&nbsp;failure&nbsp;event. |
**Parameters**
Parameters of the callback function
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **fail** (download failure). |
| callback | function | No | Callback for the download task failure event. |
| 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). |
Parameters of the callback function
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). |
```
**Example**
```js
request.download({ url: 'https://xxxx/xxxx.hap' }, (err, data)=> {
if (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
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
**System capability**: SystemCapability.MiscServices.Download
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;task&nbsp;removal&nbsp;result. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;boolean&gt; | Promise used to return the task removal result. |
```
**Example**
```js
downloadTask.remove().then((result) => {
if (result) {
console.info('Download task removed.');
......@@ -675,21 +694,22 @@ Removes this download task. This method uses a promise to return the result.
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the task removal result. |
- Example
**Example**
```
downloadTask.remove((err, result)=>{
```js
downloadTask.remove((err, result)=>{
if(err) {
console.error('Failed to remove the download task.');
return;
......@@ -699,7 +719,7 @@ Removes this download task. This method uses an asynchronous callback to return
} 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
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
**System capability**: SystemCapability.MiscServices.Download
- Parameters
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;download&nbsp;task&nbsp;information. |
**Parameters**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;[DownloadInfo](#downloadinfo7)&gt; | Promise used to return the download task information. |
```
downloadTask.query().then((downloadInfo) => {
**Example**
```js
downloadTask.query().then((downloadInfo) => {
console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
}) .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.
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[DownloadInfo](#downloadinfo7)&gt; | Yes | Callback used to return the download task information. |
- Example
**Example**
```
downloadTask.query((err, downloadInfo)=>{
```js
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
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
**System capability**: SystemCapability.MiscServices.Download
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;string&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;**MimeType**&nbsp;of&nbsp;the&nbsp;download&nbsp;task. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return **MimeType** of the download task. |
```
downloadTask.queryMimeType().then((data) => {
**Example**
```js
downloadTask.queryMimeType().then((data) => {
console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
}).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
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
**System capability**: SystemCapability.MiscServices.Download
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return **MimeType** of the download task. |
```
downloadTask.queryMimeType((err, data)=>{
**Example**
```js
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
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
**System capability**: SystemCapability.MiscServices.Download
- Return values
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;download&nbsp;task&nbsp;pause&nbsp;result. |
**Return value**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the download task pause result. |
```
downloadTask.pause().then((result) => {
**Example**
```js
downloadTask.pause().then((result) => {
if (result) {
console.info('Download task paused. ');
} else {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
}
}).catch((err) => {
}).catch((err) => {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});
});
```
......@@ -845,21 +870,22 @@ Pauses this download task. This method uses a promise to return the result.
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
**System capability**: SystemCapability.MiscServices.Download
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
```
downloadTask.pause((err, result)=>{
**Example**
```js
downloadTask.pause((err, result)=>{
if(err) {
console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
return;
......@@ -869,7 +895,7 @@ Pauses this download task. This method uses an asynchronous callback to return t
} 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
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
**System capability**: SystemCapability.MiscServices.Download
- Parameters
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Parameters**
- Example
| Type | Description |
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result. |
```
downloadTask.resume().then((result) => {
**Example**
```js
downloadTask.resume().then((result) => {
if (result) {
console.info('Download task resumed.')
} else {
console.error('Failed to resume the download task. ');
}
console.info('Download task resumed.')
}).catch((err) => {
}).catch((err) => {
console.error('Failed to resume the download task. Cause:' + err);
});
});
```
......@@ -908,21 +935,22 @@ Resumes this download task. This method uses a promise to return the result.
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
**System capability**: SystemCapability.MiscServices.Download
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback&nbsp;used&nbsp;to&nbsp;return&nbsp;the&nbsp;result. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
```
downloadTask.resume((err, result)=>{
**Example**
```js
downloadTask.resume((err, result)=>{
if (err) {
console.error('Failed to resume the download task. Cause:' + err);
return;
......@@ -932,7 +960,7 @@ Resumes this download task. This method uses an asynchronous callback to return
} 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
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource&nbsp;URL. |
| header | object | No | HTTP&nbsp;or&nbsp;HTTPS&nbsp;header&nbsp;added&nbsp;to&nbsp;a&nbsp;download&nbsp;request. |
| enableMetered | boolean | No | Download&nbsp;allowed&nbsp;in&nbsp;metered&nbsp;connections. |
| enableRoaming | boolean | No | Download&nbsp;allowed&nbsp;on&nbsp;a&nbsp;roaming&nbsp;network. |
| description | string | No | Description&nbsp;of&nbsp;the&nbsp;download&nbsp;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. |
| networkType | number | No | Network&nbsp;type&nbsp;allowed&nbsp;for&nbsp;download. |
| title | string | No | Title&nbsp;of&nbsp;the&nbsp;download&nbsp;session. |
| url | string | Yes | Resource URL. |
| header | object | No | HTTP or HTTPS header added to a download request. |
| enableMetered | boolean | No | Download allowed in metered connections. |
| enableRoaming | boolean | No | Download allowed on a roaming network. |
| description | string | No | Description of the download session. |
| filePath<sup>7+</sup> | string | No | Download path. (The default path is [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 type allowed for download. |
| title | string | No | Title of the download session. |
## DownloadInfo<sup>7+</sup>
......@@ -958,14 +986,14 @@ Resumes this download task. This method uses an asynchronous callback to return
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| downloadId | number | Yes | ID&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. |
| failedReason | number | No | Download&nbsp;failure&nbsp;cause,&nbsp;which&nbsp;can&nbsp;be&nbsp;any&nbsp;constant&nbsp;of&nbsp;[ERROR_*](#constants). |
| fileName | string | Yes | Name&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. |
| filePath | string | Yes | URI&nbsp;of&nbsp;the&nbsp;saved&nbsp;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). |
| status | number | Yes | Download&nbsp;status&nbsp;code,&nbsp;which&nbsp;can&nbsp;be&nbsp;any&nbsp;constant&nbsp;of&nbsp;[SESSION_*](#constants). |
| targetURI | string | Yes | URI&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. |
| downloadTitle | string | Yes | Title&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file. |
| downloadTotalBytes | number | Yes | Total&nbsp;size&nbsp;of&nbsp;the&nbsp;downloaded&nbsp;file&nbsp;(int&nbsp;bytes). |
| description | string | Yes | Description&nbsp;of&nbsp;the&nbsp;file&nbsp;to&nbsp;download. |
| downloadedBytes | number | Yes | Size&nbsp;of&nbsp;the&nbsp;files&nbsp;downloaded&nbsp;(int&nbsp;bytes). |
| downloadId | number | Yes | ID of the downloaded file. |
| failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). |
| fileName | string | Yes | Name of the downloaded file. |
| filePath | string | Yes | URI of the saved file. |
| pausedReason | number | No | Reason for session pause, which can be any constant of [PAUSED_*](#constants). |
| status | number | Yes | Download status code, which can be any constant of [SESSION_*](#constants). |
| targetURI | string | Yes | URI of the downloaded file. |
| downloadTitle | string | Yes | Title of the downloaded file. |
| downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). |
| description | string | Yes | Description of the file to download. |
| downloadedBytes | number | Yes | Size of the files downloaded (int bytes). |
# Setting the System Time
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> 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.
> ![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.
>
## Modules to Import
......@@ -22,16 +22,17 @@ Sets the system time. This API uses an asynchronous callback to return the resul
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- Example
| 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.|
```
// Set the system time to 2021-01-20 02:36:25.
**Example**
```js
// Set the system time to 2021-01-20 02:36:25.
var time = 1611081385000;
systemTime.setTime(time, (error, data) => {
if (error) {
......@@ -53,26 +54,28 @@ Sets the system time. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
- **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
- Example
**Return value**
```
// Set the system time to 2021-01-20 02:36:25.
var time = 1611081385000;
systemTime.setTime(time).then((data) => {
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```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) => {
}).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
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- 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) => {
if (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
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
| 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.|
- Example
**Return value**
```
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getCurrentTime().then((data) => {
console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data));
}).catch((error) => {
......@@ -140,15 +146,16 @@ Obtains the time elapsed since system start, excluding the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- 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) => {
if (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
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
| 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.|
- Example
**Return value**
```
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getCurrentTime().then((data) => {
console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data));
}).catch((error) => {
......@@ -196,15 +205,16 @@ Obtains the time elapsed since system start, including the deep sleep time. This
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- 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) => {
if (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
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
| 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.|
- Example
**Return value**
```
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|
**Example**
```js
systemTime.getRealTime().then((data) => {
console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data));
}).catch((error) => {
......@@ -254,15 +266,16 @@ Sets the system date. This API uses an asynchronous callback to return the resul
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- 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");
systemTime.setDate(data,(error, data) => {
if (error) {
......@@ -284,19 +297,21 @@ Sets the system date. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
- **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
- 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");
systemTime.setDate(data).then((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
**System capability**: SystemCapability.MiscServices.Time
- **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Date&gt; | Yes| Callback used to return the current system date.|
**Parameters**
- 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) => {
if (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.
**System capability**: SystemCapability.MiscServices.Time
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;Date&gt; | Promise used to return the current system date.|
**Return value**
- Example
| Type| Description|
| -------- | -------- |
| Promise&lt;Date&gt; | Promise used to return the current system date.|
```
**Example**
```js
systemTime.getDate().then((data) => {
console.log(`systemTime.getDate success data : ` + JSON.stringify(data));
}).catch((error) => {
......@@ -366,15 +383,16 @@ Sets the system time zone. This API uses an asynchronous callback to return the
**System capability**: SystemCapability.MiscServices.Time
- **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.|
**Parameters**
- 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) => {
if (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.
**System capability**: SystemCapability.MiscServices.Time
- **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
**Parameters**
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
- Example
**Return value**
```
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
systemTime.setTimezone('Asia/Shanghai').then((data) => {
console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data));
}).catch((error) => {
......@@ -424,14 +444,15 @@ Obtains the system time zone. This API uses an asynchronous callback to return t
**System capability**: SystemCapability.MiscServices.Time
- **Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the system time zone.|
**Parameters**
- 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) => {
if (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.
**System capability**: SystemCapability.MiscServices.Time
- Return value
| Type| Description|
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return the system time zone.|
**Return value**
- Example
| Type| Description|
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return the system time zone.|
```
**Example**
```js
systemTime.getTimezone().then((data) => {
console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data));
}).catch((error) => {
......
# Wallpaper
> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:**
> 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.
> ![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.
>
## Modules to Import
......@@ -21,8 +21,8 @@ Defines the wallpaper type.
| Name | Description |
| -------- | -------- |
| WALLPAPER_LOCKSCREEN | Lock&nbsp;screen&nbsp;wallpaper. |
| WALLPAPER_SYSTEM | Home&nbsp;screen&nbsp;wallpaper. |
| WALLPAPER_LOCKSCREEN | Lock screen wallpaper. |
| WALLPAPER_SYSTEM | Home screen wallpaper. |
## wallpaper.getColors
......@@ -36,12 +36,12 @@ Obtains the main color information of the wallpaper of a specified type.
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;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. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| callback | AsyncCallback&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Yes | Callback used to return the main color information of the wallpaper. |
- Example
```
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (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.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| 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. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Example
**Return value**
```
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
| Type | Description |
| -------- | -------- |
| Promise&lt;Array&lt;[RgbaColor](#rgbacolor)&gt;&gt; | Promise used to return the main color information of the wallpaper. |
**Example**
```js
wallpaper.getColors(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getColors.`);
}).catch((error) => {
}).catch((error) => {
console.error(`failed to getColors because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.getId
......@@ -89,23 +91,24 @@ Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| 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. |
```
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
**Example**
```js
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
......@@ -116,26 +119,27 @@ Obtains the ID of the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Parameters**
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Return values
| 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. |
**Return value**
- 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) => {
**Example**
```js
wallpaper.getId(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getId: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to getId because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.getMinHeight
......@@ -146,22 +150,23 @@ Obtains the minimum height of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- 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) => {
**Example**
```js
wallpaper.getMinHeight((error, data) => {
if (error) {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinHeight: ` + JSON.stringify(data));
});
```
});
```
## wallpaper.getMinHeight
......@@ -172,21 +177,21 @@ Obtains the minimum height of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper
**Return value**
- Return values
| Type | Description |
| -------- | -------- |
| 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. |
| 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. |
- Example
**Example**
```
wallpaper.getMinHeight().then((data) => {
```js
wallpaper.getMinHeight().then((data) => {
console.log(`success to getMinHeight: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to getMinHeight because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.getMinWidth
......@@ -197,23 +202,23 @@ Obtains the minimum width of the 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;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. |
| 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. |
- Example
**Example**
```
wallpaper.getMinWidth((error, data) => {
```js
wallpaper.getMinWidth((error, data) => {
if (error) {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
return;
}
console.log(`success to getMinWidth: ` + JSON.stringify(data));
});
```
});
```
## wallpaper.getMinWidth
......@@ -224,20 +229,21 @@ Obtains the minimum width of the wallpaper.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Return values
| 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. |
**Return value**
- 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) => {
**Example**
```js
wallpaper.getMinWidth().then((data) => {
console.log(`success to getMinWidth: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to getMinWidth because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.isChangePermitted
......@@ -248,22 +254,23 @@ Checks whether to allow the application to change the wallpaper for the current
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- 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) => {
**Example**
```js
wallpaper.isChangePermitted((error, data) => {
if (error) {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
return;
}
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
});
```
});
```
## wallpaper.isChangePermitted
......@@ -274,20 +281,21 @@ Checks whether to allow the application to change the wallpaper for the current
**System capability**: SystemCapability.MiscServices.Wallpaper
- Return values
| 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. |
**Return value**
- 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) => {
**Example**
```js
wallpaper.isChangePermitted().then((data) => {
console.log(`success to isChangePermitted: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to isChangePermitted because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.isOperationAllowed
......@@ -298,22 +306,23 @@ Checks whether the user is allowed to set wallpapers.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- 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) => {
**Example**
```js
wallpaper.isOperationAllowed((error, data) => {
if (error) {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
return;
}
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
});
```
});
```
## wallpaper.isOperationAllowed
......@@ -324,20 +333,21 @@ Checks whether the user is allowed to set wallpapers.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Return values
| 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. |
**Return value**
- 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) => {
**Example**
```js
wallpaper.isOperationAllowed().then((data) => {
console.log(`success to isOperationAllowed: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to isOperationAllowed because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.reset
......@@ -350,23 +360,24 @@ Removes a wallpaper of the specified type and restores the default one.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| 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. |
```
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
**Example**
```js
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
......@@ -379,25 +390,27 @@ Removes a wallpaper of the specified type and restores the default one.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
**Parameters**
- Return values
| 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;result&nbsp;of&nbsp;removal&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Example
**Return value**
```
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
| Type | Description |
| -------- | -------- |
| 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. |
**Example**
```js
wallpaper.reset(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to reset.`);
}).catch((error) => {
}).catch((error) => {
console.error(`failed to reset because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.setWallpaper
......@@ -410,36 +423,37 @@ Sets a specified source as the wallpaper of a specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters
| 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. |
| 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| 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. |
```
//The source type is string.
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
**Example**
```js
// The source type is string.
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
return;
}
console.log(`success to setWallpaper.`);
});
});
//The source type is image.PixelMap.
import image from '@ohos.multimedia.image';
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts = {
// The source type is image.PixelMap.
import image from '@ohos.multimedia.image';
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts = {
"desiredSize": {
"height": 3648,
"width": 2736
}
};
imageSource.createPixelMap(opts).then((pixelMap) => {
};
imageSource.createPixelMap(opts).then((pixelMap) => {
wallpaper.setWallpaper(pixelMap, wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
if (error) {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
......@@ -447,10 +461,10 @@ Sets a specified source as the wallpaper of a specified type.
}
console.log(`success to setWallpaper.`);
});
}).catch((error) => {
}).catch((error) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.setWallpaper
......@@ -463,47 +477,49 @@ Sets a specified source as the wallpaper of a specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- Return values
| 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;setting&nbsp;result&nbsp;is&nbsp;returned.&nbsp;Otherwise,&nbsp;error&nbsp;information&nbsp;is&nbsp;returned. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| source | string \| [PixelMap](js-apis-image.md#pixelmap7) | Yes | Uri path of the JPEG or PNG file, or bitmap of the PNG file. |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Example
**Return value**
```
//The source type is string.
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
| Type | Description |
| -------- | -------- |
| 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. |
**Example**
```js
// The source type is string.
let wallpaperPath = "/data/data/ohos.acts.aafwk.plrdtest.form/files/Cup_ic.jpg";
wallpaper.setWallpaper(wallpaperPath, wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to setWallpaper.`);
}).catch((error) => {
}).catch((error) => {
console.error(`failed to setWallpaper because: ` + JSON.stringify(error));
});
});
//The source type is image.PixelMap.
import image from '@ohos.multimedia.image';
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts = {
// The source type is image.PixelMap.
import image from '@ohos.multimedia.image';
let imageSource = image.createImageSource("file://" + wallpaperPath);
let opts = {
"desiredSize": {
"height": 3648,
"width": 2736
}
};
imageSource.createPixelMap(opts).then((pixelMap) => {
};
imageSource.createPixelMap(opts).then((pixelMap) => {
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) => {
}).catch((error) => {
console.error(`failed to createPixelMap because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.getFile<sup>8+</sup>
......@@ -511,27 +527,28 @@ getFile(wallpaperType: WallpaperType, callback: AsyncCallback&lt;number&gt;): vo
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
- 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. |
**Parameters**
- Example
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
| 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. |
```
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM, (error, data) => {
**Example**
```js
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>
......@@ -543,25 +560,27 @@ Obtains the wallpaper of the specified type.
**System capability**: SystemCapability.MiscServices.Wallpaper
- Parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper&nbsp;type. |
**Parameters**
- Return values
| Type | Description |
| -------- | -------- |
| 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. |
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| wallpaperType | [WallpaperType](#wallpapertype) | Yes | Wallpaper type. |
- Example
**Return value**
```
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
| Type | Description |
| -------- | -------- |
| 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. |
**Example**
```js
wallpaper.getFile(wallpaper.WallpaperType.WALLPAPER_SYSTEM).then((data) => {
console.log(`success to getFile: ` + JSON.stringify(data));
}).catch((error) => {
}).catch((error) => {
console.error(`failed to getFile because: ` + JSON.stringify(error));
});
```
});
```
## wallpaper.on('colorChange')
......@@ -572,20 +591,21 @@ Subscribes to the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- 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. |
| 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. |
```
let listener = (colors, wallpaperType) => {
**Example**
```js
let listener = (colors, wallpaperType) => {
console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
```
};
wallpaper.on('colorChange', listener);
```
## wallpaper.off('colorChange')
......@@ -596,24 +616,25 @@ Unsubscribes from the wallpaper color change event.
**System capability**: SystemCapability.MiscServices.Wallpaper
- 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. |
**Parameters**
- 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. |
| 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. |
```
let listener = (colors, wallpaperType) => {
**Example**
```js
let listener = (colors, wallpaperType) => {
console.log(`wallpaper color changed.`);
};
wallpaper.on('colorChange', listener);
// Unsubscribe from the listener.
wallpaper.off('colorChange', listener);
//Unsubscribe from all subscriptions of the colorChange type.
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
......@@ -622,7 +643,7 @@ Unsubscribes from the wallpaper color change event.
| 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. |
| green | number | Yes | Yes | Green&nbsp;color.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. |
| blue | number | Yes | Yes | Blue&nbsp;color.&nbsp;The&nbsp;value&nbsp;ranges&nbsp;from&nbsp;0&nbsp;to&nbsp;255. |
| alpha | number | Yes | Yes | Alpha&nbsp;value.&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 color. The value ranges from 0 to 255. |
| blue | number | Yes | Yes | Blue color. The value ranges from 0 to 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.
先完成此消息的编辑!
想要评论请 注册