inputmethod_inputmethod_proxy_capi.h

概述

提供使用输入法的方法，可以向输入法应用发送请求和通知，适用于需要控制输入法显示、隐藏、配置变更通知等功能的应用开发场景。

引用文件： <inputmethod/inputmethod_inputmethod_proxy_capi.h>

库： libohinputmethod.so

系统能力： SystemCapability.MiscServices.InputMethodFramework

起始版本： 12

相关模块： InputMethod

汇总

结构体

函数

函数说明

OH_InputMethodProxy_ShowKeyboard()

InputMethod_ErrorCode OH_InputMethodProxy_ShowKeyboard(InputMethod_InputMethodProxy *inputMethodProxy)

描述

显示键盘。调用此函数后，系统将请求输入法应用弹出软键盘界面，用于文本输入。

使用场景：当应用需要主动拉起键盘以便用户进行文本输入时调用此函数，例如编辑框获得焦点后需要显示键盘的场景。

使用后效果：调用成功后，输入法应用将弹出软键盘界面；调用失败后，返回对应的错误码，需根据错误码进行处理。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。

生命周期管理：inputMethodProxy由OH_InputMethodController_Attach创建输出，不可手动销毁。当调用OH_InputMethodController_Detach解除绑定后，inputMethodProxy将失效，此后再调用此函数将返回IME_ERR_DETACHED错误码。

调用顺序：OH_InputMethodController_Attach → OH_InputMethodProxy_ShowKeyboard → OH_InputMethodProxy_HideKeyboard → OH_InputMethodController_Detach

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象，如需多线程访问请自行加锁保护。

起始版本： 12

参数：

返回：

OH_InputMethodProxy_ShowTextInput()

InputMethod_ErrorCode OH_InputMethodProxy_ShowTextInput(InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_AttachOptions *options)

描述

显示文本输入框。与ShowKeyboard不同，此接口可通过AttachOptions指定请求键盘输入的原因，系统根据原因决定是否弹出键盘。

使用场景：当应用需要在特定场景下（如主动切换输入框、恢复输入等）请求显示文本输入界面时调用此函数，特别适用于需要携带RequestKeyboardReason的场景。

使用后效果：调用成功后，系统将根据options中的RequestKeyboardReason决定是否弹出键盘并激活文本输入；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。options参数需先通过OH_AttachOptions_Create创建。

生命周期管理：inputMethodProxy由OH_InputMethodController_Attach创建输出，不可手动销毁。Detach后失效。options的生命周期由调用者管理，使用完毕后需调用OH_AttachOptions_Destroy销毁。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 15

参数：

返回：

OH_InputMethodProxy_HideKeyboard()

InputMethod_ErrorCode OH_InputMethodProxy_HideKeyboard(InputMethod_InputMethodProxy *inputMethodProxy)

描述

隐藏键盘。调用此函数后，系统将请求输入法应用关闭软键盘界面。

使用场景：当应用需要主动收起键盘时调用此函数，例如编辑框失去焦点、用户完成输入后需要隐藏键盘的场景。

使用后效果：调用成功后，输入法应用将收起软键盘界面；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。

生命周期管理：inputMethodProxy由OH_InputMethodController_Attach创建输出，不可手动销毁。Detach后失效，再调用此函数将返回IME_ERR_DETACHED。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 12

参数：

返回：

OH_InputMethodProxy_NotifySelectionChange()

InputMethod_ErrorCode OH_InputMethodProxy_NotifySelectionChange(InputMethod_InputMethodProxy *inputMethodProxy, char16_t text[], size_t length, int start, int end)

描述

通知文本框选区变化。当输入框内文本内容、光标位置或选中文本发生变化时，通过此接口将变更信息通知给输入法应用，使输入法能够感知编辑框的文本状态。

使用场景：当编辑框中的文本内容被修改、光标位置发生移动、或用户选中文本发生变化时调用此函数，确保输入法应用与编辑框的文本状态保持同步。

