鸿蒙操作系统使用 IME Kit 开发自定义输入法应用实战(本文已在AtomGit仓库开源)
一、背景说明
随着 HarmonyOS 7 AI 先锋版发布、鸿蒙装机量突破 1 亿(API 26 设备占比超 82%),输入法作为 AI 交互的第一入口,第三方输入法应用的需求持续升温。HarmonyOS 的 IME Kit(输入法开发服务)提供了输入法应用开发所需的完整框架:应用只需继承 InputMethodExtensionAbility 并通过 @ohos.inputMethodEngine 操作编辑框,即可实现一个可用的软键盘。本文完整实现"Extension 生命周期 → 键盘面板创建 → 按键输入文本 → 回删与收起"的最小可用输入法,代码基于 API 9 及以上(含 26.0.x)。
二、技术原理
输入法应用由三部分协作:
- InputMethodExtensionAbility:输入法应用入口,系统在编辑框获取焦点时拉起,onCreate 中完成全部初始化(获取能力对象、订阅事件、创建面板),onDestroy 中清理;
- InputMethodAbility:输入法能力对象,由
inputMethodEngine.getInputMethodAbility()获取。on('inputStart')在编辑框绑定(键盘需要弹出)时回调,并返回KeyboardController(控制键盘显隐)与InputClient(操作编辑框:insertText、deleteForward、moveCursor 等); - Panel 面板:软键盘的可视部分,
createPanel(context, panelInfo)创建,setUiContent('pages/KeyboardPage')加载一个普通 ArkUI 页面作为键盘 UI,show()/hide()控制显隐。
数据流为:编辑框获焦 → 系统拉起 Extension(onCreate)→ inputStart 回调拿到 InputClient → 面板 show → 用户点按键 → 调 InputClient.insertText 上屏 → inputStop 后销毁面板。
三、实现步骤
1. module.json5 注册 ExtensionAbility(entry/src/main/module.json5 的 module 节点内):
{
"module": {
"extensionAbilities": [
{
"name": "InputMethodService",
"srcEntry": "./ets/inputmethod/InputMethodService.ets",
"type": "inputMethod",
"metadata": [
{
"name": "ohos.extension.input_method",
"resource": "$profile:input_method_config"
}
]
}
]
}
}
2. 配置输入法属性 entry/src/main/resources/base/profile/input_method_config.json:
{
"settingsAbility": "EntryAbility",
"supportedLanguages": ["zh_CN", "en_US"]
}
3. 输入法服务类 entry/src/main/ets/inputmethod/InputMethodService.ets:
import { InputMethodExtensionAbility } from '@kit.InputMethodKit';
import { inputMethodEngine } from '@kit.InputMethodKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG: string = 'InputMethodService';
export default class InputMethodService extends InputMethodExtensionAbility {
private panel: inputMethodEngine.Panel | null = null;
private inputClient: inputMethodEngine.InputClient | null = null;
private kbController: inputMethodEngine.KeyboardController | null = null;
onCreate(want: import('@kit.AbilityKit').Want): void {
hilog.info(TAG, 'onCreate');
const imeAbility = inputMethodEngine.getInputMethodAbility();
// 编辑框绑定(键盘需要弹出)时回调
imeAbility.on('inputStart', (kbController: inputMethodEngine.KeyboardController,
inputClient: inputMethodEngine.InputClient) => {
this.kbController = kbController;
this.inputClient = inputClient;
hilog.info(TAG, 'inputStart');
});
imeAbility.on('inputStop', () => {
if (this.panel) {
imeAbility.destroyPanel(this.panel);
this.panel = null;
}
});
// 创建软键盘面板并加载键盘页面
const panelInfo: inputMethodEngine.PanelInfo = {
type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
flag: inputMethodEngine.PanelFlag.FLG_FIXED
};
this.panel = imeAbility.createPanel(this.context, panelInfo);
this.panel.setUiContent('pages/KeyboardPage');
this.panel.show();
}
onDestroy(): void {
hilog.info(TAG, 'onDestroy');
}
}
4. 键盘页面 entry/src/main/ets/pages/KeyboardPage.ets(完整代码):
import { inputMethodEngine } from '@kit.InputMethodKit';
import { common } from '@kit.AbilityKit';
@Entry
@Component
struct KeyboardPage {
// 通过扩展上下文拿 InputClient 的间接引用:用应用级存储桥接
private getKeys(): string[] {
return ['q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p'];
}
// 按键上屏:拿到 InputClient 后插文本
private insert(keyValue: string): void {
const ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
// InputClient 由 inputStart 回调分发,此处通过全局桥接对象获取
const client = (ctx as unknown as Record<string, object>)['__ime_client__']
as inputMethodEngine.InputClient | undefined;
if (client) {
client.insertText(keyValue);
}
}
build() {
Column({ space: 8 }) {
ForEach([0, 1], (row: number) => {
Row({ space: 6 }) {
ForEach(this.getKeys().slice(row * 5, row * 5 + 5), (key: string) => {
Button(key.toUpperCase())
.width(62).height(46)
.onClick(() => { this.insert(key); })
}, (key: string) => key)
}
}, (row: number) => row.toString())
Row({ space: 6 }) {
Button('空格').width(120).height(46)
.onClick(() => { this.insert(' '); })
Button('删除').width(80).height(46)
.onClick(() => { this.deleteOne(); })
Button('收起').width(80).height(46)
.onClick(() => { this.hideKeyboard(); })
}
}
.width('100%')
.padding(10)
.backgroundColor('#ECEFF1')
}
private deleteOne(): void {
const ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
const client = (ctx as unknown as Record<string, object>)['__ime_client__']
as inputMethodEngine.InputClient | undefined;
if (client) {
client.deleteForward(1);
}
}
private hideKeyboard(): void {
const ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
const ctrl = (ctx as unknown as Record<string, object>)['__ime_ctrl__']
as inputMethodEngine.KeyboardController | undefined;
if (ctrl) {
ctrl.hide();
}
}
}
5. 把回调对象分发给页面(在 InputMethodService.ets 的 inputStart 回调中追加):
imeAbility.on('inputStart', (kbController: inputMethodEngine.KeyboardController,
inputClient: inputMethodEngine.InputClient) => {
this.kbController = kbController;
this.inputClient = inputClient;
// 面板页面与 Extension 不共享组件实例,通过 context 挂载桥接
(this.context as unknown as Record<string, object>)['__ime_client__'] = inputClient;
(this.context as unknown as Record<string, object>)['__ime_ctrl__'] = kbController;
});
工程完整结构见文末「代码仓库」。
四、应用场景示例
模拟一次真实输入:在任意应用的输入框点击唤出该输入法,按 q、w、三个键后再按"空格",编辑框中即出现"qw ";按"删除"调 deleteForward(1) 逐字符回删;按"收起"调 KeyboardController.hide() 收起面板。
五、技术要点
- onCreate 是唯一初始化入口:getInputMethodAbility、createPanel、on(‘inputStart’) 必须集中在 onCreate 中完成,过晚初始化会导致 inputStart 事件丢失、键盘无法弹出;
- createPanel 必须传 this.context:这是 InputMethodExtensionAbility 的上下文,传入其他 context 会导致面板归属错误;
- panel.setUiContent 加载的是应用内页面:键盘 UI 就是一个普通 ArkUI 页面,可通过状态驱动重绘候选词栏;Panel 还支持 FLG_FLOATING 悬浮态与沉浸模式;
- 生命周期配对:inputStop 后调用 destroyPanel 释放面板,Extension 销毁时不要再访问已 destroy 的 Panel;
- 调试方法:系统设置中启用该输入法后,在任意输入框唤出;修改键盘页面后需在"系统设置 > 应用 > 输入法"中重新启用才会重新加载页面。
六、扩展建议
在此骨架上扩展即得完整输入法:KeyboardDelegate 的 on('keyDown') 处理物理键盘;拼音候选词可结合本地词库 + AI 模型做智能联想(HarmonyOS 7 AI 先锋版的端侧 AI 交互正是沿着这条链路演进);隐私面板、预上屏(setPreviewText)、与编辑框应用的自定义消息(recvMessage)等高级能力均可按需叠加。
结语
本文用约 150 行 ArkTS 实现了一个最小可用的鸿蒙软键盘:Extension 生命周期管理、面板创建与页面加载、InputClient 的插入/回删、KeyboardController 的收起控制。理解"onCreate 集中初始化 + inputStart 分发客户端"这一框架约定后,距离一个 AI 联想输入法只差词库与界面打磨。
代码仓库
本文完整示例工程已在 AtomGit 开源,为标准鸿蒙 Stage 工程(AppScope 应用配置、entry 模块、InputMethodExtensionAbility 注册、hvigor 构建脚本齐全),DevEco Studio 可直接打开编译运行:https://atomgit.com/NJPJI_Yang/hm-article-2026-11-22-ime-kit-ime-kit-atomgit
更多推荐




所有评论(0)