@ohos.InputMethodExtensionAbility (InputMethodExtensionAbility)

约束限制

为保障系统安全性和稳定性，防止InputMethodExtensionAbility滥用系统资源，系统对其能力进行管控，不支持部分模块的引用，详情请参考附录。

另外输入法应用区分基础模式和完整体验模式，关于基础模式和完整体验模式说明如下：

基础模式介绍：

基础模式下，输入法扩展（InputMethodExtensionAbility）进程无法拉起其他UIAbility或ExtensionAbility。

基础模式下，输入法扩展会受到系统管控，不能使用涉及访问或泄露用户个人数据的各种接口，同时无法将数据传递出进程。管控功能包括但不限于：网络、短信、电话、麦克风、定位、相机、蓝牙、壁纸、支付、日历、游戏、扬声器、Wi-Fi、剪贴板、多媒体、联系人、公共事件、系统账号、健康数据、地图服务、推送服务、融合搜索、共享内存、分布式特性、广告设备标识、振动等。

基础模式下，输入法扩展可以使用基础输入功能必要的系统能力，例如，IME Kit、ArkUI、窗口、图形、屏幕管理等。

基础模式下，输入法扩展对共享沙箱只读，对输入法扩展独立沙箱可读写；应用主入口可以对共享沙箱及其独立沙箱读写。

完整体验模式介绍：

完整体验模式下，输入法扩展不受基础模式相关限制，例如可以拉起其他UIAbility或ExtensionAbility、可以调用访问用户数据的接口等。

完整体验模式下，输入法扩展可以对共享沙箱读写。

导入模块

import { InputMethodExtensionAbility } from '@kit.IMEKit';

InputMethodExtensionAbility

输入法ExtensionAbility类，提供了输入法应用的核心能力，支持开发者创建输入法应用。

下列API均需通过继承InputMethodExtensionAbility创建子类后，在子类中重写或使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.MiscServices.InputMethodFramework

context参数使用建议：

• 含义/功能：提供InputMethodExtensionContext上下文对象，用于执行输入法应用上下文级操作，包括销毁自身（destroy()）和拉起其他应用（startAbility()）。
• 使用场景：当输入法应用需要主动终止自身运行或拉起目标应用时使用context属性。context在onCreate回调触发后即可使用。
• 使用后效果：通过context.destroy()可销毁当前ExtensionAbility；通过context.startAbility(want)可拉起目标应用。
• 前提条件：context由系统在创建InputMethodExtensionAbility实例时自动赋值，开发者无需手动创建。context仅在ExtensionAbility生命周期内有效，onDestroy回调执行后context将不可用。
• 相关接口间的配合/制约关系：context需配合@ohos.inputMethodEngine模块使用——在onCreate回调中，context作为InputMethodAbility.createPanel()的参数传入，用于创建输入法面板。

onCreate

onCreate(want: Want): void

生命周期回调，在拉起输入法Extension时调用，用于初始化输入法应用。

• 含义/功能：系统拉起输入法ExtensionAbility时触发的初始化回调。开发者在该回调中完成输入法应用的所有关键初始化工作，包括获取核心能力对象、创建输入法面板、订阅事件等。
• 使用场景：当系统根据module.json5配置拉起输入法ExtensionAbility时自动触发。这是输入法应用初始化的唯一入口，所有关键对象的获取和面板创建必须在此回调中完成。
• 使用后效果：回调执行完成后，输入法应用进入正常运行状态。系统将随后触发键盘显示/隐藏请求、客户端绑定等事件，输入法应用需在此之前完成初始化（如已订阅on('inputStart')事件、已创建面板等），否则后续事件可能无法正常响应。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.MiscServices.InputMethodFramework

参数：

want参数使用建议：

• 含义/功能：系统传递给onCreate回调的Want信息，描述当前ExtensionAbility的启动信息。
• 使用场景：开发者可通过want获取启动参数（如abilityName、bundleName等），用于判断启动场景或获取配置参数。
• 取值范围：Want对象包含多种类型的属性，常见属性如abilityName、bundleName等为string类型。want中包含的abilityName和bundleName与module.json5中配置的值一致。
• 注意事项：want参数由系统自动传入，开发者无需手动构造。

注意事项：

