此页面由 Cloud Translation API 翻译。

创建输入法

输入法 (IME) 是一种可让用户输入文本的用户控件。Android 提供了一种可扩展的输入法框架。借助该框架，应用可以为用户提供备选输入法，例如屏幕键盘或语音输入。安装 IME 后，用户可以从系统设置中选择一个 IME，并在整个系统中使用该 IME。一次只能启用一个 IME。

如需向 Android 系统添加 IME，请创建一个包含扩展 InputMethodService 的类的 Android 应用。此外，您通常需要创建一个“设置”activity，以向 IME 服务传递选项。您还可以定义一个设置界面，使其作为系统设置的一部分显示。

本页将介绍以下主题：

IME 生命周期
在应用清单中声明 IME 组件
IME API
设计 IME 界面
将文本从 IME 发送到应用
使用 IME 子类型
其他 IME 注意事项

如果您以前没有处理过 IME，请先阅读入门文章屏幕输入法。

IME 生命周期

下图描述了 IME 的生命周期：

一张图片，显示了 IME 的生命周期。 — **图 1.** IME 的生命周期。

以下各部分介绍了如何实现与遵循此生命周期的 IME 相关联的界面和代码。

在清单中声明 IME 组件

在 Android 系统中，IME 是包含一项特殊 IME 服务的 Android 应用。应用的清单文件必须声明该服务，请求必需的权限，提供一个与操作 action.view.InputMethod 匹配的 intent 过滤器，并提供定义 IME 特征的元数据。此外，要提供可让用户修改 IME 行为的设置界面，您可以定义一个可通过“系统设置”启动的“设置”activity。

以下代码段声明了一项 IME 服务。它请求了 BIND_INPUT_METHOD 权限以让该服务可以将 IME 连接到系统，设置了一个与 android.view.InputMethod 操作匹配的 intent 过滤器，并定义了 IME 的元数据：

<!-- Declares the input method service. -->
<service android:name="FastInputIME"
    android:label="@string/fast_input_label"
    android:permission="android.permission.BIND_INPUT_METHOD">
    <intent-filter>
        <action android:name="android.view.InputMethod" />
    </intent-filter>
    <meta-data android:name="android.view.im"
               android:resource="@xml/method" />
</service>

下面的代码段声明了 IME 的设置 activity。它有一个适用于 ACTION_MAIN 的 intent 过滤器，指示该 activity 是 IME 应用的主入口点：

<!-- Optional: an activity for controlling the IME settings. -->
<activity android:name="FastInputIMESettings"
    android:label="@string/fast_input_settings">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
    </intent-filter>
</activity>

您还可以让用户能够直接从 IME 界面访问 IME 设置。

输入法 API

android.inputmethodservice 和 android.view.inputmethod 软件包中提供了 IME 专用的类。KeyEvent 类对于处理键盘字符非常重要。

IME 的核心部分是一个服务组件，即一个扩展 InputMethodService 的类。除了实现正常的服务生命周期之外，该类还提供具有以下用途的回调：提供 IME 的界面，处理用户输入，以及向处于焦点的字段提供文本。默认情况下，InputMethodService 类提供了用于管理 IME 的状态和可见性以及与当前输入字段进行通信的大部分实现。

以下类也很重要：

BaseInputConnection: 定义从 InputMethod 返回到接收其输入的应用的通信渠道。您可以使用该类读取光标周围的文本，将文本提交至文本框，然后将原始按键事件发送到应用。应用必须扩展此类，而不是实现基接口 InputConnection。
KeyboardView: 用于呈现键盘和响应用户输入事件的 View 的扩展。键盘布局由 Keyboard 的实例指定，您可以在 XML 文件中定义该实例。

设计输入法界面

IME 有两个主要视觉元素：输入视图和候选视图。您只需实现与您要设计的输入法相关的元素。

输入视图

输入视图是用户以点击按键、手写或手势的形式输入文本的界面。当 IME 首次显示时，系统会调用 onCreateInputView() 回调。在此方法的实现中，创建要在 IME 窗口中显示的布局，并将布局返回系统。以下代码段展示了实现 onCreateInputView() 方法的示例：

Kotlin

override fun onCreateInputView(): View {
    return layoutInflater.inflate(R.layout.input, null).apply {
        if (this is MyKeyboardView) {
            setOnKeyboardActionListener(this@MyInputMethod)
            keyboard = latinKeyboard
        }
    }
}

Java

@Override
public View onCreateInputView() {
    MyKeyboardView inputView =
        (MyKeyboardView) getLayoutInflater().inflate(R.layout.input, null);

    inputView.setOnKeyboardActionListener(this);
    inputView.setKeyboard(latinKeyboard);

    return inputView;
}

在此示例中，MyKeyboardView 是 KeyboardView（呈现 Keyboard）的自定义实现的一个实例。

候选视图

候选视图是 IME 显示可能的字词更正或建议供用户选择的界面。在 IME 生命周期中，系统会在准备好显示候选视图时调用 onCreateCandidatesView()。在此方法的实现中，可以返回显示文字建议的布局；如果您不想显示任何内容，可以返回 null。Null 响应是默认行为，因此如果您不提供建议，则无需实现此方法。

