!15144 翻译完成 14353：【输入法框架】【新增接口】新增需求相关接口描述

Merge pull request !15144 from ester.zhou/TR-14353

en/application-dev/reference/apis/js-apis-inputmethod-InputMethodCommon.md

+# InputMethodCommon
+
+> **NOTE**
+>
+> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+
+The **InputMethodCommon** module provides the common attributes defined by the input method framework.
+
+## Direction
+
+Enumerates the directions of cursor movement.
+
+ **System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+| Name        | Value  | Description      |
+| ------------ | ---- | ---------- |
+| CURSOR_UP    | 1    | The cursor moves upward.|
+| CURSOR_DOWN  | 2    | The cursor moves downward.|
+| CURSOR_LEFT  | 3    | The caret moves leftward.|
+| CURSOR_RIGHT | 4    | The caret moves rightward.|
+
+## Range
+
+Describes the range of the selected text.
+
+ **System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+| Name | Type  | Readable| Writable| Description                              |
+| ----- | ------ | ---- | ---- | ---------------------------------- |
+| start | number | Yes  | Yes  | Index of the first selected character in the text box.|
+| end   | number | Yes  | Yes  | Index of the last selected character in the text box.|
+
+## Movement
+
+Describes the direction in which the cursor moves when the text is selected.
+
+ **System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+| Name     | Type                   | Readable| Writable| Description                              |
+| --------- | ----------------------- | ---- | ---- | ---------------------------------- |
+| direction | [Direction](#direction) | Yes  | Yes  | Direction in which the cursor moves when the text is selected.|

en/application-dev/reference/apis/js-apis-inputmethod.md

@@ -839,6 +839,92 @@ inputMethodController.stopInput().then((result) => {
 })
 ```
 
+### on('selectByRange')<sup>10+</sup>
+
+on(type: 'selectByRange', callback: Callback&lt;Range&gt;): void
+
+Enables listening for the selection-by-range event. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                                                        | Mandatory| Description                                                        |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type     | string                                                       | Yes  | Listening type.<br>The value **selectByRange** indicates the selection-by-range event.|
+| callback | Callback&lt;[Range](./js-apis-inputmethod-InputMethodCommon.md#range)&gt; | Yes  | Callback used to return the range of the text to be selected.<br>Your application needs to select the text in the returned range in the text box.|
+
+**Example**
+
+```js
+inputMethodController.on('selectByRange', (range) => {
+    console.info('Succeeded in subscribing selectByRange: start: ' + range.start + " , end: " + range.end);
+});
+```
+
+### off('selectByRange')<sup>10+</sup>
+
+off(type: 'selectByRange'): void
+
+Disables listening for the selection-by-range event.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name| Type  | Mandatory| Description                                                        |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| type   | string | Yes  | Listening type.<br>The value **selectByRange** indicates the selection-by-range event.|
+
+**Example**
+
+```js
+inputMethodController.off('selectByRange');
+```
+
+### on('selectByMovement')<sup>10+</sup>
+
+on(type: 'selectByMovement', callback: Callback&lt;Range&gt;): void
+
+Enables listening for the selection-by-cursor-movement event. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                                                        | Mandatory| Description                                                        |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type     | string                                                       | Yes  | Listening type.<br>The value **selectByMovement** indicates the selection-by-cursor-movement event.|
+| callback | Callback&lt;[Movement](./js-apis-inputmethod-InputMethodCommon.md#movement)&gt; | Yes  | Callback used to return the range of the text to be selected.<br>Your application needs to select the text in the returned range in the text box.|
+
+**Example**
+
+```js
+inputMethodController.on('selectByMovement', (movement) => {
+    console.info('Succeeded in subscribing selectByMovement: direction: ' + movement.direction);
+});
+```
+
+### off('selectByMovement')<sup>10+</sup>
+
+off(type: 'selectByMovement'): void
+
+Disables listening for the selection-by-cursor-movement event.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name| Type  | Mandatory| Description                                                        |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| type   | string | Yes  | Listening type.<br>The value **selectByMovement** indicates the selection-by-cursor-movement event.|
+
+**Example**
+
+```js
+inputMethodController.off('selectByMovement');
+```
+
 ## InputMethodSetting<sup>8+</sup>
 
 In the following API examples, you must first use [getSetting](#inputmethodgetsetting9) to obtain an **InputMethodSetting** instance, and then call the APIs using the obtained instance.

en/application-dev/reference/apis/js-apis-inputmethodengine.md

@@ -1495,6 +1495,241 @@ try {
 }
 ```
 
+### selectByRange<sup>10+</sup>
+
+selectByRange(range: Range, callback: AsyncCallback&lt;void&gt;): void
+
+Selects text based on the specified range. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                                                     | Mandatory| Description                                                        |
+| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
+| range    | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | Yes  | Range of the selected text.                                            |
+| callback | AsyncCallback&lt;void&gt;                                 | Yes  | Callback used to return the result. If the selection event is sent, **err** is **undefined**; otherwise, **err** is an error object.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                  |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**Example**
+
+```js
+try {
+    inputClient.selectByRange({start: 0, end: 1}, (err) => {
+        if (err !== undefined) {
+            console.error('Failed to selectByRange: ${err.message}');
+            return;
+        }
+        console.info('Succeeded in selecting by range.');
+    });
+} catch (err) {
+    console.error('Failed to selectByRange: ${err.message}');
+}
+```
+
+### selectByRange<sup>10+</sup>
+
+selectByRange(range: Range): Promise&lt;void&gt;
+
+Selects text based on the specified range. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name| Type                                                     | Mandatory| Description            |
+| ------ | --------------------------------------------------------- | ---- | ---------------- |
+| range  | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | Yes  | Range of the selected text.|
+
+**Return value**
+
+| Type               | Description                     |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                  |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**Example**
+
+```js
+try {
+    inputClient.selectByRange({start: 0, end:1}).then(() => {
+        console.log('Succeeded in selecting by range.');
+    }).catch((err) => {
+        console.error('Failed to selectByRange: ${err.message}');
+    });
+} catch (err) {
+    console.log('Failed to selectByRange: ${err.message}');
+}
+```
+
+### selectByMovement<sup>10+</sup>
+
+selectByMovement(movement: Movement, callback: AsyncCallback&lt;void&gt;): void
+
+Selects text based on the cursor movement direction. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                                                        | Mandatory| Description                                                        |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | Yes  | Direction in which the cursor moves when the text is selected.                                      |
+| callback | AsyncCallback&lt;void&gt;                                    | Yes  | Callback used to return the result. If the selection event is sent, **err** is **undefined**; otherwise, **err** is an error object.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                  |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**Example**
+
+```js
+try {
+    inputClient.selectByMovement({direction: 1}, (err) => {
+        if (err !== undefined) {
+            console.error('Failed to selectByMovement: ${err.message}');
+            return;
+        }
+        console.info('Succeeded in selecting by movement.');
+    });
+} catch (err) {
+    console.error('Failed to selectByMovement: ${err.message}');
+}
+```
+
+### selectByMovement<sup>10+</sup>
+
+selectByMovement(range: Range): Promise&lt;void&gt;
+
+Selects text based on the specified range. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                                                        | Mandatory| Description                  |
+| -------- | ------------------------------------------------------------ | ---- | ---------------------- |
+| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | Yes  | Direction in which the cursor moves when the text is selected.|
+
+**Return value**
+
+| Type               | Description                     |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                  |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**Example**
+
+```js
+try {
+    inputClient.selectByMovement({direction: 1}).then(() => {
+        console.log('Succeeded in selecting by movement.');
+    }).catch((err) => {
+        console.error('Failed to selectByMovement: ${err.message}');
+    });
+} catch (err) {
+    console.log('Failed to selectByMovement: ${err.message}');
+}
+```
+
+### getTextIndexAtCursor<sup>10+</sup>
+
+getTextIndexAtCursor(callback: AsyncCallback&lt;number&gt;): void
+
+Obtains the index of the text where the cursor is located. This API uses an asynchronous callback to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Parameters**
+
+| Name  | Type                       | Mandatory| Description                                                        |
+| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
+| callback | AsyncCallback&lt;number&gt; | Yes  | Callback used to return the result. If the text index is obtained, **err** is **undefined**; otherwise, **err** is an error object.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                      |
+| -------- | ------------------------------ |
+| 401      | parameter error.               |
+| 12800003 | Input method client error.     |
+| 12800006 | Input method controller error. |
+
+**Example**
+
+```js
+inputClient.getTextIndexAtCursor((err, index) => {
+    if (err !== undefined) {
+        console.error('Failed to getTextIndexAtCursor: ${err.message}');
+        return;
+    }
+    console.info('Succeeded in getTextIndexAtCursor: ' + index);
+});
+```
+
+### getTextIndexAtCursor<sup>10+</sup>
+
+getTextIndexAtCursor(): Promise&lt;number&gt;
+
+Obtains the index of the text where the cursor is located. This API uses a promise to return the result.
+
+**System capability**: SystemCapability.MiscServices.InputMethodFramework
+
+**Return value**
+
+| Type                 | Description                                   |
+| --------------------- | --------------------------------------- |
+| Promise&lt;number&gt; | Promise used to return the result.|
+
+**Error codes**
+
+For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md).
+
+| Error Code ID| Error Message                      |
+| -------- | ------------------------------ |
+| 12800003 | Input method client error.     |
+| 12800006 | Input method controller error. |
+
+**Example**
+
+```js
+inputClient.getTextIndexAtCursor().then((index) => {
+    console.info('Succeeded in getTextIndexAtCursor: ' + index);
+}).catch((err) => {
+    console.error('Failed to getTextIndexAtCursor: ${err.message}');
+});
+```
+
 ## EditorAttribute
 
 Attribute of the edit box.