!14353 【输入法框架】【新增接口】新增需求相关接口描述

Merge pull request !14353 from 赵凌岚/master

zh-cn/application-dev/reference/apis/js-apis-inputmethod-InputMethodCommon.md

+# InputMethodCommon
+
+> **说明：**
+> 本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+
+输入法框架接口定义的公共属性信息。
+
+## Direction
+
+光标移动方向类型枚举。
+
+ **系统能力:**  SystemCapability.MiscServices.InputMethodFramework
+
+| 名称         | 值   | 说明       |
+| ------------ | ---- | ---------- |
+| CURSOR_UP    | 1    | 光标上移。 |
+| CURSOR_DOWN  | 2    | 光标下移。 |
+| CURSOR_LEFT  | 3    | 光标左移。 |
+| CURSOR_RIGHT | 4    | 光标右移。 |
+
+## Range
+
+描述选中文本的范围。
+
+ **系统能力:**  SystemCapability.MiscServices.InputMethodFramework
+
+| 名称  | 类型   | 可读 | 可写 | 说明                               |
+| ----- | ------ | ---- | ---- | ---------------------------------- |
+| start | number | 是   | 是   | 选中文本的首字符在编辑框的索引值。 |
+| end   | number | 是   | 是   | 选中文本的末字符在编辑框的索引值。 |
+
+## Movement
+
+描述进行选中文本动作时光标移动的方向。
+
+ **系统能力:** SystemCapability.MiscServices.InputMethodFramework
+
+| 名称      | 类型                    | 可读 | 可写 | 说明                               |
+| --------- | ----------------------- | ---- | ---- | ---------------------------------- |
+| direction | [Direction](#direction) | 是   | 是   | 进行选中文本动作时光标移动的方向。 |
+

zh-cn/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
+
+订阅输入法应用按范围选中文本事件。使用callback异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                                                         | 必填 | 说明                                                         |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type     | string                                                       | 是   | 设置监听类型。<br/>-type为‘selectByRange’时表示订阅输入法应用按范围选中文本事件监听。 |
+| callback | Callback&lt;[Range](./js-apis-inputmethod-InputMethodCommon.md#range)&gt; | 是   | 回调函数，返回需要选中的文本的范围。<br/>开发者需要在回调函数中根据传入的范围选中编辑框中相应文本。 |
+
+**示例：**
+
+```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
+
+取消订阅输入法应用按范围选中文本事件。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名 | 类型   | 必填 | 说明                                                         |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| type   | string | 是   | 设置监听类型。<br/>-type为‘selectByRange’时表示取消订阅输入法应用按范围选中文本事件监听。 |
+
+**示例：**
+
+```js
+inputMethodController.off('selectByRange');
+```
+
+### on('selectByMovement')<sup>10+</sup>
+
+on(type: 'selectByMovement', callback: Callback&lt;Range&gt;): void
+
+订阅输入法应用按光标动作选中文本事件。使用callback异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                                                         | 必填 | 说明                                                         |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type     | string                                                       | 是   | 设置监听类型。<br/>-type为‘selectByMovement’时表示订阅输入法应用按光标移动动作选中文本事件监听。 |
+| callback | Callback&lt;[Movement](./js-apis-inputmethod-InputMethodCommon.md#movement)&gt; | 是   | 回调函数，返回需要选中的文本的范围。<br/>开发者需要在回调函数中根据传入的光标动作选中编辑框中相应文本。 |
+
+**示例：**
+
+```js
+inputMethodController.on('selectByMovement', (movement) => {
+    console.info('Succeeded in subscribing selectByMovement: direction: ' + movement.direction);
+});
+```
+
+### off('selectByMovement')<sup>10+</sup>
+
+off(type: 'selectByMovement'): void
+
+取消订阅输入法应用按光标动作选中文本事件。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名 | 类型   | 必填 | 说明                                                         |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| type   | string | 是   | 设置监听类型。<br/>-type为‘selectByMovement’时表示取消订阅输入法应用按范围选中文本事件监听。 |
+
+**示例：**
+
+```js
+inputMethodController.off('selectByMovement');
+```
+
 ## InputMethodSetting<sup>8+</sup>
 
 下列API示例中都需使用[getSetting](#inputmethodgetsetting9)获取到InputMethodSetting实例，再通过此实例调用对应方法。

zh-cn/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
+
+根据索引范围选中文本。使用callback异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                                                      | 必填 | 说明                                                         |
+| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
+| range    | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | 是   | 选中文本的范围。                                             |
+| callback | AsyncCallback&lt;void&gt;                                 | 是   | 回调函数。当成功发送选中事件后，err为undefined，否则为错误对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                   |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**示例：**
+
+```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;
+
+根据索引范围选中文本。使用promise异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名 | 类型                                                      | 必填 | 说明             |
+| ------ | --------------------------------------------------------- | ---- | ---------------- |
+| range  | [Range](./js-apis-inputmethod-InputMethodCommon.md#range) | 是   | 选中文本的范围。 |
+
+**返回值：**
+
+| 类型                | 说明                      |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                   |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**示例：**
+
+```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
+
+根据光标移动方向选中文本。使用callback异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                                                         | 必填 | 说明                                                         |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | 是   | 选中时光标移动的方向。                                       |
+| callback | AsyncCallback&lt;void&gt;                                    | 是   | 回调函数。当成功发送选中事件后，err为undefined，否则为错误对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                   |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**示例：**
+
+```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;
+
+根据索引范围选中文本。使用promise异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                                                         | 必填 | 说明                   |
+| -------- | ------------------------------------------------------------ | ---- | ---------------------- |
+| movement | [Movement](./js-apis-inputmethod-InputMethodCommon.md#movement) | 是   | 选中时光标移动的方向。 |
+
+**返回值：**
+
+| 类型                | 说明                      |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                   |
+| -------- | -------------------------- |
+| 401      | parameter error.           |
+| 12800003 | Input method client error. |
+
+**示例：**
+
+```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
+
+获取光标所在处的文本索引。使用callback异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**参数：**
+
+| 参数名   | 类型                        | 必填 | 说明                                                         |
+| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
+| callback | AsyncCallback&lt;number&gt; | 是   | 回调函数。当文本索引获取成功，err为undefined，否则为错误对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                       |
+| -------- | ------------------------------ |
+| 401      | parameter error.               |
+| 12800003 | Input method client error.     |
+| 12800006 | Input method controller error. |
+
+**示例：**
+
+```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;
+
+获取光标所在处的文本索引。使用promise异步回调。
+
+**系统能力：** SystemCapability.MiscServices.InputMethodFramework
+
+**返回值：**
+
+| 类型                  | 说明                                    |
+| --------------------- | --------------------------------------- |
+| Promise&lt;number&gt; | Promise对象，返回光标所在处的文本索引。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
+
+| 错误码ID | 错误信息                       |
+| -------- | ------------------------------ |
+| 12800003 | Input method client error.     |
+| 12800006 | Input method controller error. |
+
+**示例：**
+
+```js
+inputClient.getTextIndexAtCursor().then((index) => {
+    console.info('Succeeded in getTextIndexAtCursor: ' + index);
+}).catch((err) => {
+    console.error('Failed to getTextIndexAtCursor: ${err.message}');
+});
+```
+
 ## EditorAttribute
 
 编辑框属性值。