界面设计注意事项

本部分介绍了一些 IME 界面设计注意事项。

处理多种屏幕尺寸

IME 的界面必须能够针对不同的屏幕尺寸进行缩放，并且还必须处理横向和纵向屏幕方向。在非全屏 IME 模式下，留出足够的空间供应用显示文本字段和任何关联的上下文，以使 IME 占用不超过一半的屏幕空间。在全屏 IME 模式下，不存在此问题。

处理不同的输入类型

通过 Android 文本字段，您可以设置特定的输入类型，例如自由格式的文本、数字、网址、电子邮件地址以及搜索字符串。实现新的 IME 时，请检测每个字段的输入类型，并为其提供适当的接口。不过，您无需设置 IME 来检查用户针对输入类型输入的文本是否有效。这由拥有文本字段的应用负责。

例如，以下是拉丁语 IME 为 Android 平台文本输入提供的界面：

一张图片，显示拉丁语 IME 上的文本输入 — **图 2.** 拉丁语 IME 文本输入。

以下是拉丁语 IME 为 Android 平台数字输入提供的接口：

显示拉丁语 IME 上数字输入的图片 — **图 3.** 拉丁语 IME 数字输入。

当输入字段获得焦点且 IME 启动时，系统会调用 onStartInputView()，并传入一个 EditorInfo 对象，其中包含有关输入类型的详细信息以及文本字段的其他属性。在该对象中，inputType 字段包含文本字段的输入类型。

inputType 字段是一个包含各种输入类型设置的位模式的 int。如要针对文本字段的输入类型测试该字段，请使用常量 TYPE_MASK_CLASS 遮盖它，如下所示：

Kotlin

inputType and InputType.TYPE_MASK_CLASS

Java

inputType & InputType.TYPE_MASK_CLASS

输入类型位模式可以具有以下值之一：

TYPE_CLASS_NUMBER: 用于输入数字的文本字段。如图 3 所示，拉丁语 IME 会为此类字段显示一个数字键盘。
TYPE_CLASS_DATETIME: 用于输入日期和时间的文本字段。
TYPE_CLASS_PHONE: 用于输入电话号码的文本字段。
TYPE_CLASS_TEXT: 用于输入任何受支持字符的文本字段。

InputType 的参考文档中对这些常量进行了更详细的说明。

inputType 字段可以包含其他位，以指示文本字段类型的变体，例如：

TYPE_TEXT_VARIATION_PASSWORD: 用于输入密码的 TYPE_CLASS_TEXT 的变体。输入法会显示装饰标志，而不是实际文本。
TYPE_TEXT_VARIATION_URI: 用于输入网址以及其他统一资源标识符 (URI) 的 TYPE_CLASS_TEXT 的变体。
TYPE_TEXT_FLAG_AUTO_COMPLETE: TYPE_CLASS_TEXT 的变体，用于输入应用从字典、搜索或其他工具自动补全的文本。

在测试这些变体时，请使用相应的常量遮盖 inputType。InputType 的参考文档中列出了可用的遮盖常量。

向应用发送文本

当用户使用您的 IME 输入文本时，您可以通过发送各个按键事件或修改应用文本字段中光标周围的文本，向应用发送文本。无论是哪种情况，都需要使用 InputConnection 实例来提供文本。如需获取此实例，请调用 InputMethodService.getCurrentInputConnection()。

修改光标周围的文本

处理现有文本的编辑时，BaseInputConnection 中的一些实用方法包括：

getTextBeforeCursor(): 返回 CharSequence，其中包含当前光标位置之前请求数量的字符。
getTextAfterCursor(): 返回 CharSequence，其中包含当前光标位置后面请求数量的字符。
deleteSurroundingText(): 删除当前光标位置前后指定数量的字符。
commitText(): 将 CharSequence 提交到文本字段并设置新的光标位置。

