一、背景说明

随着 HarmonyOS 7 AI 先锋版发布、鸿蒙装机量突破 1 亿(API 26 设备占比超 82%),输入法作为 AI 交互的第一入口,第三方输入法应用的需求持续升温。HarmonyOS 的 IME Kit(输入法开发服务)提供了输入法应用开发所需的完整框架:应用只需继承 InputMethodExtensionAbility 并通过 @ohos.inputMethodEngine 操作编辑框,即可实现一个可用的软键盘。本文完整实现"Extension 生命周期 → 键盘面板创建 → 按键输入文本 → 回删与收起"的最小可用输入法,代码基于 API 9 及以上(含 26.0.x)。

二、技术原理

输入法应用由三部分协作:

  1. InputMethodExtensionAbility:输入法应用入口,系统在编辑框获取焦点时拉起,onCreate 中完成全部初始化(获取能力对象、订阅事件、创建面板),onDestroy 中清理;
  2. InputMethodAbility:输入法能力对象,由 inputMethodEngine.getInputMethodAbility() 获取。on('inputStart') 在编辑框绑定(键盘需要弹出)时回调,并返回 KeyboardController(控制键盘显隐)与 InputClient(操作编辑框:insertText、deleteForward、moveCursor 等);
  3. 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() 收起面板。

五、技术要点
  1. onCreate 是唯一初始化入口:getInputMethodAbility、createPanel、on(‘inputStart’) 必须集中在 onCreate 中完成,过晚初始化会导致 inputStart 事件丢失、键盘无法弹出;
  2. createPanel 必须传 this.context:这是 InputMethodExtensionAbility 的上下文,传入其他 context 会导致面板归属错误;
  3. panel.setUiContent 加载的是应用内页面:键盘 UI 就是一个普通 ArkUI 页面,可通过状态驱动重绘候选词栏;Panel 还支持 FLG_FLOATING 悬浮态与沉浸模式;
  4. 生命周期配对:inputStop 后调用 destroyPanel 释放面板,Extension 销毁时不要再访问已 destroy 的 Panel;
  5. 调试方法:系统设置中启用该输入法后,在任意输入框唤出;修改键盘页面后需在"系统设置 > 应用 > 输入法"中重新启用才会重新加载页面。
六、扩展建议

在此骨架上扩展即得完整输入法: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

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