键盘设备

使用合集保持井井有条 根据您的偏好设置保存内容并对其进行分类。

Android 支持各种键盘设备，包括特殊功能键盘（音量和电源控件）、紧凑型嵌入式 QWERTY 键盘以及全功能 PC 式外接键盘。

本文档仅介绍物理键盘。有关软键盘（输入法编辑器）的信息，请参阅 Android SDK。

键盘分类

如果满足以下任一条件，则输入设备被归类为键盘：

• 输入设备报告存在键盘上使用的任何 Linux 键代码，包括 0 到 0xff 或 KEY_OK 到 KEY_MAX。

• 输入设备报告存在操纵杆和游戏手柄上使用的任何 Linux 键代码，包括 BTN_0 到 BTN_9、BTN_TRIGGER 到 BTN_DEAD 或 BTN_A 到 BTN_THUMBR。

操纵杆目前被归类为键盘，因为操纵杆和游戏手柄按钮通过 EV_KEY 事件报告，方式与键盘按键的报告方式相同。因此，操纵杆和游戏手柄也使用按键映射文件进行配置。

一旦输入设备被归类为键盘，系统就会为该键盘加载输入设备配置文件和键盘布局。

然后，系统会尝试确定设备的附加特性。

• 如果输入设备有任何键映射到 KEYCODE_Q，则该设备被视为具有字母键盘（而不是数字键盘）。字母键盘功能在资源 Configuration 对象中报告为 KEYBOARD_QWERTY。

• 如果输入设备有任何键映射到 KEYCODE_DPAD_UP、KEYCODE_DPAD_DOWN、KEYCODE_DPAD_LEFT、KEYCODE_DPAD_RIGHT 和 KEYCODE_DPAD_CENTER（所有键都必须存在），则该设备被视为具有方向键键盘。方向键键盘功能在资源 Configuration 对象中报告为 NAVIGATION_DPAD。

• 如果输入设备有任何键映射到 KEYCODE_BUTTON_A 或其他游戏手柄相关按键，则该设备被视为具有游戏手柄。

键盘驱动程序要求

1. 键盘驱动程序应仅注册它们实际支持的按键的键代码。注册过多的键代码可能会混淆设备分类算法，或导致系统错误地检测设备支持的键盘功能。

2. 键盘驱动程序应使用 EV_KEY 报告按键按下事件，使用值 0 表示按键已释放，值 1 表示按键已按下，值大于或等于 2 表示按键正在自动重复。

3. Android 执行自己的键盘重复操作。应在驱动程序中禁用自动重复功能。

4. 键盘驱动程序可以选择通过在按下按键时发送带有 MSC_SCANCODE 的 EV_MSC 和指示用法或扫描代码的值来指示 HID 用法或低级扫描代码。Android 目前不使用此信息。

5. 当 EV_LED 写入设备时，键盘驱动程序应支持设置 LED 状态。hid-input 驱动程序会自动处理此问题。在撰写本文时，Android 使用 LED_CAPSLOCK、LED_SCROLLLOCK 和 LED_NUMLOCK。仅当键盘实际具有关联的指示灯时，才需要支持这些 LED。

6. 用于嵌入式键盘（例如，使用 GPIO 矩阵）的键盘驱动程序应确保为设备进入睡眠状态时仍按下的任何按键发送值为 0 的 EV_KEY 事件。否则，按键可能会卡住，并会永远自动重复。

键盘操作

以下是 Android 上键盘操作的简要概述。

1. EventHub 从 evdev 驱动程序读取原始事件，并使用键盘的按键布局图将 Linux 键代码（有时称为扫描码）映射到 Android 键代码。

2. InputReader 会使用原始事件并更新元键状态。例如，如果按下或释放了左 Shift 键，则读取器将相应地设置或重置 META_SHIFT_LEFT_ON 和 META_SHIFT_ON 位。

3. InputReader 会将按键事件通知给 InputDispatcher。

4. InputDispatcher 通过调用 WindowManagerPolicy.interceptKeyBeforeQueueing 询问 WindowManagerPolicy 如何处理按键事件。此方法是关键路径的一部分，该路径负责在按下某些按键时唤醒设备。EventHub 有效地在此关键路径上保持唤醒锁定，以确保它能够运行完成。