例如，以下代码段展示了如何将光标左侧的四个字符替换为文本“Hello!”：

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.deleteSurroundingText(4, 0)
    ic.commitText("Hello", 1)
    ic.commitText("!", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.deleteSurroundingText(4, 0);
ic.commitText("Hello", 1);
ic.commitText("!", 1);

支持在提交之前编写文本

如果您的 IME 预测文本或需要多个步骤来撰写字形或字词，您可以在文本字段中显示进度，直到用户提交相应字词，然后您就可以将部分组合替换为完成的文本。在将文本传递至 setComposingText() 时，您可以通过向文本添加 span 对其进行特殊处理。

以下代码段演示了如何在文本字段中显示进度：

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.setComposingText("Composi", 1)
    ic.setComposingText("Composin", 1)
    ic.commitText("Composing ", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.setComposingText("Composi", 1);
ic.setComposingText("Composin", 1);
ic.commitText("Composing ", 1);

拦截硬件按键事件

即使输入法窗口未获得明确的焦点，它也会先接收硬件按键事件，并且可以使用这些事件或将其转发到应用。例如，您可能需要使用方向键在界面中导航，以便在组合期间选择候选词。您可能还需要点按返回键，以便关闭来自输入法窗口的任何对话框。

如要拦截硬件按键，请替换 onKeyDown() 和 onKeyUp()。

对您不想自行处理的按键调用 super() 方法。

创建 IME 子类型

借助子类型，IME 可以提供多种受支持的输入模式和语言。子类型可以代表以下内容：

语言区域，例如 en_US 或 fr_FR
输入模式，例如语音输入、键盘输入或手写输入
特定于 IME 的其他输入样式、表单或属性，例如 10 键或 QWERTY 键盘布局

模式可以是任何文本，例如“keyboard”或“voice”。子类型还可以公开这些模式的组合。

子类型信息用于通知栏中提供的 IME 切换器对话框以及 IME 设置。通过此信息，框架还可以直接调出 IME 的特定子类型。在构建 IME 时，请使用子类型工具，因为它可以帮助用户识别不同的 IME 语言和模式并在它们之间切换。

使用 <subtype> 元素在输入法的某个 XML 资源文件中定义子类型。以下代码段定义了一个具有两个子类型的 IME：用于美国英语语言区域的键盘子类型，以及用于法国法语语言区域的另一种键盘子类型：

<input-method xmlns:android="http://schemas.android.com/apk/res/android"
        android:settingsActivity="com.example.softkeyboard.Settings"
        android:icon="@drawable/ime_icon">
    <subtype android:name="@string/display_name_english_keyboard_ime"
            android:icon="@drawable/subtype_icon_english_keyboard_ime"
            android:languageTag="en-US"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="somePrivateOption=true" />
    <subtype android:name="@string/display_name_french_keyboard_ime"
            android:icon="@drawable/subtype_icon_french_keyboard_ime"
            android:languageTag="fr-FR"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="someVariable=30,someInternalOption=false" />
    <subtype android:name="@string/display_name_german_keyboard_ime" ... />
</input-method>

为了确保您的子类型在界面中标记正确，请使用“%s”获取与子类型的语言区域标签相同的子类型标签。以下两个代码段演示了此过程。第一个代码段显示了输入法的 XML 文件的一部分：

<subtype
    android:label="@string/label_subtype_generic"
    android:imeSubtypeLocale="en_US"
    android:icon="@drawable/icon_en_us"
    android:imeSubtypeMode="keyboard" />

第二个代码段是 IME 的 strings.xml 文件的一部分。字符串资源 label_subtype_generic（由输入法界面定义用来设置子类型的标签）定义为：

<string name="label_subtype_generic">%s</string>

此设置可使子类型的显示名称与语言区域设置一致。例如，在任何英语语言区域中，显示名称都是“English (United States)”。

从通知栏中选择 IME 子类型

Android 系统会管理所有 IME 提供的所有子类型。IME 子类型被视为它们所属 IME 的模式。用户可以从通知栏或“设置”应用导航到可用 IME 子类型的菜单，如下图所示：

显示“语言和输入法”菜单的图片 — **图 4.** **语言和输入法**系统菜单。

从系统设置中选择 IME 子类型

用户还可以在系统设置的语言和输入法设置面板中控制子类型的使用方式：

在 IME 子类型之间切换

通过提供切换键（例如键盘上的地球形状的语言图标），您可以让用户在 IME 子类型之间轻松切换。这可以提高键盘的易用性，并且很方便用户。如需启用此切换，请执行以下步骤：

在输入法的 XML 资源文件中声明 supportsSwitchingToNextInputMethod = "true"。您的声明必须类似于以下代码段：

<input-method xmlns:android="http://schemas.android.com/apk/res/android"
        android:settingsActivity="com.example.softkeyboard.Settings"
        android:icon="@drawable/ime_icon"
        android:supportsSwitchingToNextInputMethod="true">

调用 shouldOfferSwitchingToNextInputMethod() 方法。
如果该方法返回 true，则显示一个切换键。
当用户点按该切换键时，调用 switchToNextInputMethod()，并传递 false。False 值会告知系统以同样的方式处理所有子类型，无论它们属于哪种 IME。指定 true 则会要求系统循环切换当前 IME 中的子类型。

IME 一般注意事项

在实现 IME 时，还需要考虑以下事项：

为用户提供一种直接通过 IME 界面设置选项的方式。
由于设备上可能安装了多个 IME，因此请为用户提供一种可以直接从输入法界面切换到其他 IME 的方式。
快速调出 IME 界面。预加载或按需加载任何大型资源，以便用户在点按文本字段后立即看到 IME。缓存输入法后续调用的资源和视图。
在输入法窗口隐藏后立即释放较大的内存分配，以便应用有足够的内存来运行。如果 IME 隐藏了几秒钟，请使用延迟消息来释放资源。
确保对于与 IME 相关联的语言或语言区域，用户可以输入尽可能多的字符。用户可能会在密码或用户名中使用标点符号，因此您的 IME 必须提供多种不同的字符，以允许用户输入密码并访问设备。