HarmonyOS API:@ohos.inputMethodEngine (输入法服务)
版本:v3.1 Beta
@ohos.inputMethodEngine (输入法服务)
更新时间: 2023-02-17 09:19
本模块的作用是拉通输入法应用和其他三方应用(联系人、微信等),功能包括:将三方应用与输入法应用的服务进行绑定、三方应用通过输入法应用进行文本输入、三方应用对输入法应用进行显示键盘请求和隐藏键盘请求、三方应用对输入法应用当前状态进行监听等。
说明
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
导入模块
常量
功能键常量值、编辑框常量值及光标常量值。
系统能力: SystemCapability.MiscServices.InputMethodFramework
名称 | 类型 | 值 | 说明 |
ENTER_KEY_TYPE_UNSPECIFIED | number | 0 | 无功能键。 |
ENTER_KEY_TYPE_GO | number | 2 | “前往”功能键。 |
ENTER_KEY_TYPE_SEARCH | number | 3 | “搜索”功能键。 |
ENTER_KEY_TYPE_SEND | number | 4 | “发送”功能键。 |
ENTER_KEY_TYPE_NEXT | number | 5 | “下一个”功能键。 |
ENTER_KEY_TYPE_DONE | number | 6 | “回车”功能键。 |
ENTER_KEY_TYPE_PREVIOUS | number | 7 | “前一个”功能键。 |
PATTERN_NULL | number | -1 | 无特殊性编辑框。 |
PATTERN_TEXT | number | 0 | 文本编辑框。 |
PATTERN_NUMBER | number | 2 | 数字编辑框。 |
PATTERN_PHONE | number | 3 | 电话号码编辑框。 |
PATTERN_DATETIME | number | 4 | 日期编辑框。 |
PATTERN_EMAIL | number | 5 | 邮件编辑框。 |
PATTERN_URI | number | 6 | 超链接编辑框。 |
PATTERN_PASSWORD | number | 7 | 密码编辑框。 |
OPTION_ASCII | number | 20 | 允许输入ASCII值。 |
OPTION_NONE | number | 0 | 不指定编辑框输入属性。 |
OPTION_AUTO_CAP_CHARACTERS | number | 2 | 允许输入字符。 |
OPTION_AUTO_CAP_SENTENCES | number | 8 | 允许输入句子。 |
OPTION_AUTO_WORDS | number | 4 | 允许输入单词。 |
OPTION_MULTI_LINE | number | 1 | 允许输入多行。 |
OPTION_NO_FULLSCREEN | number | 10 | 半屏样式。 |
FLAG_SELECTING | number | 2 | 编辑框处于选择状态。 |
FLAG_SINGLE_LINE | number | 1 | 编辑框为单行。 |
DISPLAY_MODE_PART | number | 0 | 编辑框显示为半屏。 |
DISPLAY_MODE_FULL | number | 1 | 编辑框显示为全屏。 |
CURSOR_UP9+ | number | 1 | 光标上移。 |
CURSOR_DOWN9+ | number | 2 | 光标下移。 |
CURSOR_LEFT9+ | number | 3 | 光标左移。 |
CURSOR_RIGHT9+ | number | 4 | 光标右移。 |
WINDOW_TYPE_INPUT_METHOD_FLOAT9+ | number | 2105 | 输入法应用窗口风格标识。 |
inputMethodEngine.getInputMethodAbility9+
getInputMethodAbility(): InputMethodAbility
获取服务端实例。
系统能力: SystemCapability.MiscServices.InputMethodFramework
返回值:
类型 | 说明 |
服务端实例。 |
示例:
inputMethodEngine.getKeyboardDelegate9+
getKeyboardDelegate(): KeyboardDelegate
获取客户端监听实例。
系统能力: SystemCapability.MiscServices.InputMethodFramework
返回值:
类型 | 说明 |
客户端监听实例。 |
示例:
inputMethodEngine.getInputMethodEngine(deprecated)
getInputMethodEngine(): InputMethodEngine
获取服务端实例。
说明
从API version 8开始支持,API version 9开始废弃, 建议使用getInputMethodAbility()替代。
系统能力: SystemCapability.MiscServices.InputMethodFramework
返回值:
类型 | 说明 |
服务端实例。 |
示例:
inputMethodEngine.createKeyboardDelegate(deprecated)
createKeyboardDelegate(): KeyboardDelegate
获取客户端监听实例。
说明
从API version 8开始支持,API version 9开始废弃, 建议使用getKeyboardDelegate()替代。
系统能力: SystemCapability.MiscServices.InputMethodFramework
返回值:
类型 | 说明 |
客户端监听实例。 |
示例:
InputMethodEngine
下列API示例中都需使用getInputMethodEngine回调获取到InputMethodEngine实例,再通过此实例调用对应方法。
on('inputStart')
on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void
订阅输入法绑定成功事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStart’时表示订阅输入法绑定。 |
callback | (kbController: KeyboardController, textInputClient: TextInputClient) => void | 是 | 回调函数,返回订阅输入法的KeyboardController和TextInputClient实例。 |
示例:
off('inputStart')
off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void
取消订阅输入法绑定成功事件。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStart’时表示订阅输入法绑定。 |
callback | (kbController: KeyboardController, textInputClient: TextInputClient) => void | 否 | 回调函数,返回取消订阅的KeyboardController和TextInputClient实例。 |
示例:
on('keyboardShow'|'keyboardHide')
on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void
订阅输入法事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyboardShow',表示订阅输入法显示。 - type为'keyboardHide',表示订阅输入法隐藏。 |
callback | () => void | 是 | 回调函数。 |
示例:
off('keyboardShow'|'keyboardHide')
off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void
取消订阅输入法事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyboardShow',表示订阅输入法显示。 - type为'keyboardHide',表示订阅输入法隐藏。 |
callback | () => void | 否 | 回调函数。 |
示例:
InputMethodAbility
下列API示例中都需使用getInputMethodAbility回调获取到InputMethodAbility实例,再通过此实例调用对应方法。
on('inputStart')9+
on(type: 'inputStart', callback: (kbController: KeyboardController, inputClient: InputClient) => void): void
订阅输入法绑定成功事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStart’时表示订阅输入法绑定。 |
callback | (kbController: KeyboardController, inputClient: InputClient) => void | 是 | 回调函数,返回输入法操作相关实例。 |
示例:
off('inputStart')9+
off(type: 'inputStart', callback?: (kbController: KeyboardController, inputClient: InputClient) => void): void
取消订阅输入法绑定成功事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStart’时表示订阅输入法绑定。 |
callback | (kbController: KeyboardController, inputClient: InputClient) => void | 否 | 回调函数,返回输入法操作相关实例。 |
示例:
on('inputStop')9+
on(type: 'inputStop', callback: () => void): void
订阅停止输入法应用事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStop’时表示订阅停止输入法应用事件。 |
callback | () => void | 是 | 回调函数。 |
示例:
off('inputStop')9+
off(type: 'inputStop', callback: () => void): void
取消订阅停止输入法应用事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘inputStop’时表示订阅停止输入法应用事件。 |
callback | () => void | 是 | 回调函数。 |
示例:
on('setCallingWindow')9+
on(type: 'setCallingWindow', callback: (wid: number) => void): void
订阅设置调用窗口事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘setCallingWindow’时表示订阅设置调用窗口事件。 |
callback | (wid: number) => void | 是 | 回调函数,返回调用方window id。 |
示例:
off('setCallingWindow')9+
off(type: 'setCallingWindow', callback: (wid:number) => void): void
取消订阅设置调用窗口事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为‘setCallingWindow’时表示订阅设置调用窗口事件。 |
callback | (wid:number) => void | 是 | 回调函数,返回调用方window id。 |
示例:
on('keyboardShow'|'keyboardHide')9+
on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void
订阅输入法事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyboardShow',表示订阅显示键盘事件。 - type为'keyboardHide',表示订阅隐藏键盘事件。 |
callback | () => void | 是 | 回调函数。 |
示例:
off('keyboardShow'|'keyboardHide')9+
off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void
取消订阅输入法事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyboardShow',表示取消订阅显示键盘事件。 - type为'keyboardHide',表示取消订阅隐藏键盘事件。 |
callback | () => void | 否 | 回调函数。 |
示例:
on('setSubtype')9+
on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void
订阅设置输入法子类型事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'setSubtype',表示订阅输入法子类型的设置事件。 |
callback | (inputMethodSubtype: InputMethodSubtype) => void | 是 | 回调函数,返回设置的输入法子类型。 |
示例:
off('setSubtype')9+
off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void
取消订阅输入法子类型事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'setSubtype',表示取消订阅输入法子类型的设置事件。 |
callback | (inputMethodSubtype: InputMethodSubtype) => void | 否 | 回调函数,返回设置的输入法子类型。 |
示例:
KeyboardDelegate
下列API示例中都需使用getKeyboardDelegate回调获取到KeyboardDelegate实例,再通过此实例调用对应方法。
on('keyDown'|'keyUp')
on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void
订阅硬键盘(即物理键盘)事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyDown',表示订阅硬键盘按下事件。 - type为'keyUp',表示订阅硬键盘抬起事件。 |
callback | (event: KeyEvent) => boolean | 是 | 回调函数,返回按键信息。 |
示例:
off('keyDown'|'keyUp')
off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void
取消订阅硬键盘(即物理键盘)事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 设置监听类型。 - type为'keyDown',表示取消订阅硬键盘按下事件。 - type为'keyUp',表示取消订阅硬键盘抬起事件。 |
callback | (event: KeyEvent) => boolean | 否 | 回调函数,返回按键信息。 |
示例:
on('cursorContextChange')
on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void
订阅光标变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 光标变化事件。 - type为’cursorContextChange‘时,表示订阅光标变化事件。 |
callback | (x: number, y: number, height: number) => void | 是 | 回调函数,返回光标信息。 - x为光标上端的的x坐标值。 - y为光标上端的y坐标值。 - height为光标的高度值。 |
示例:
off('cursorContextChange')
off(type: 'cursorContextChange', callback?: (x: number, y: number, height: number) => void): void
取消订阅光标变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 光标变化事件。 - type为’cursorContextChange‘时,表示光标变化。 |
callback | (x: number, y:number, height:number) => void | 否 | 回调函数,返回光标信息。 - x为光标上端的的x坐标值。 - y为光标上端的y坐标值。 - height为光标的高度值。 |
示例:
on('selectionChange')
on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void
订阅文本选择变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 文本选择变化事件。 - type为’selectionChange‘时,表示选择文本变化。 |
callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | 是 | 回调函数,返回文本选择信息。 - oldBegin为变化之前被选中文本的起始下标。 - oldEnd为变化之前被选中文本的终止下标。 - newBegin为变化之后被选中文本的起始下标。 - newEnd为变化之后被选中文本的终止下标。 |
示例:
off('selectionChange')
off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void
取消订阅文本选择变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 文本选择变化事件。 - type为’selectionChange‘时,表示选择文本变化。 |
callback | (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void | 否 | 回调函数,返回文本选择信息。 - oldBegin为变化之前被选中文本的起始下标。 - oldEnd为变化之前被选中文本的终止下标。 - newBegin为变化之后被选中文本的起始下标。 - newEnd为变化之后被选中文本的终止下标。 |
示例:
on('textChange')
on(type: 'textChange', callback: (text: string) => void): void
订阅文本变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 文本变化事件。 - type为’textChange‘时,表示订阅文本变化事件。 |
callback | (text: string) => void | 是 | 回调函数,返回订阅的文本内容。 |
示例:
off('textChange')
off(type: 'textChange', callback?: (text: string) => void): void
取消订阅文本变化事件。使用callback异步回调。
系统能力: SystemCapability.MiscServices.InputMethodFramework
参数:
参数名 | 类型 | 必填 | 说明 |
type | string | 是 | 文本变化事件。 - type为’textChange‘时,表示取消订阅文本变化事件。 |
callback | (text: string) => void | 否 | 回调函数,返回取消订阅的文本内容。 |
示例: