# @ohos.inputMethod (输入法框架)
本模块主要面向普通前台应用(备忘录、信息、设置等系统应用与三方应用),提供对输入法(输入法应用)的控制、管理能力,包括显示/隐藏输入法软键盘、切换输入法、获取所有输入法列表等等。
> **说明:**
>
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
## 导入模块
```ts
import inputMethod from '@ohos.inputMethod';
```
## 常量8+
常量值。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 参数名 | 类型 | 常量值 | 说明 |
| -------- | -------- | -------- | -------- |
| MAX_TYPE_NUM | number | 128 | 可支持的最大输入法个数。 |
## InputMethodProperty8+
输入法应用属性。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| name9+ | string | 是 | 否 | 必填。输入法内部名称。|
| id9+ | string | 是 | 否 | 必填。输入法唯一标识。|
| label9+ | string | 是 | 否 | 非必填。输入法对外显示名称。|
| labelId10+ | string | 是 | 否 | 非必填。输入法对外显示名称资源号。|
| icon9+ | string | 是 | 否 | 非必填。输入法图标数据,可以通过iconId查询获取。预留字段,暂不支持使用。|
| iconId9+ | number | 是 | 否 | 非必填。输入法图标资源号。 |
| extra9+ | object | 是 | 是 | 输入法扩展信息。预留字段,当前无具体含义,暂不支持使用。
- API version 10起:非必填;
- API version 9:必填。|
| packageName(deprecated) | string | 是 | 否 | 输入法包名。必填。
说明:从API version 8开始支持,从API version 9开始废弃,建议使用name替代。 |
| methodId(deprecated) | string | 是 | 否 | 输入法唯一标识。必填。
说明:从API version 8开始支持,从API version 9开始废弃,建议使用id替代。 |
## inputMethod.getController9+
getController(): InputMethodController
获取客户端实例[InputMethodController](#inputmethodcontroller)。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------- | ------------------------ |
| [InputMethodController](#inputmethodcontroller) | 回调返回当前客户端实例。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | ------------------------------ |
| 12800006 | input method controller error. |
**示例:**
```ts
let inputMethodController = inputMethod.getController();
```
## inputMethod.getSetting9+
getSetting(): InputMethodSetting
获取客户端设置实例[InputMethodSetting](#inputmethodsetting8)。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ---------------------------- |
| [InputMethodSetting](#inputmethodsetting8) | 回调返回当前客户端设置实例。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800007 | settings extension error. |
**示例:**
```ts
let inputMethodSetting = inputMethod.getSetting();
```
## inputMethod.switchInputMethod9+
switchInputMethod(target: InputMethodProperty, callback: AsyncCallback<boolean>): void
切换输入法,仅系统应用可用。使用callback异步回调。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| target | [InputMethodProperty](#inputmethodproperty8) | 是 | 目标输入法。 |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当输入法切换成功,err为undefined,data为true;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let currentIme = inputMethod.getCurrentInputMethod();
try{
inputMethod.switchInputMethod(currentIme, (err: Error, result: boolean) => {
if (err) {
console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
return;
}
if (result) {
console.log('Succeeded in switching inputmethod.');
} else {
console.error('Failed to switchInputMethod.');
}
});
} catch(err) {
console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
}
```
## inputMethod.switchInputMethod9+
switchInputMethod(target: InputMethodProperty): Promise<boolean>
切换输入法,仅系统应用可用。使用promise异步回调。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|target | [InputMethodProperty](#inputmethodproperty8)| 是 | 目标输入法。 |
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ---------------------------- |
| Promise\ | Promise对象。返回true表示切换输入法成功,返回false表示切换输入法失败。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let currentIme = inputMethod.getCurrentInputMethod();
try {
inputMethod.switchInputMethod(currentIme).then((result: boolean) => {
if (result) {
console.log('Succeeded in switching inputmethod.');
} else {
console.error('Failed to switchInputMethod.');
}
}).catch((err: Error) => {
console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
})
} catch (err) {
console.error(`Failed to switchInputMethod: ${JSON.stringify(err)}`);
}
```
## inputMethod.getCurrentInputMethod9+
getCurrentInputMethod(): InputMethodProperty
使用同步方法获取当前输入法。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------------------------------------------- | ------------------------ |
| [InputMethodProperty](#inputmethodproperty8) | 返回当前输入法属性对象。 |
**示例:**
```ts
let currentIme = inputMethod.getCurrentInputMethod();
```
## inputMethod.switchCurrentInputMethodSubtype9+
switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback\): void
切换当前输入法的子类型。使用callback异步回调。
> **说明:**
>
> 在API version 9版本,仅支持系统应用调用;API version 10版本起,支持系统应用和当前输入法应用调用。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| 是 | 目标输入法子类型。 |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当输入法子类型切换成功,err为undefined,data为true;否则为错误对象。|
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
let extra: Record = {}
inputMethod.switchCurrentInputMethodSubtype({
id: "ServiceExtAbility",
label: "",
name: "com.example.kikakeyboard",
mode: "upper",
locale: "",
language: "",
icon: "",
iconId: 0,
extra: extra
}, (err: Error, result: boolean) => {
if (err) {
console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
return;
}
if (result) {
console.log('Succeeded in switching currentInputMethodSubtype.');
} else {
console.error('Failed to switchCurrentInputMethodSubtype');
}
});
} catch(err) {
console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
## inputMethod.switchCurrentInputMethodSubtype9+
switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise<boolean>
切换当前输入法的子类型。使用promise异步回调。
> **说明:**
>
> 在API version 9版本,仅支持系统应用调用;API version 10版本起,支持系统应用和当前输入法应用调用。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|target | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| 是 | 目标输入法子类型。 |
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ---------------------------- |
| Promise\ | Promise对象。返回true表示当前输入法切换子类型成功,返回false表示当前输入法切换子类型成功失败。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
let extra: Record = {}
inputMethod.switchCurrentInputMethodSubtype({
id: "ServiceExtAbility",
label: "",
name: "com.example.kikakeyboard",
mode: "upper",
locale: "",
language: "",
icon: "",
iconId: 0,
extra: extra
}).then((result: boolean) => {
if (result) {
console.log('Succeeded in switching currentInputMethodSubtype.');
} else {
console.error('Failed to switchCurrentInputMethodSubtype.');
}
}).catch((err: Error) => {
console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to switchCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
## inputMethod.getCurrentInputMethodSubtype9+
getCurrentInputMethodSubtype(): InputMethodSubtype
获取当前输入法的子类型。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------------------------------------------- | ------------------------ |
| [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype) | 返回当前输入法子类型对象。 |
**示例:**
```ts
let currentImeSubType = inputMethod.getCurrentInputMethodSubtype();
```
## inputMethod.switchCurrentInputMethodAndSubtype9+
switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback\): void
切换至指定输入法的指定子类型,适用于跨输入法切换子类型,仅系统应用可用。使用callback异步回调。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| 是 | 目标输入法。 |
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| 是 | 目标输入法子类型。 |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当输入法和子类型切换成功,err为undefined,data为获取到的切换子类型结果true;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let currentIme = inputMethod.getCurrentInputMethod();
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType, (err: Error, result: boolean) => {
if (err) {
console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
return;
}
if (result) {
console.log('Succeeded in switching currentInputMethodAndSubtype.');
} else {
console.error('Failed to switchCurrentInputMethodAndSubtype.');
}
});
} catch (err) {
console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
}
```
## inputMethod.switchCurrentInputMethodAndSubtype9+
switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean>
切换至指定输入法的指定子类型,适用于跨输入法切换子类型,仅系统应用可用。使用promise异步回调。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
|inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| 是 | 目标输入法。 |
|inputMethodSubtype | [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)| 是 | 目标输入法子类型。 |
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ---------------------------- |
| Promise\ | Promise对象。返回true表示切换至指定输入法的指定子类型成功,返回false表示切换至指定输入法的指定子类型失败。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800005 | configuration persisting error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let currentIme = inputMethod.getCurrentInputMethod();
let imSubType = inputMethod.getCurrentInputMethodSubtype();
try {
inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType).then((result: boolean) => {
if (result) {
console.log('Succeeded in switching currentInputMethodAndSubtype.');
} else {
console.error('Failed to switchCurrentInputMethodAndSubtype.');
}
}).catch((err: Error) => {
console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to switchCurrentInputMethodAndSubtype: ${JSON.stringify(err)}`);
}
```
## inputMethod.getInputMethodController(deprecated)
getInputMethodController(): InputMethodController
获取客户端实例[InputMethodController](#inputmethodcontroller)。
> **说明:**
>
> 从API version 6开始支持,从API version 9开始废弃,建议使用[getController()](#inputmethodgetcontroller9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------- | ------------------------ |
| [InputMethodController](#inputmethodcontroller) | 回调返回当前客户端实例。 |
**示例:**
```ts
let inputMethodController = inputMethod.getInputMethodController();
```
## inputMethod.getInputMethodSetting(deprecated)
getInputMethodSetting(): InputMethodSetting
获取客户端设置实例[InputMethodSetting](#inputmethodsetting8)。
> **说明:**
>
> 从API version 6开始支持,从API version 9开始废弃,建议使用[getSetting()](#inputmethodgetsetting9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ---------------------------- |
| [InputMethodSetting](#inputmethodsetting8) | 回调返回当前客户端设置实例。 |
**示例:**
```ts
let inputMethodSetting = inputMethod.getInputMethodSetting();
```
## TextInputType10+
文本输入类型。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 值 |说明 |
| -------- | -------- |-------- |
| NONE | -1 |NONE。 |
| TEXT | 0 |文本类型。 |
| MULTILINE | 1 |多行类型。 |
| NUMBER | 2 |数字类型。 |
| PHONE | 3 |电话号码类型。 |
| DATETIME | 4 |日期类型。 |
| EMAIL_ADDRESS | 5 |邮箱地址类型。 |
| URL | 6 |链接类型。 |
| VISIBLE_PASSWORD | 7 |密码类型。 |
## EnterKeyType10+
Enter键的功能类型。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 值 |说明 |
| -------- | -------- |-------- |
| UNSPECIFIED | 0 |未指定。 |
| NONE | 1 |NONE。 |
| GO | 2 |前往。 |
| SEARCH | 3 |查找。 |
| SEND | 4 |发送。 |
| NEXT | 5 |下一步。 |
| DONE | 6 |完成。 |
| PREVIOUS | 7 |上一步。 |
## KeyboardStatus10+
输入法软键盘状态。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 值 |说明 |
| -------- | -------- |-------- |
| NONE | 0 |NONE。 |
| HIDE | 1 |隐藏状态。 |
| SHOW | 2 |显示状态。 |
## Direction10+
光标移动方向。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 值 |说明 |
| -------- | -------- |-------- |
| CURSOR_UP | 1 |向上。 |
| CURSOR_DOWN | 2 |向下。 |
| CURSOR_LEFT | 3 |向左。 |
| CURSOR_RIGHT | 4 |向右。 |
## ExtendAction10+
编辑框中文本的扩展编辑操作类型,如剪切、复制等。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 值 |说明 |
| -------- | -------- |-------- |
| SELECT_ALL | 0 |全选。 |
| CUT | 3 |剪切。 |
| COPY | 4 |复制。 |
| PASTE | 5 |粘贴。 |
## FunctionKey10+
输入法功能键类型。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| enterKeyType10+ | [EnterKeyType](#enterkeytype10) | 是 | 是 | 输入法enter键类型。|
## InputAttribute10+
编辑框属性,包含文本输入类型和Enter键功能类型。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| textInputType10+ | [TextInputType](#textinputtype10) | 是 | 是 | 文本输入类型。|
| enterKeyType10+ | [EnterKeyType](#enterkeytype10) | 是 | 是 | Enter键功能类型。|
## TextConfig10+
编辑框的配置信息。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 只读 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| inputAttribute10+ | [InputAttribute](#inputattribute10) | 否 | 是 | 编辑框属性。|
| cursorInfo10+ | [CursorInfo](#cursorinfo10) | 否 | 否 | 光标信息。|
| selection10+ | [Range](#range10) | 否 | 否 | 文本选中的范围。|
| windowId10+ | number | 否 | 否 | 编辑框所在的窗口Id。|
## CursorInfo10+
光标信息。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| left | number | 是 | 是 | 光标的left坐标。|
| top | number | 是 | 是 | 光标的top坐标。|
| width | number | 是 | 是 | 光标的宽度。|
| height | number | 是 | 是 | 光标的高度。|
## Range10+
文本的选中范围。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| start | number | 是 | 是 | 选中文本的首字符在编辑框的索引值。|
| end | number | 是 | 是 | 选中文本的末字符在编辑框的索引值。|
## Movement10+
选中文本时,光标移动的方向。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| direction | [Direction](#direction10) | 是 | 是 | 选中文本时,光标的移动方向。|
## InputWindowInfo10+
输入法软键盘的窗口信息。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
| 名称 | 类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| name | string | 是 | 是 | 输入法窗口的名称。|
| left | number | 是 | 是 | 输入法窗口左上顶点的横坐标,单位为px。|
| top | number | 是 | 是 | 输入法窗口左上顶点的纵坐标,单位为px。|
| width | number | 是 | 是 | 输入法窗口的宽度,单位为px。|
| height | number | 是 | 是 | 输入法窗口的高度,单位为px。|
## InputMethodController
下列API示例中都需使用[getController](#inputmethodgetcontroller9)获取到InputMethodController实例,再通过实例调用对应方法。
### attach10+
attach(showKeyboard: boolean, textConfig: TextConfig, callback: AsyncCallback<void>): void
自绘控件绑定输入法。使用callback异步回调。
> **说明**
>
> 需要先调用此接口,完成自绘控件与输入法的绑定,才能使用以下功能:显示/隐藏键盘、更新光标信息、更改编辑框选中范围、保存配置信息、监听处理由输入法应用发送的信息或命令等。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| showKeyboard | boolean | 是 | 绑定输入法成功后,是否拉起输入法键盘。
- ture表示拉起,false表示不拉起。 |
| textConfig | [TextConfig](#textconfig10) | 是 | 编辑框的配置信息。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当绑定输入法成功后,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
let textConfig: inputMethod.TextConfig = {
inputAttribute: {
textInputType: 0,
enterKeyType: 1
}
};
inputMethodController.attach(true, textConfig, (err: Error) => {
if (err) {
console.error(`Failed to attach: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in attaching the inputMethod.');
});
} catch(err) {
console.error(`Failed to attach: ${JSON.stringify(err)}`);
}
```
### attach10+
attach(showKeyboard: boolean, textConfig: TextConfig): Promise<void>
自绘控件绑定输入法。使用promise异步回调。
> **说明**
>
> 需要先调用此接口,完成自绘控件与输入法的绑定,才能使用以下功能:显示/隐藏键盘、更新光标信息、更改编辑框选中范围、保存配置信息、监听处理由输入法应用发送的信息或命令等。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| showKeyboard | boolean | 是 | 绑定输入法成功后,是否拉起输入法键盘。
- ture表示拉起,false表示不拉起。|
| textConfig | [TextConfig](#textconfig10) | 是 | 编辑框的配置信息。 |
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
let textConfig: inputMethod.TextConfig = {
inputAttribute: {
textInputType: 0,
enterKeyType: 1
}
};
inputMethodController.attach(true, textConfig).then(() => {
console.log('Succeeded in attaching inputMethod.');
}).catch((err: Error) => {
console.error(`Failed to attach: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to attach: ${JSON.stringify(err)}`);
}
```
### showTextInput10+
showTextInput(callback: AsyncCallback<void>): void
进入文本编辑状态。使用callback异步回调。
> **说明**
>
> 编辑框与输入法绑定成功后,可调用该接口拉起软键盘,进入文本编辑状态。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | 是 | 回调函数。若成功进入编辑状态,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
inputMethodController.showTextInput((err: Error) => {
if (err) {
console.error(`Failed to showTextInput: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in showing the inputMethod.');
});
```
### showTextInput10+
showTextInput(): Promise<void>
进入文本编辑状态。使用promise异步回调。
> **说明**
>
> 编辑框与输入法绑定成功后,可调用该接口拉起软键盘,进入文本编辑状态。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
inputMethodController.showTextInput().then(() => {
console.log('Succeeded in showing text input.');
}).catch((err: Error) => {
console.error(`Failed to showTextInput: ${JSON.stringify(err)}`);
});
```
### hideTextInput10+
hideTextInput(callback: AsyncCallback<void>): void
退出文本编辑状态。使用callback异步回调。
> **说明**
>
> 调用接口时,若软键盘处于显示状态,调用接口后软键盘会被隐藏。
>
> 调用该接口不会解除与输入法的绑定,再次调用[showTextInput](#showtextinput10)时,可重新进入文本编辑状态。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | 是 | 回调函数。当成功退出编辑状态时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
inputMethodController.hideTextInput((err: Error) => {
if (err) {
console.error(`Failed to hideTextInput: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in hiding text input.');
});
```
### hideTextInput10+
hideTextInput(): Promise<void>
退出文本编辑状态。使用promise异步回调。
> **说明**
>
> 调用接口时,若软键盘处于显示状态,调用接口后软键盘会被隐藏。
>
> 调用该接口不会解除与输入法的绑定,再次调用[showTextInput](#showtextinput10)时,可重新进入文本编辑状态。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
inputMethodController.hideTextInput().then(() => {
console.log('Succeeded in hiding inputMethod.');
}).catch((err: Error) => {
console.error(`Failed to hideTextInput: ${JSON.stringify(err)}`);
})
```
### detach10+
detach(callback: AsyncCallback<void>): void
自绘控件解除与输入法的绑定。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | 是 | 回调函数。当解绑定输入法成功时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.detach((err: Error) => {
if (err) {
console.error(`Failed to detach: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in detaching inputMethod.');
});
```
### detach10+
detach(): Promise<void>
自绘控件解除与输入法的绑定。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.detach().then(() => {
console.log('Succeeded in detaching inputMethod.');
}).catch((err: Error) => {
console.error(`Failed to detach: ${JSON.stringify(err)}`);
});
```
### setCallingWindow10+
setCallingWindow(windowId: number, callback: AsyncCallback<void>): void
设置要避让软键盘的窗口。使用callback异步回调。
> **说明**
>
> 将绑定到输入法的应用程序所在的窗口Id传入,此窗口可以避让输入法窗口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| windowId | number | 是 | 绑定输入法应用的应用程序所在的窗口Id。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当设置成功时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let windowId: number = 2000;
inputMethodController.setCallingWindow(windowId, (err: Error) => {
if (err) {
console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in setting callingWindow.');
});
} catch(err) {
console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
}
```
### setCallingWindow10+
setCallingWindow(windowId: number): Promise<void>
设置要避让软键盘的窗口。使用promise异步回调。
> **说明**
>
> 将绑定到输入法的应用程序所在的窗口Id传入,此窗口可以避让输入法窗口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| windowId | number | 是 | 绑定输入法应用的应用程序所在的窗口Id。 |
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let windowId: number = 2000;
inputMethodController.setCallingWindow(windowId).then(() => {
console.log('Succeeded in setting callingWindow.');
}).catch((err: Error) => {
console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to setCallingWindow: ${JSON.stringify(err)}`);
}
```
### updateCursor10+
updateCursor(cursorInfo: CursorInfo, callback: AsyncCallback<void>): void
更新当前编辑框内的光标信息。当光标信息发生变化时,调用该接口使输入法感知到光标变化。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| cursorInfo | [CursorInfo](#cursorinfo10) | 是 | 光标信息。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当光标信息更新成功时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let cursorInfo: inputMethod.CursorInfo = { left: 0, top: 0, width: 600, height: 800 };
inputMethodController.updateCursor(cursorInfo, (err: Error) => {
if (err) {
console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in updating cursorInfo.');
});
} catch(err) {
console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
}
```
### updateCursor10+
updateCursor(cursorInfo: CursorInfo): Promise<void>
更新当前编辑框内的光标信息。当光标信息发生变化时,调用该接口使输入法感知到光标变化。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| cursorInfo | [CursorInfo](#cursorinfo10) | 是 | 光标信息。 |
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let cursorInfo: inputMethod.CursorInfo = { left: 0, top: 0, width: 600, height: 800 };
inputMethodController.updateCursor(cursorInfo).then(() => {
console.log('Succeeded in updating cursorInfo.');
}).catch((err: Error) => {
console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to updateCursor: ${JSON.stringify(err)}`);
}
```
### changeSelection10+
changeSelection(text: string, start: number, end: number, callback: AsyncCallback<void>): void
更新当前编辑框内被选中的文本信息。当选中的文本内容或文本范围发生变化时,可调用该接口更新文本信息,使输入法应用感知到变化。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| text | string | 是 | 整个输入文本。 |
| start | number | 是 | 所选文本的起始位置。 |
| end | number | 是 | 所选文本的结束位置。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当文本信息更新成功时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.changeSelection('text', 0, 5, (err: Error) => {
if (err) {
console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in changing selection.');
});
} catch(err) {
console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
}
```
### changeSelection10+
changeSelection(text: string, start: number, end: number): Promise<void>
更新当前编辑框内被选中的文本信息。当选中的文本内容或文本范围发生变化时,可调用该接口更新文本信息,使输入法应用感知到变化。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| text | string | 是 | 整个输入文本。 |
| start | number | 是 | 所选文本的起始位置。 |
| end | number | 是 | 所选文本的结束位置。 |
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.changeSelection('test', 0, 5).then(() => {
console.log('Succeeded in changing selection.');
}).catch((err: Error) => {
console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to changeSelection: ${JSON.stringify(err)}`);
}
```
### updateAttribute10+
updateAttribute(attribute: InputAttribute, callback: AsyncCallback<void>): void
更新编辑框属性信息。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| attribute | [InputAttribute](#inputattribute10) | 是 | 编辑框属性对象。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当编辑框属性信息更新成功时,err为undefined;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
inputMethodController.updateAttribute(inputAttribute, (err: Error) => {
if (err) {
console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in updating attribute.');
});
} catch(err) {
console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
}
```
### updateAttribute10+
updateAttribute(attribute: InputAttribute): Promise<void>
更新编辑框属性信息。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| attribute | [InputAttribute](#inputattribute10) | 是 | 编辑框属性对象。 |
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
inputMethodController.updateAttribute(inputAttribute).then(() => {
console.log('Succeeded in updating attribute.');
}).catch((err: Error) => {
console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to updateAttribute: ${JSON.stringify(err)}`);
}
```
### stopInputSession9+
stopInputSession(callback: AsyncCallback<boolean>): void
结束输入会话。使用callback异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用该接口结束输入会话。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当结束输入会话成功时,err为undefined,data为true;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodController.stopInputSession((err: Error, result: boolean) => {
if (err) {
console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
return;
}
if (result) {
console.log('Succeeded in stopping inputSession.');
} else {
console.error('Failed to stopInputSession.');
}
});
} catch(err) {
console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
}
```
### stopInputSession9+
stopInputSession(): Promise<boolean>
结束输入会话。使用promise异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用该接口结束输入会话。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<boolean> | Promise对象。返回true表示结束输入会话成功,返回false表示结束输入会话失败。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodController.stopInputSession().then((result: boolean) => {
if (result) {
console.log('Succeeded in stopping inputSession.');
} else {
console.error('Failed to stopInputSession.');
}
}).catch((err: Error) => {
console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to stopInputSession: ${JSON.stringify(err)}`);
}
```
### showSoftKeyboard9+
showSoftKeyboard(callback: AsyncCallback<void>): void
显示输入法软键盘。使用callback异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用显示当前输入法的软键盘。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY,仅系统应用可用。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | 是 | 回调函数。当软键盘显示成功。err为undefined,否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.showSoftKeyboard((err: Error) => {
if (!err) {
console.log('Succeeded in showing softKeyboard.');
} else {
console.error(`Failed to show softKeyboard: ${JSON.stringify(err)}`);
}
})
```
### showSoftKeyboard9+
showSoftKeyboard(): Promise<void>
显示输入法软键盘。使用Promise异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用显示当前输入法的软键盘。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY,仅系统应用可用。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.showSoftKeyboard().then(() => {
console.log('Succeeded in showing softKeyboard.');
}).catch((err: Error) => {
console.error(`Failed to show softKeyboard: ${JSON.stringify(err)}`);
});
```
### hideSoftKeyboard9+
hideSoftKeyboard(callback: AsyncCallback<void>): void
隐藏输入法软键盘。使用callback异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用隐藏当前输入法的软键盘。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY,仅系统应用可用。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | 是 | 回调函数。当软键盘隐藏成功。err为undefined,否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.hideSoftKeyboard((err: Error) => {
if (!err) {
console.log('Succeeded in hiding softKeyboard.');
} else {
console.error(`Failed to hide softKeyboard: ${JSON.stringify(err)}`);
}
})
```
### hideSoftKeyboard9+
hideSoftKeyboard(): Promise<void>
隐藏输入法软键盘。使用Promise异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用隐藏当前输入法的软键盘。
**需要权限:** ohos.permission.CONNECT_IME_ABILITY,仅系统应用可用。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise<void> | 无返回结果的Promise对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800003 | input method client error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodController.hideSoftKeyboard().then(() => {
console.log('Succeeded in hiding softKeyboard.');
}).catch((err: Error) => {
console.error(`Failed to hide softKeyboard: ${JSON.stringify(err)}`);
});
```
### stopInput(deprecated)
stopInput(callback: AsyncCallback<boolean>): void
结束输入会话。使用callback异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用该接口结束输入会话。
>
> 从API version 6开始支持,从API version 9开始废弃,建议使用[stopInputSession()](#stopinputsession9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当会话结束成功,err为undefined,data为true;否则为错误对象。 |
**示例:**
```ts
inputMethodController.stopInput((err: Error, result: boolean) => {
if (err) {
console.error(`Failed to stopInput: ${JSON.stringify(err)}`);
return;
}
if (result) {
console.log('Succeeded in stopping input.');
} else {
console.error('Failed to stopInput.');
}
});
```
### stopInput(deprecated)
stopInput(): Promise<boolean>
结束输入会话。使用promise异步回调。
> **说明:**
>
> 该接口需要编辑框与输入法绑定时才能调用,即点击编辑控件后,才可调用该接口结束输入会话。
>
> 从API version 6开始支持,从API version 9开始废弃,建议使用[stopInputSession()](#stopinputsession9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<boolean> | Promise对象。返回true表示会话结束成功;返回false表示会话结束失败。 |
**示例:**
```ts
inputMethodController.stopInput().then((result: boolean) => {
if (result) {
console.log('Succeeded in stopping input.');
} else {
console.error('Failed to stopInput.');
}
}).catch((err: Error) => {
console.error(`Failed to stopInput: ${JSON.stringify(err)}`);
})
```
### on('insertText')10+
on(type: 'insertText', callback: (text: string) => void): void;
订阅输入法应用插入文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'insertText'。 |
| callback | (text: string) => void | 是 | 回调函数,返回需要插入的文本内容。
根据传入的文本,在回调函数中操作编辑框中的内容。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('insertText', (text: string) => {
console.log(`Succeeded in subscribing insertText: ${text}`);
});
} catch(err) {
console.error(`Failed to subscribe insertText: ${JSON.stringify(err)}`);
}
```
### off('insertText')10+
off(type: 'insertText', callback?: (text: string) => void): void
取消订阅输入法应用插入文本事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'insertText'。 |
| callback | (text: string) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onInsertTextCallback = (text: string) => {
console.log(`Succeeded in subscribing insertText: ${text}`);
};
inputMethodController.off('insertText', onInsertTextCallback);
inputMethodController.off('insertText');
```
### on('deleteLeft')10+
on(type: 'deleteLeft', callback: (length: number) => void): void
订阅输入法应用向左删除事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ----- |
| type | string | 是 | 设置监听类型,固定取值为'deleteLeft'。|
| callback | (length: number) => void | 是 | 回调函数,返回需要向左删除的文本长度。
根据传入的删除长度,在回调函数中操作编辑框中的文本。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('deleteLeft', (length: number) => {
console.log(`Succeeded in subscribing deleteLeft, length: ${length}`);
});
} catch(err) {
console.error(`Failed to subscribe deleteLeft: ${JSON.stringify(err)}`);
}
```
### off('deleteLeft')10+
off(type: 'deleteLeft', callback?: (length: number) => void): void
取消订阅输入法应用向左删除文本事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听,固定取值为'deleteLeft'。 |
| callback | (length: number) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onDeleteLeftCallback = (length: number) => {
console.log(`Succeeded in subscribing deleteLeft, length: ${length}`);
};
inputMethodController.off('deleteLeft', onDeleteLeftCallback);
inputMethodController.off('deleteLeft');
```
### on('deleteRight')10+
on(type: 'deleteRight', callback: (length: number) => void): void
订阅输入法应用向右删除事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ----- |
| type | string | 是 | 设置监听类型,固定取值为'deleteRight'。|
| callback | (length: number) => void | 是 | 回调函数,返回需要向右删除的文本长度。
根据传入的删除长度,在回调函数中操作编辑框中的文本。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('deleteRight', (length: number) => {
console.log(`Succeeded in subscribing deleteRight, length: ${length}`);
});
} catch(err) {
console.error(`Failed to subscribe deleteRight: ${JSON.stringify(err)}`);
}
```
### off('deleteRight')10+
off(type: 'deleteRight', callback?: (length: number) => void): void
取消订阅输入法应用向右删除文本事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为`deleteRight`。 |
| callback | (length: number) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onDeleteRightCallback = (length: number) => {
console.log(`Succeeded in subscribing deleteRight, length: ${length}`);
};
inputMethodController.off('deleteRight', onDeleteRightCallback);
inputMethodController.off('deleteRight');
```
### on('sendKeyboardStatus')10+
on(type: 'sendKeyboardStatus', callback: (keyboardStatus: KeyboardStatus) => void): void
订阅输入法应用发送输入法软键盘状态事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---- |
| type | string | 是 | 设置监听类型,固定取值为'sendKeyboardStatus'。 |
| callback | (keyboardStatus: [KeyboardStatus](#keyboardstatus10)) => void | 是 | 回调函数,返回软键盘状态。
根据传入的软键盘状态,在回调函数中做相应操作。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('sendKeyboardStatus', (keyboardStatus: inputMethod.KeyboardStatus) => {
console.log(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
});
} catch(err) {
console.error(`Failed to subscribe sendKeyboardStatus: ${JSON.stringify(err)}`);
}
```
### off('sendKeyboardStatus')10+
off(type: 'sendKeyboardStatus', callback?: (keyboardStatus: KeyboardStatus) => void): void
取消订阅输入法应用发送软键盘状态事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'sendKeyboardStatus'。 |
| callback | (keyboardStatus: [KeyboardStatus](#keyboardstatus10)) => void | 否 | 取消订阅的回调函数。参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onSendKeyboardStatus = (keyboardStatus: inputMethod.KeyboardStatus) => {
console.log(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
};
inputMethodController.off('sendKeyboardStatus', onSendKeyboardStatus);
inputMethodController.off('sendKeyboardStatus');
```
### on('sendFunctionKey')10+
on(type: 'sendFunctionKey', callback: (functionKey: FunctionKey) => void): void
订阅输入法应用发送功能键事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ----- |
| type | string | 是 | 设置监听类型,固定取值为'sendFunctionKey'。|
| callback | (functionKey: [FunctionKey](#functionkey10)) => void | 是 | 回调函数,返回输入法应用发送的功能键信息。
根据返回的功能键信息,做相应操作。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('sendFunctionKey', (functionKey: inputMethod.FunctionKey) => {
console.log(`Succeeded in subscribing sendFunctionKey, functionKey.enterKeyType: ${functionKey.enterKeyType}`);
});
} catch(err) {
console.error(`Failed to subscribe sendFunctionKey: ${JSON.stringify(err)}`);
}
```
### off('sendFunctionKey')10+
off(type: 'sendFunctionKey', callback?: (functionKey: FunctionKey) => void): void
取消订阅输入法应用发送功能键事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'sendFunctionKey'。 |
| callback | (functionKey: [FunctionKey](#functionkey10)) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onSendFunctionKey = (functionKey: inputMethod.FunctionKey) => {
console.log(`Succeeded in subscribing sendFunctionKey, functionKey: ${functionKey.enterKeyType}`);
};
inputMethodController.off('sendFunctionKey', onSendFunctionKey);
inputMethodController.off('sendFunctionKey');
```
### on('moveCursor')10+
on(type: 'moveCursor', callback: (direction: Direction) => void): void
订阅输入法应用移动光标事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值为'moveCursor'。 |
| callback | callback: (direction: [Direction10+](#direction10)) => void | 是 | 回调函数,返回光标信息。
根据返回的光标移动方向,改变光标位置,如光标向上或向下。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('moveCursor', (direction: inputMethod.Direction) => {
console.log(`Succeeded in subscribing moveCursor, direction: ${direction}`);
});
} catch(err) {
console.error(`Failed to subscribe moveCursor: ${JSON.stringify(err)}`);
}
```
### off('moveCursor')10+
off(type: 'moveCursor', callback?: (direction: Direction) => void): void
取消订阅输入法应用移动光标事件。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---- |
| type | string | 是 | 设置监听类型,固定取值为'moveCursor'。 |
| callback | (direction: [Direction10+](#direction10)) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onMoveCursorCallback = (direction: inputMethod.Direction) => {
console.log(`Succeeded in subscribing moveCursor, direction: ${direction}`);
};
inputMethodController.off('moveCursor', onMoveCursorCallback);
inputMethodController.off('moveCursor');
```
### on('handleExtendAction')10+
on(type: 'handleExtendAction', callback: (action: ExtendAction) => void): void
订阅输入法应用发送扩展编辑操作事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | -------- |
| type | string | 是 | 设置监听类型,固定取值为'handleExtendAction'。 |
| callback | callback: (action: [ExtendAction](#extendaction10)) => void | 是 | 回调函数,返回扩展编辑操作类型。
根据传入的扩展编辑操作类型,做相应的操作,如剪切、复制等。|
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('handleExtendAction', (action: inputMethod.ExtendAction) => {
console.log(`Succeeded in subscribing handleExtendAction, action: ${action}`);
});
} catch(err) {
console.error(`Failed to subscribe handleExtendAction: ${JSON.stringify(err)}`);
}
```
### off('handleExtendAction')10+
off(type: 'handleExtendAction', callback?: (action: ExtendAction) => void): void
取消订阅输入法应用发送扩展编辑操作事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------- |
| type | string | 是 | 设置监听类型,固定取值为'handleExtendAction'。 |
| callback | (action: [ExtendAction](#extendaction10)) => void | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onHandleExtendActionCallback = (action: inputMethod.ExtendAction) => {
console.log(`Succeeded in subscribing handleExtendAction, action: ${action}`);
};
inputMethodController.off('handleExtendAction', onHandleExtendActionCallback);
inputMethodController.off('handleExtendAction');
```
### on('selectByRange')10+
on(type: 'selectByRange', callback: Callback<Range>): void
订阅输入法应用按范围选中文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---- | ---- | ------- |
| type | string | 是 | 设置监听类型,固定取值为'selectByRange'。 |
| callback | Callback<[Range](#range10)> | 是 | 回调函数,返回需要选中的文本范围。
根据传入的文本范围,开发者在回调函数中编辑框中相应文本。|
**示例:**
```ts
inputMethodController.on('selectByRange', (range: inputMethod.Range) => {
console.log(`Succeeded in subscribing selectByRange: start: ${range.start} , end: ${range.end}`);
});
```
### off('selectByRange')10+
off(type: 'selectByRange', callback?: Callback<Range>): void
取消订阅输入法应用按范围选中文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'selectByRange'。 |
| callback | Callback<[Range](#range10)> | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onSelectByRangeCallback = (range: inputMethod.Range) => {
console.log(`Succeeded in subscribing selectByRange, range: ${JSON.stringify(range)}`);
};
inputMethodController.off('selectByRange', onSelectByRangeCallback);
inputMethodController.off('selectByRange');
```
### on('selectByMovement')10+
on(type: 'selectByMovement', callback: Callback<Movement>): void
订阅输入法应用按光标移动方向,选中文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值为'selectByMovement'。 |
| callback | Callback<[Movement](#movement10)> | 是 | 回调函数,返回光标移动的方向。
根据传入的光标移动方向,选中编辑框中相应文本。 |
**示例:**
```ts
inputMethodController.on('selectByMovement', (movement: inputMethod.Movement) => {
console.log('Succeeded in subscribing selectByMovement: direction: ' + movement.direction);
});
```
### off('selectByMovement')10+
off(type: 'selectByMovement', callback?: Callback<Movement>): void
取消订阅输入法应用按光标移动方向,选中文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'selectByMovement'。 |
| callback | Callback<[Movement](#movement10)> | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
let onSelectByMovementCallback = (movement: inputMethod.Movement) => {
console.log(`Succeeded in subscribing selectByMovement, movement.direction: ${movement.direction}`);
};
inputMethodController.off('selectByMovement', onSelectByMovementCallback);
inputMethodController.off('selectByMovement');
```
### on('getLeftTextOfCursor')10+
on(type: 'getLeftTextOfCursor', callback: (length: number) => string): void;
订阅输入法应用获取光标左侧指定长度文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值为'getLeftTextOfCursor'。 |
| callback | (length: number) => string | 是 | 回调函数,获取编辑框最新状态下光标左侧指定长度的文本内容并返回。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('getLeftTextOfCursor', (length: number) => {
console.info(`Succeeded in subscribing getLeftTextOfCursor, length: ${length}`);
let text:string = "";
return text;
});
} catch(err) {
console.error(`Failed to subscribe getLeftTextOfCursor. err: ${JSON.stringify(err)}`);
}
```
### off('getLeftTextOfCursor')10+
off(type: 'getLeftTextOfCursor', callback?: (length: number) => string): void;
取消订阅输入法应用获取光标左侧指定长度文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'getLeftTextOfCursor'。 |
| callback | (length: number) => string | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。|
**示例:**
```ts
try {
let getLeftTextOfCursorCallback = (length: number) => {
console.info(`Succeeded in unsubscribing getLeftTextOfCursor, length: ${length}`);
let text:string = "";
return text;
};
inputMethodController.off('getLeftTextOfCursor', getLeftTextOfCursorCallback);
inputMethodController.off('getLeftTextOfCursor');
} catch(err) {
console.error(`Failed to unsubscribing getLeftTextOfCursor. err: ${JSON.stringify(err)}`);
}
```
### on('getRightTextOfCursor')10+
on(type: 'getRightTextOfCursor', callback: (length: number) => string): void;
订阅输入法应用获取光标右侧指定长度文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值为'getRightTextOfCursor'。 |
| callback | (length: number) => string | 是 | 回调函数,获取编辑框最新状态下光标右侧指定长度的文本内容并返回。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('getRightTextOfCursor', (length: number) => {
console.info(`Succeeded in subscribing getRightTextOfCursor, length: ${length}`);
let text:string = "";
return text;
});
} catch(err) {
console.error(`Failed to subscribe getRightTextOfCursor. err: ${JSON.stringify(err)}`);
}
```
### off('getRightTextOfCursor')10+
off(type: 'getRightTextOfCursor', callback?: (length: number) => string): void;
取消订阅输入法应用获取光标右侧指定长度文本事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'getRightTextOfCursor'。 |
| callback | (length: number) => string | 否 |取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。|
**示例:**
```ts
try {
let getRightTextOfCursorCallback = (length: number) => {
console.info(`Succeeded in unsubscribing getRightTextOfCursor, length: ${length}`);
let text:string = "";
return text;
};
inputMethodController.off('getRightTextOfCursor', getRightTextOfCursorCallback);
inputMethodController.off('getRightTextOfCursor');
} catch(err) {
console.error(`Failed to unsubscribing getRightTextOfCursor. err: ${JSON.stringify(err)}`);
}
```
### on('getTextIndexAtCursor')10+
on(type: 'getTextIndexAtCursor', callback: () => number): void;
订阅输入法应用获取光标处文本索引事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值为'getTextIndexAtCursor'。 |
| callback | () => number | 是 | 回调函数,获取编辑框最新状态下光标处文本索引并返回。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800009 | input method client is detached. |
**示例:**
```ts
try {
inputMethodController.on('getTextIndexAtCursor', () => {
console.info(`Succeeded in subscribing getTextIndexAtCursor.`);
let index:number = 0;
return index;
});
} catch(err) {
console.error(`Failed to subscribe getTextIndexAtCursor. err: ${JSON.stringify(err)}`);
}
```
### off('getTextIndexAtCursor')10+
off(type: 'getTextIndexAtCursor', callback?: () => number): void;
取消订阅输入法应用获取光标处文本索引事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'getTextIndexAtCursor'。 |
| callback | () => number | 否 | 取消订阅的回调函数,需要与on接口传入的保持一致。
参数不填写时,取消订阅type对应的所有回调事件。|
**示例:**
```ts
try {
let getTextIndexAtCursorCallback = () => {
console.info(`Succeeded in unsubscribing getTextIndexAtCursor.`);
let index:number = 0;
return index;
};
inputMethodController.off('getTextIndexAtCursor', getTextIndexAtCursorCallback);
inputMethodController.off('getTextIndexAtCursor');
} catch(err) {
console.error(`Failed to unsubscribing getTextIndexAtCursor. err: ${JSON.stringify(err)}`);
}
```
## InputMethodSetting8+
下列API均需使用[getSetting](#inputmethodgetsetting9)获取到InputMethodSetting实例后,通过实例调用。
### on('imeChange')9+
on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void
订阅输入法及子类型变化监听事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 设置监听类型,固定取值为'imeChange'。 |
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | 是 | 回调函数,返回输入法属性对象及子类型对象。 |
**示例:**
```ts
import InputMethodSubtype from '@ohos.InputMethodSubtype';
inputMethodSetting.on('imeChange', (inputMethodProperty: inputMethod.InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => {
console.log('Succeeded in subscribing imeChange: inputMethodProperty: ' + JSON.stringify(inputMethodProperty) + " , inputMethodSubtype: " + JSON.stringify(inputMethodSubtype));
});
```
### off('imeChange')9+
off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void
取消订阅输入法及子类型变化监听事件。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------- | ---- | --------------- |
| type | string | 是 | 设置监听类型,固定取值为'imeChange'。 |
| callback | (inputMethodProperty: [InputMethodProperty](#inputmethodproperty8), inputMethodSubtype: [InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)) => void | 否 | 回调函数,返回取消订阅的输入法属性对象及子类型对象。 |
**示例:**
```ts
inputMethodSetting.off('imeChange');
```
### on('imeShow')10+
on(type: 'imeShow', callback: (info: Array\) => void): void
订阅输入法软键盘显示事件。使用callback异步回调。
**系统接口**:此接口为系统接口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---- | ---- | ---- |
| type | string | 是 | 设置监听类型,固定取值为'imeShow'。 |
| callback | (info: Array\) => void | 是 | 回调函数,返回输入法软键盘信息。 |
**示例:**
```ts
inputMethodSetting.on('imeShow', (info: Array) => {
console.info('Succeeded in subscribing imeShow event.');
});
```
### on('imeHide')10+
on(type: 'imeHide', callback: (info: Array\) => void): void
订阅输入法软键盘隐藏事件。使用callback异步回调。
**系统接口**:此接口为系统接口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---- | ---- | ---- |
| type | string | 是 | 设置监听类型,固定取值为'imeHide'。 |
| callback | (info: Array\) => void | 是 | 回调函数,返回输入法软键盘信息。 |
**示例:**
```ts
inputMethodSetting.on('imeHide', (info: Array) => {
console.info('Succeeded in subscribing imeHide event.');
});
```
### off('imeShow')10+
off(type: 'imeShow', callback?: (info: Array\) => void): void
取消订阅输入法软键盘显示事件。
**系统接口**:此接口为系统接口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值`imeShow`。 |
| callback | (info: Array\) => void | 否 | 取消订阅的回调函数。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
inputMethodSetting.off('imeShow');
```
### off('imeHide')10+
off(type: 'imeHide', callback?: (info: Array\) => void): void
取消订阅输入法软键盘隐藏事件。
**系统接口**:此接口为系统接口。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---- | ---- | ------ |
| type | string | 是 | 设置监听类型,固定取值'imeHide'。 |
| callback | (info: Array\) => void | 否 | 取消订阅的回调函数。
参数不填写时,取消订阅type对应的所有回调事件。 |
**示例:**
```ts
inputMethodSetting.off('imeHide');
```
### listInputMethodSubtype9+
listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void
获取指定输入法应用的所有子类型。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| 是 | 输入法应用。 |
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | 是 | 回调函数,返回指定输入法应用的所有子类型。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let inputMethodProperty: inputMethod.InputMethodProperty = {
packageName: 'com.example.kikakeyboard',
name: 'InputMethodExAbility',
methodId: '',
id: 'propertyId',
}
try {
inputMethodSetting.listInputMethodSubtype(inputMethodProperty, (err: Error, data: Array) => {
if (err) {
console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in listing inputMethodSubtype.');
});
} catch (err) {
console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
### listInputMethodSubtype9+
listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>>
获取指定输入法应用的所有子类型。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| inputMethodProperty | [InputMethodProperty](#inputmethodproperty8)| 是 | 输入法应用。 |
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------------------- | ---------------------- |
| Promise> | Promise对象,返回指定输入法应用的所有子类型。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
let inputMethodProperty: inputMethod.InputMethodProperty = {
packageName: 'com.example.kikakeyboard',
name: 'InputMethodExAbility',
methodId: '',
id: 'propertyId',
}
try {
inputMethodSetting.listInputMethodSubtype(inputMethodProperty).then((data: Array) => {
console.log('Succeeded in listing inputMethodSubtype.');
}).catch((err: Error) => {
console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to listInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
### listCurrentInputMethodSubtype9+
listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void
查询当前输入法应用的所有子类型。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | AsyncCallback<Array<[InputMethodSubtype](./js-apis-inputmethod-subtype.md#inputmethodsubtype)>> | 是 | 回调函数,返回当前输入法应用的所有子类型。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodSetting.listCurrentInputMethodSubtype((err: Error, data: Array) => {
if (err) {
console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in listing currentInputMethodSubtype.');
});
} catch(err) {
console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
### listCurrentInputMethodSubtype9+
listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>>
查询当前输入法应用的所有子类型。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------------------- | ---------------------- |
| Promise> | Promise对象,返回当前输入法应用的所有子类型。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodSetting.listCurrentInputMethodSubtype().then((data: Array) => {
console.log('Succeeded in listing currentInputMethodSubtype.');
}).catch((err: Error) => {
console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to listCurrentInputMethodSubtype: ${JSON.stringify(err)}`);
}
```
### getInputMethods9+
getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void
获取已激活/未激活的输入法应用列表。使用callback异步回调。
> **说明**
>
> 已激活输入法包括当前使用的输入法,未激活输入法包括当前输入法以外的其他已安装的输入法。
>
> 已激活/未激活为预留概念,暂不支持。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ----------------------------- |
| enable | boolean | 是 |true表示返回已激活输入法列表,false表示返回未激活输入法列表。 |
| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | 是 | 回调函数,返回已激活/未激活输入法列表。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodSetting.getInputMethods(true, (err: Error, data: Array) => {
if (err) {
console.error(`Failed to getInputMethods: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in getting inputMethods.');
});
} catch (err) {
console.error(`Failed to getInputMethods: ${JSON.stringify(err)}`);
}
```
### getInputMethods9+
getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>
获取已激活/未激活的输入法应用列表。使用promise异步回调。
> **说明**
>
> 已激活输入法包括当前使用的输入法,未激活输入法包括当前输入法以外的其他已安装的输入法。
>
> 已激活/未激活为预留概念,暂不支持。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------- |
| enable | boolean | 是 |- true表示返回已激活输入法列表,false表示返回未激活输入法列表。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800001 | package manager error. |
| 12800008 |input method manager service error. |
**返回值:**
| 类型 | 说明 |
| ------------------------------------------------------------ | ----------------------------- |
| Promise\> | Promise对象,返回已激活/未激活输入法列表。 |
**示例:**
```ts
try {
inputMethodSetting.getInputMethods(true).then((data: Array) => {
console.log('Succeeded in getting inputMethods.');
}).catch((err: Error) => {
console.error(`Failed to getInputMethods: ${JSON.stringify(err)}`);
})
} catch(err) {
console.error(`Failed to getInputMethods: ${JSON.stringify(err)}`);
}
```
### showOptionalInputMethods9+
showOptionalInputMethods(callback: AsyncCallback<boolean>): void
显示输入法选择对话框。使用callback异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | 是 | 回调函数。当输入法选择对话框显示成功,err为undefined,data为true;否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800008 | input method manager service error. |
**示例:**
```ts
try {
inputMethodSetting.showOptionalInputMethods((err: Error, data: boolean) => {
if (err) {
console.error(`Failed to showOptionalInputMethods: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in showing optionalInputMethods.');
});
} catch (err) {
console.error(`Failed to showOptionalInputMethods: ${JSON.stringify(err)}`);
}
```
### showOptionalInputMethods9+
showOptionalInputMethods(): Promise<boolean>
显示输入法选择对话框。使用promise异步回调。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<boolean> | Promise对象。返回true表示输入法选择对话框显示成功,返回false表示输入法选择对话框显示失败。 |
**错误码:**
以下错误码的详细介绍请参见[输入法框架错误码](../errorcodes/errorcode-inputmethod-framework.md)。
| 错误码ID | 错误信息 |
| -------- | -------------------------------------- |
| 12800008 | input method manager service error. |
**示例:**
```ts
inputMethodSetting.showOptionalInputMethods().then((data: boolean) => {
console.log('Succeeded in showing optionalInputMethods.');
}).catch((err: Error) => {
console.error(`Failed to showOptionalInputMethods: ${JSON.stringify(err)}`);
})
```
### listInputMethod(deprecated)
listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void
查询已安装的输入法列表。使用callback异步回调。
> **说明:**
>
> 从API version 8开始支持,从API version 9开始废弃,建议使用[getInputMethods](#getinputmethods9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------------------- | ---- | ---------------------- |
| callback | AsyncCallback<Array<[InputMethodProperty](#inputmethodproperty8)>> | 是 | 回调函数,返回已安装的输入法列表。 |
**示例:**
```ts
inputMethodSetting.listInputMethod((err: Error, data: Array) => {
if (err) {
console.error(`Failed to listInputMethod: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in listing inputMethod.');
});
```
### listInputMethod(deprecated)
listInputMethod(): Promise<Array<InputMethodProperty>>
查询已安装的输入法列表。使用promise异步回调。
> **说明:**
>
> 从API version 8开始支持,从API version 9开始废弃,建议使用[getInputMethods](#getinputmethods9-1)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------------------- | ---------------------- |
| Promise> | Promise对象,返回已安装输入法列表。 |
**示例:**
```ts
inputMethodSetting.listInputMethod().then((data: Array) => {
console.log('Succeeded in listing inputMethod.');
}).catch((err: Error) => {
console.error(`Failed to listInputMethod: ${JSON.stringify(err)}`);
})
```
### displayOptionalInputMethod(deprecated)
displayOptionalInputMethod(callback: AsyncCallback<void>): void
显示输入法选择对话框。使用callback异步回调。
> **说明:**
>
> 从API version 8开始支持,从API version 9开始废弃,建议使用[showOptionalInputMethods()](#showoptionalinputmethods9)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | 是 | 回调函数。当输入法选择对话框显示成功。err为undefined,否则为错误对象。 |
**示例:**
```ts
inputMethodSetting.displayOptionalInputMethod((err: Error) => {
if (err) {
console.error(`Failed to displayOptionalInputMethod: ${JSON.stringify(err)}`);
return;
}
console.log('Succeeded in displaying optionalInputMethod.');
});
```
### displayOptionalInputMethod(deprecated)
displayOptionalInputMethod(): Promise<void>
显示输入法选择对话框。使用promise异步回调。
> **说明:**
>
> 从API version 8开始支持,从API version 9开始废弃,建议使用[showOptionalInputMethods()](#showoptionalinputmethods9-1)替代。
**系统能力:** SystemCapability.MiscServices.InputMethodFramework
**返回值:**
| 类型 | 说明 |
| -------- | -------- |
| Promise<void> | 无返回结果的Promise对象。 |
**示例:**
```ts
inputMethodSetting.displayOptionalInputMethod().then(() => {
console.log('Succeeded in displaying optionalInputMethod.');
}).catch((err: Error) => {
console.error(`Failed to displayOptionalInputMethod: ${JSON.stringify(err)}`);
})
```