5. 如果当前正在使用 InputFilter，则 InputDispatcher 会为其提供机会来使用或转换按键。InputFilter 可用于实现低级别的全系统辅助功能策略。

6. InputDispatcher 将按键加入队列，以便在调度线程上进行处理。

7. 当 InputDispatcher 将按键从队列中移除时，它会通过调用 WindowManagerPolicy.interceptKeyBeforeDispatching，再次让 WindowManagerPolicy 有机会拦截按键事件。此方法处理系统快捷方式和其他功能。

8. 然后，InputDispatcher 识别按键事件目标（焦点窗口）并等待它们准备就绪。然后，InputDispatcher 将按键事件传递给应用。

9. 在应用内部，按键事件会沿着视图层级结构向下传播到焦点视图，以进行预输入法按键调度。

10. 如果在预输入法调度中未处理按键事件并且正在使用输入法，则按键事件将传递到输入法。

11. 如果输入法未消耗按键事件，则按键事件会沿着视图层级结构向下传播到焦点视图，以进行标准按键调度。

12. 应用会向 InputDispatcher 报告按键事件是否已被消耗。如果事件未被消耗，则 InputDispatcher 调用 WindowManagerPolicy.dispatchUnhandledKey 以应用“回退”行为。根据回退操作，可以使用不同的键代码重新启动按键事件调度周期。例如，如果应用不处理 KEYCODE_ESCAPE，则系统可能会将按键事件重新调度为 KEYCODE_BACK。

键盘配置

键盘行为由键盘的按键布局、按键字符图和输入设备配置决定。

有关参与键盘配置的文件的更多详细信息，请参阅以下部分

• 按键布局文件
• 按键字符映射文件
• 输入设备配置文件

属性

以下输入设备配置属性用于键盘。

keyboard.layout

定义： keyboard.layout = <名称>

指定与输入设备关联的按键布局文件的名称，不包括 .kl 扩展名。如果找不到此文件，输入系统将使用默认按键布局。

名称中的空格在查找期间会转换为下划线。

有关更多详细信息，请参阅按键布局文件文档。

keyboard.characterMap

定义： keyboard.characterMap = <名称>

指定与输入设备关联的按键字符图文件的名称，不包括 .kcm 扩展名。如果找不到此文件，输入系统将使用默认按键字符图。

名称中的空格在查找期间会转换为下划线。

有关更多详细信息，请参阅按键字符图文件文档。

keyboard.orientationAware

定义： keyboard.orientationAware = 0 | 1

指定键盘是否应响应显示屏方向更改。

• 如果值为 1，则当关联的显示屏方向更改时，方向键区按键会旋转。

• 如果值为 0，则键盘不受显示屏方向更改的影响。

默认值为 0。

方向感知用于支持方向键区按键的旋转，例如在 Motorola Droid 上。例如，当设备从其自然方向顺时针旋转 90 度时，KEYCODE_DPAD_UP 将被重新映射以产生 KEYCODE_DPAD_RIGHT，因为当设备以此方向握持时，“向上”键最终指向“向右”。

keyboard.builtIn

定义： keyboard.builtIn = 0 | 1

指定键盘是否为内置（物理连接）键盘。

如果设备名称以 -keypad 结尾，则默认值为 1，否则为 0。

内置键盘始终分配设备 ID 0。其他非内置键盘分配唯一的非零设备 ID。

对于内置键盘，使用 ID 0 对于保持与 KeyCharacterMap.BUILT_IN_KEYBOARD 字段的兼容性非常重要，该字段指定内置键盘的 ID，其值为 0。此字段已在 API 中弃用，但较旧的应用可能仍在使用它。

特殊功能键盘（其按键字符图指定 SPECIAL_FUNCTION 类型）永远不会注册为内置键盘，无论此属性的设置如何。这是因为特殊功能键盘根据定义不打算用于通用打字。

示例配置

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

兼容性说明

在 Honeycomb 之前，键盘输入映射器不使用任何配置属性。所有键盘都假定为物理连接且方向感知。默认按键布局和按键字符图命名为 qwerty 而不是 Generic。按键字符图格式也非常不同，并且框架不支持 PC 风格的全键盘或外部键盘。

