创建输入法

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

如需向 Android 系统添加 IME,请创建一个包含扩展 InputMethodService 的类的 Android 应用。 此外,您通常还需要创建一个“设置”activity,用于向 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

IME 专用的类位于 android.inputmethodserviceandroid.view.inputmethod 软件包中。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;
}

在此示例中,MyKeyboardViewKeyboardView 的自定义实现的实例,它会呈现 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
TYPE_CLASS_TEXT 的变体,用于输入网址和其他统一资源标识符 (URI)。
TYPE_TEXT_FLAG_AUTO_COMPLETE
TYPE_CLASS_TEXT 的变体,用于输入应用从字典、搜索或其他工具中自动填充的文本。

在测试这些变体时,请使用适当的常量遮盖 inputTypeInputType 的参考文档中列出了可用的遮盖常量。

向应用发送文本

当用户使用您的 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 键盘布局

模式可以是任何文本,例如“键盘”或“语音”。子类型也可以公开这些模式的组合。

子类型信息用于通知栏中提供的 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 子类型

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

显示语言选择菜单的图片
图 5. 语言系统菜单

在 IME 子类型之间切换

您可以通过提供切换键(例如键盘上的球形语言图标)让用户轻松地在 IME 子类型之间切换。这可以提高键盘的易用性,并为用户带来方便。如需启用此切换功能,请执行以下步骤:

  1. 在输入法的 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">
    
  2. 调用 shouldOfferSwitchingToNextInputMethod() 方法。
  3. 如果该方法返回 true,则显示一个切换键。
  4. 当用户点按该切换键时,调用 switchToNextInputMethod() 并传递 false。false 值会告知系统对所有子类型都平等对待,无论它们属于哪种 IME。指定 true 会要求系统循环切换当前 IME 中的子类型。

IME 一般注意事项

在实现 IME 时,还需要考虑以下事项:

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