• 前提条件：onCreate是输入法应用初始化的核心入口。必须在onCreate中完成以下关键初始化工作：
  1. 通过inputMethodEngine.getInputMethodAbility()获取InputMethodAbility实例。
  2. 通过inputMethodEngine.getKeyboardDelegate()获取KeyboardDelegate实例。
  3. 订阅on('inputStart')事件以接收编辑框绑定通知。
  4. 创建输入法面板（InputMethodAbility.createPanel(this.context, panelInfo)），注意this.context参数必须传入。
  5. 订阅其他必要事件（如on('keyboardShow')、on('setSubtype')等）。
• 开发建议：建议将面板创建和事件订阅集中放在onCreate中完成，避免在其他时机初始化导致事件遗漏或面板创建失败。

相关接口间的配合/制约关系：onCreate需配合以下接口使用：

• inputMethodEngine.getInputMethodAbility()：获取输入法能力对象。
• inputMethodEngine.getKeyboardDelegate()：获取键盘代理对象。
• InputMethodAbility.createPanel(this.context, panelInfo)：创建面板时必须使用onCreate中可获取的this.context作为参数。
• InputMethodAbility.on('inputStart')：必须在onCreate中订阅，否则后续编辑框绑定事件无法接收。

示例：

import { InputMethodExtensionAbility, inputMethodEngine } from '@kit.IMEKit';
import { Want } from '@kit.AbilityKit';

class InputMethodExt extends InputMethodExtensionAbility {
  onCreate(want: Want): void {
    console.info(`onCreate, want: ${want.abilityName}`);

    // 获取输入法能力对象
    let ability: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();

    // 获取键盘代理对象
    let keyboardDelegate: inputMethodEngine.KeyboardDelegate = inputMethodEngine.getKeyboardDelegate();

    // 创建面板
    let panelInfo: inputMethodEngine.PanelInfo = {
      type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
      flag: inputMethodEngine.PanelFlag.FLG_FIXED
    };
    ability.createPanel(this.context, panelInfo, (err, panel) => {
      if (err) {
        console.error(`Failed to create panel: ${err.code}`);
        return;
      }
      console.info('Succeeded in creating panel.');
    });

    // 订阅输入法绑定事件
    ability.on('inputStart', (kbController, inputClient) => {
      console.info('Input method bound to client.');
    });
  }
}

onDestroy

onDestroy(): void

生命周期回调，在销毁输入法应用时调用，用于资源清理。

• 含义/功能：系统销毁输入法ExtensionAbility时触发的清理回调。开发者在该回调中释放面板、取消事件订阅等资源清理工作。
• 使用场景：当系统主动销毁输入法ExtensionAbility（如系统回收资源、用户切换到其他输入法）或开发者主动调用context.destroy()触发销毁时自动触发。注意：onDestroy回调执行后，context将不可用，不应在回调中或回调后继续使用context对象。
• 使用后效果：回调执行完成后，输入法ExtensionAbility进程终止，所有资源应已释放。调用后再进行其他操作将不起效。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.MiscServices.InputMethodFramework

注意事项：

• 开发建议：建议在onDestroy中完成以下清理工作：
  1. 销毁已创建的面板（InputMethodAbility.destroyPanel(panel)）。
  2. 取消所有事件订阅（InputMethodAbility.off('inputStart')等）。
  3. 释放其他应用资源（如缓存数据、定时器等）。
• 开发建议：未在onDestroy中正确销毁面板可能导致面板资源泄漏，影响系统资源使用。

相关接口间的配合/制约关系：onDestroy需配合以下接口使用：

• InputMethodAbility.destroyPanel(panel)：销毁在onCreate中创建的面板，必须与createPanel配对调用。
• InputMethodAbility.off('inputStart')等：取消在onCreate中订阅的事件。
• context.destroy()：开发者主动调用context.destroy()会触发系统执行onDestroy回调。

示例：

import { InputMethodExtensionAbility } from '@kit.IMEKit';

class InputMethodExt extends InputMethodExtensionAbility {
  onDestroy(): void {
    // 销毁面板、取消事件订阅等清理工作
    console.info('onDestroy');
  }
}

附录

InputMethodExtensionAbility不支持以下模块的引用。