使用后效果：调用成功后，输入法应用将接收到选区变更信息，并据此更新输入法内部状态（如候选词、联想等）；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。

生命周期管理：inputMethodProxy由OH_InputMethodController_Attach创建输出，不可手动销毁。Detach后失效。

内存管理：text参数为输入指针，由调用者分配内存，函数内部仅读取该数据，不会修改或释放。调用者负责text数组内存的生命周期管理。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 12

参数：

返回：

OH_InputMethodProxy_NotifyConfigurationChange()

InputMethod_ErrorCode OH_InputMethodProxy_NotifyConfigurationChange(InputMethod_InputMethodProxy *inputMethodProxy,InputMethod_EnterKeyType enterKey, InputMethod_TextInputType textType)

描述

通知输入框配置变化。当编辑框的回车键类型或输入类型发生变化时，通过此接口将新的配置信息通知给输入法应用，使输入法能够调整键盘布局和输入行为。

使用场景：当编辑框的输入类型（如从文本模式切换为数字模式）或回车键类型（如从"完成"切换为"搜索"）发生变化时调用此函数。

使用后效果：调用成功后，输入法应用将根据新的配置调整键盘布局和回车键显示；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。

生命周期管理：inputMethodProxy由OH_InputMethodController_Attach创建输出，不可手动销毁。Detach后失效。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 12

参数：

返回：

OH_InputMethodProxy_NotifyCursorUpdate()

InputMethod_ErrorCode OH_InputMethodProxy_NotifyCursorUpdate(InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_CursorInfo *cursorInfo)

描述

通知光标位置变化。当编辑框中光标位置发生变化时，通过此接口将新的光标信息通知给输入法应用，使输入法能够根据光标位置调整候选词窗口的显示位置。

使用场景：当编辑框中光标位置发生移动时调用此函数，例如用户点击编辑框中不同位置、代码主动移动光标等场景。

使用后效果：调用成功后，输入法应用将接收到新的光标信息，并据此调整候选词窗口的定位；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例。cursorInfo需先通过OH_CursorInfo_Create创建并设置相关属性。

生命周期管理：inputMethodProxy由Attach创建输出，不可手动销毁，Detach后失效。cursorInfo的生命周期由调用者管理，使用完毕后需调用OH_CursorInfo_Destroy销毁。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 12

参数：

返回：

OH_InputMethodProxy_SendPrivateCommand()

InputMethod_ErrorCode OH_InputMethodProxy_SendPrivateCommand(InputMethod_InputMethodProxy *inputMethodProxy, InputMethod_PrivateCommand *privateCommand[], size_t size)

描述

发送私有数据命令。应用通过此接口向输入法应用发送自定义的私有命令数据，用于实现应用与输入法之间的私有通信协议。

使用场景：当应用需要向输入法应用传递自定义的私有数据（如业务特定的指令、配置参数等）时调用此函数，适用于应用与输入法之间有私有通信协议的场景。

使用后效果：调用成功后，输入法应用将通过OH_TextEditorProxy_ReceivePrivateCommandFunc回调接收到私有命令数据；调用失败后，返回对应的错误码。

前置条件：必须先调用OH_InputMethodController_Attach获取inputMethodProxy实例，且当前处于已绑定（Attached）状态。

生命周期管理：inputMethodProxy由Attach创建输出，不可手动销毁，Detach后失效。privateCommand数组中每个元素的生命周期由调用者管理，使用完毕后需调用OH_PrivateCommand_Destroy逐个销毁。

性能建议：privateCommand数组最多包含5个命令对象（size最大为5），超出此限制将返回IME_ERR_PARAMCHECK。单个命令对象最大大小为32KB，超出限制可能导致数据传输失败。

线程安全：此函数非线程安全，不建议在多线程环境下同时操作同一个inputMethodProxy对象。

起始版本： 12

参数：

返回：