将设备升级到 Honeycomb 时，请确保创建或更新必要的配置和按键图文件。

HID 用法、Linux 键代码和 Android 键代码

系统使用几个不同的标识符来引用按键，具体取决于抽象层。

对于 HID 设备，每个按键都有关联的 HID 用法。Linux hid-input 驱动程序以及相关的供应商和设备特定 HID 驱动程序负责解析 HID 报告并将 HID 用法映射到 Linux 键代码。

当 Android 从 Linux 内核读取 EV_KEY 事件时，它会根据设备的按键布局文件将每个 Linux 键代码转换为其对应的 Android 键代码。

当按键事件调度到应用时，android.view.KeyEvent 实例会将 Linux 键代码报告为 getScanCode() 的值，并将 Android 键代码报告为 getKeyCode() 的值。对于框架而言，只有 getKeyCode() 的值才重要。

请注意，Android 本身不使用 HID 用法信息，也不会将其传递给应用。

代码表

下表显示了 HID 用法、Linux 键代码和 Android 键代码之间的相互关系。

LKC 列指定了十六进制的 Linux 键代码。

AKC 列指定了十六进制的 Android 键代码。

“注释”列指的是表格后发布的注释。

“版本”列指定了 Android 平台的第一个版本，该版本在其默认按键图中包含了此按键。在默认按键图在版本之间发生更改的情况下，会显示多行。指示的最旧版本为 1.6。

• 在 Gingerbread (2.3) 及更早版本中，默认按键图为 qwerty.kl。此按键图仅供 Android 模拟器使用，并非旨在用于支持任意外部键盘。尽管如此，一些 OEM 在平台中添加了蓝牙键盘支持，并依赖 qwerty.kl 来提供必要的键盘映射。因此，对于正在为这些特定设备构建外围设备的 OEM 而言，这些较旧的映射可能很有意义。请注意，这些映射与当前的映射有很大不同，尤其是在 HOME 键的处理方面。建议所有新的外围设备都应根据 Honeycomb 或更新的按键图（即标准 HID）进行开发。

• 从 Honeycomb (3.0) 开始，默认按键图为 Generic.kl。此按键图旨在支持完整的 PC 样式键盘。标准 HID 键盘的大多数功能都应该可以直接使用。

键代码映射可能因 Linux 内核和 Android 版本而异。当已知 Android 默认按键图发生更改时，会在版本列中指示出来。

特定于设备的 HID 驱动程序和按键图可能会应用与此处指示的不同的映射。

HID 键盘和小键盘页 (0x07)

HID 通用桌面页 (0x01)

HID 消费者页面 (0x0c)

Additional non-HID mappings

These mappings describe functions that do not appear in HID but for which Linux key codes exist.

Legacy unsupported keys

These mappings appeared in previous versions of Android but were inconsistent with HID or used non-standard Linux key codes. They are no longer supported.

注释

1. The Android key code associated with common alphanumeric and symbolic keys may vary based on the keyboard layout and language. For historical reasons, the physical scan codes and HID usages associated with keys on a keyboard are often defined positionally even though the labels printed on those keys may vary from one language to another.

   On a US English (QWERTY) keyboard, the top-left alphabetic key is labeled Q. On a French (AZERTY) keyboard, the key in the same position is labeled A. Despite the label, on both keyboards the top-left alphabetic key is referred to using the HID usage 0x07 0x0014 which is mapped to the Linux key code KEY_Q.

   When Android is configured with a US English keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_Q and will produce the characters 'Q' and 'q'. However, when Android is configured with a French keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_A and will produce the characters 'A' and 'a'.

   The Android key code typically reflects the language-specific interpretation of the key, so a different Android key code may be used for different languages.

2. 0x0c 0x022f AC Zoom is defined in the HID as a linear control but the kernel maps it as a key, which is probably incorrect.

3. The Linux function keys KEY_FN_* are mapped to simpler key codes but are dispatched with the META_FUNCTION meta state bit set to true.

4. Prior to Android Ice Cream Sandwich 4.0, the default key layout contained mappings for some extra key codes that were not defined in the mainline Linux kernel headers. These mappings have since been removed because these previously undefined key codes have since been assigned different meanings in more recent versions of the Linux kernel.

Sources

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java