鸿蒙与Rust(17)——IME Kit(输入法开发服务)

在 HarmonyOS（鸿蒙系统）的应用开发中，如果开发者使用的是 ArkUI 提供的标准组件（如 TextInput、TextArea），系统会自动处理软键盘的弹出、文本的输入与删除。然而，在游戏开发（如  Unity、Cocos 引擎）或自绘 UI 框架（基于 OpenGL/Vulkan/Skia  自定义渲染）的场景下，开发者并没有使用系统的标准输入组件，而是自己在屏幕上画出了一个“输入框”。此时，如何唤起软键盘？如何接收软键盘输入的字符？这就需要用到  HarmonyOS 提供的 IME Kit（输入法开发服务） NDK 接口，其核心支撑正是 libohinputmethod.so 动态库。

什么是 IME Kit？

IME Kit（Input Method Editor Kit） 是 HarmonyOS 提供的输入法应用与各类输入终端（如应用文本框）之间进行交互的桥梁。

在 C/C++ 原生开发（NDK）层面，IME Kit 的能力被封装在 libohinputmethod.so 中。通过它，Native 应用可以实现：

1. 主动控制：绑定输入法、显示/隐藏软键盘。
2. 被动监听：接收用户在软键盘上输入的文本（Insert）、删除操作（Delete）、以及键盘状态（弹出/收起）的变化。

开发环境准备

要在 C/C++ 项目中使用 IME Kit，需要进行以下配置：

1. 引入头文件在需要处理输入的 C/C++ 源码中引入 IME Kit 的 NDK 头文件：

#include <inputmethod/inputmethod_controller_capi.h>#include <inputmethod/inputmethod_types_capi.h>

2. 配置 CMakeLists.txt在项目的 CMake 构建脚本中，将 libohinputmethod.so 链接到你的目标库中：

target_link_libraries(your_native_module PUBLIC    libohinputmethod.so    # 其他可能用到的库，例如日志库    libhilog_ndk.z.so)

NDK 自绘编辑框接入输入法核心流程

在自绘引擎中接入软键盘，核心流程分为四个步骤：初始化监听、绑定输入法、显示软键盘、处理输入内容并解绑。

步骤 1：创建控制器与注册回调

输入法与应用之间是异步交互的。我们需要注册一系列回调函数，告诉系统：“当软键盘输入字符或删除字符时，请调用这些 C 函数”。

// 1. 定义文本输入回调void OnInsertText(const char* text, void* userData){// text 即为软键盘输入的字符串（UTF-8）// TODO: 将 text 追加到你自绘引擎的字符串中，并触发重新渲染OH_LOG_INFO(LOG_APP, "Insert Text: %{public}s", text);}// 2. 定义删除文本回调void OnDeleteBackward(int32_t length, void* userData){// length 为需要删除的字符长度// TODO: 从你自绘引擎的字符串中删除对应长度的字符，并重新渲染OH_LOG_INFO(LOG_APP, "Delete Length: %{public}d", length);}// 3. 定义键盘状态回调（可选）void OnKeyboardStatus(InputMethod_KeyboardStatus status, void* userData){if (status == IME_KEYBOARD_STATUS_SHOW) {// 键盘弹起，可能需要上移你的 UI 以免被遮挡    } else if (status == IME_KEYBOARD_STATUS_HIDE) {// 键盘收起    }}// 4. 将回调封装到 TextEditorProxyInputMethod_TextEditorProxy* textEditorProxy = OH_TextEditorProxy_Create();OH_TextEditorProxy_SetInsertTextFunc(textEditorProxy, OnInsertText);OH_TextEditorProxy_SetDeleteBackwardFunc(textEditorProxy, OnDeleteBackward);

步骤 2：绑定输入法 (Attach)

当用户点击了你自绘的“假输入框”时，你需要告诉系统：“我现在需要使用输入法了”。这就叫 Attach。

// 获取输入法控制器单例InputMethod_Controller* controller = OH_InputMethodController_Create();// 配置输入法选项（例如：这是普通文本，还是密码框，还是数字键盘）InputMethod_AttachOptions* options = OH_AttachOptions_Create();OH_AttachOptions_SetEnterKeyType(options, IME_ENTER_KEY_GO); // 设置回车键为"前往"OH_AttachOptions_SetTextInputType(options, IME_TEXT_INPUT_TYPE_TEXT); // 普通文本// 发起绑定int32_t ret = OH_InputMethodController_Attach(controller, textEditorProxy, options);if (ret == IME_ERR_OK) {OH_LOG_INFO(LOG_APP, "Attach IME Success");}

步骤 3：唤起软键盘 (Show)

Attach 成功后，软键盘并不会立刻弹出来，需要显式调用显示接口：

// 显示软键盘OH_InputMethodController_ShowTextInput(controller);

此时，屏幕下方会弹出鸿蒙系统的默认软键盘。用户敲击键盘时，系统就会触发你在步骤 1中注册的 OnInsertText 等回调。

步骤 4：隐藏键盘与解绑 (Detach)

当用户点击输入完成，或者点击屏幕空白处（焦点离开自绘输入框）时，应当收起软键盘并解除绑定释放资源。

// 隐藏软键盘OH_InputMethodController_HideTextInput(controller);// 解除绑定OH_InputMethodController_Detach(controller);// 释放不再使用的资源OH_AttachOptions_Destroy(options);OH_TextEditorProxy_Destroy(textEditorProxy);

开发避坑与最佳实践

1. 光标管理由自己负责：使用 IME Kit 的 C API，意味着你完全脱离了系统的排版引擎。输入法只负责给你发字符串（InsertText）和指令（DeleteBackward）。光标的闪烁、文本的换行、文字在屏幕上的测算与绘制，全部需要你的 C/C++ 渲染引擎自行实现。
2. UI 避让（Keyboard Avoidance）：软键盘弹起会遮挡屏幕下半部分。你需要监听键盘状态回调，并获取键盘高度（可通过窗口 API 配合），动态调整你自绘画布（Surface）或 Camera 的视口，确保输入框不被遮挡。
3. 内存管理：以 OH_XXX_Create 创建的结构体，在不使用时务必调用对应的 OH_XXX_Destroy 销毁，避免 Native 层内存泄漏。
4. ArkUI_Node 场景的抉择：如果你在 NDK 中使用的是 ArkUI_Node（Native UI 框架）创建了系统标准的 TextInput 节点，那么不需要直接调用 libohinputmethod.so，ArkUI 底层会自动处理输入法交互。 IME Kit C API 仅针对纯自绘（如 OpenGL/Skia）的场景。

总结

libohinputmethod.so 提供的 IME Kit C API，为鸿蒙生态中的游戏引擎和跨平台自绘 UI 框架补齐了至关重要的文本输入能力。通过 Attach 建立连接，通过 Proxy 接收输入，开发者可以在完全掌控渲染流程的同时，完美融入鸿蒙系统的输入法生态。

参考资料

• HarmonyOS指南>应用框架>IME Kit（输入法开发服务）>IME Kit简介 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ime-kit-intro
• HarmonyOS指南>应用框架>IME  Kit（输入法开发服务）>在自绘编辑框中使用输入法开发指导 (C/C++)  https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/use-inputmethod-in-custom-edit-box-ndk
• HarmonyOS  API参考>应用框架>IME Kit（输入法开发服务）>ArkTS API  https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ime-arkts
• HarmonyOS API参考>应用框架>IME Kit（输入法开发服务）>C API https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ime-c