鍵盤裝置

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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. 鍵盤驅動程式可以選擇透過傳送 EV_MSC 和 MSC_SCANCODE，以及表示按下按鍵時的使用或掃描碼的值，來指出 HID 用途或低階掃描碼。Android 目前未使用這項資訊。

5. 當 EV_LED 寫入裝置時，鍵盤驅動程式應支援設定 LED 狀態。hid-input 驅動程式會自動處理這項作業。在撰寫本文時，Android 使用 LED_CAPSLOCK、LED_SCROLLLOCK 和 LED_NUMLOCK。只有在鍵盤實際具有相關指示燈時，才需要支援這些 LED。

6. 針對嵌入式數字鍵盤的鍵盤驅動程式 (例如使用 GPIO 矩陣)，應確保針對裝置進入休眠狀態時仍按下的任何按鍵，傳送 EV_KEY 事件，且值為 0。否則按鍵可能會卡住，並永久自動重複按下。

鍵盤操作

以下簡要說明 Android 上的鍵盤操作。

1. EventHub 會讀取 evdev 驅動程式中的原始事件，並使用鍵盤的按鍵版面配置對應表，將 Linux 按鍵碼 (有時稱為掃描碼) 對應至 Android 按鍵碼。

2. InputReader 會消耗原始事件並更新元鍵狀態。舉例來說，如果按下或放開左移鍵，讀取器會據此設定或重設 META_SHIFT_LEFT_ON 和 META_SHIFT_ON 位元。

3. InputReader 會將重要事件通知 InputDispatcher。

4. InputDispatcher 會透過呼叫 WindowManagerPolicy.interceptKeyBeforeQueueing，詢問 WindowManagerPolicy 如何處理按鍵事件。這個方法是關鍵路徑的一部分，負責在按下特定按鍵時喚醒裝置。EventHub 會有效地在這個關鍵路徑上保留喚醒鎖定，確保喚醒鎖定會執行至完成。

5. 如果目前有 InputFilter 在使用中，InputDispatcher 會讓 InputFilter 有機會使用或轉換金鑰。InputFilter 可用於實作系統層級的低階無障礙政策。

6. InputDispatcher 會將索引鍵排入調度執行緒的處理佇列。

7. 當 InputDispatcher 從佇列中移除鍵時，會讓 WindowManagerPolicy 有第二次機會透過呼叫 WindowManagerPolicy.interceptKeyBeforeDispatching 來攔截按鍵事件。這個方法會處理系統捷徑和其他功能。

8. InputDispatcher 接著會找出重要事件目標 (已聚焦的視窗)，並等待這些目標就緒。接著，InputDispatcher 會將按鍵事件傳送至應用程式。

9. 在應用程式中，按鍵事件會向下傳播至檢視區塊階層，並將焦點轉移至 IME 前按鍵調度。

10. 如果在預先輸入法編輯器調度作業中未處理按鍵事件，且輸入法編輯器正在使用中，則按鍵事件會傳送至輸入法編輯器。

11. 如果按鍵事件未由 IME 使用，則按鍵事件會沿著檢視畫面階層傳播至聚焦的檢視畫面，以便標準按鍵調度。

12. 應用程式會回報給 InputDispatcher，指出是否已取用按鍵事件。如果未使用事件，InputDispatcher 會呼叫 WindowManagerPolicy.dispatchUnhandledKey 以套用「備用」行為。視備用動作而定，系統可能會使用不同的鍵碼重新啟動按鍵事件調度週期。舉例來說，如果應用程式未處理 KEYCODE_ESCAPE，系統可能會改為以 KEYCODE_BACK 重新分派按鍵事件。

鍵盤設定

鍵盤行為取決於鍵盤的按鍵版面配置、按鍵字元對應和輸入裝置設定。

如要進一步瞭解參與鍵盤設定的檔案，請參閱以下各節：

• 按鍵版面配置檔案
• 鍵盤字元對應檔案
• 輸入裝置設定檔

屬性

下列輸入裝置設定屬性適用於鍵盤。

keyboard.layout

定義： keyboard.layout = <name>

指定與輸入裝置相關聯的按鍵配置檔案名稱，不含 .kl 副檔名。如果找不到這個檔案，輸入系統會改用預設的按鍵配置。

在查詢期間，名稱中的空格會轉換為底線。

詳情請參閱按鍵版面配置檔說明文件。

keyboard.characterMap

定義： keyboard.characterMap = <name>

指定與輸入裝置相關聯的鍵盤文字對應檔案名稱，不含 .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。

內建鍵盤一律會指派 0 的裝置 ID。其他非內建鍵盤會指派不重複的非零裝置 ID。

為內建鍵盤使用 0 ID 非常重要，因為這樣才能與 KeyCharacterMap.BUILT_IN_KEYBOARD 欄位保持相容性。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 鍵碼

系統會根據抽象層級，使用多個不同的 ID 參照鍵。

對於 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 Emulator 使用，不支援任意外接鍵盤。不過，部分原始設備製造商 (OEM) 在平台上加入了藍牙鍵盤支援功能，並依賴 qwerty.kl 提供必要的鍵盤對應功能。因此，這些較舊的對應項目可能會吸引為這些特定裝置建構周邊裝置的原始設備製造商 (OEM) 的興趣。請注意，這些對應項目與目前的對應項目大不相同，特別是 HOME 鍵的處理方式。建議所有新周邊裝置都根據 Honeycomb 或較新的按鍵對應表 (例如標準 HID) 進行開發。

• 自 Honeycomb (3.0) 起，預設的鍵映射為 Generic.kl。這個按鍵對應表旨在支援全 PC 風格鍵盤。標準 HID 鍵盤的大部分功能應該都能直接使用。

不同版本的 Linux 核心和 Android 可能會使用不同的按鍵代碼對應。當 Android 預設鍵映射發生變更時，系統會在版本欄中顯示這些變更。

裝置專屬的 HID 驅動程式和按鍵對應表可能會套用與此處所述不同的對應項目。

HID 鍵盤和鍵台頁面 (0x07)

HID 通用電腦版頁面 (0x01)

HID 使用者頁面 (0x0c)

其他非 HID 對應

這些對應項目會說明 HID 中沒有顯示，但 Linux 鍵碼存在的函式。

舊版不支援的鍵

這些對應項目出現在舊版 Android 中，但與 HID 不一致，或使用非標準的 Linux 鍵碼。系統已不再支援這些項目。

附註

1. 與常見英數和符號鍵相關聯的 Android 鍵碼，可能會因鍵盤配置和語言而異。基於歷史原因，與鍵盤上按鍵相關的實體掃描代碼和 HID 用法通常會以位置定義，即使這些按鍵上印製的標籤可能因語言而異。

   在美國英文 (QWERTY) 鍵盤上，左上方的字母鍵標示為 Q。在法文 (AZERTY) 鍵盤上，同一個位置的按鍵標示為 A。無論標籤為何，在兩種鍵盤上，左上角的字母鍵都會使用 HID 用法 0x07 0x0014 進行參照，而這會對應至 Linux 鍵碼 KEY_Q。

   當 Android 設定為使用美國英文鍵盤配置時，Linux 鍵碼 KEY_Q 會對應至 Android 鍵碼 KEYCODE_Q，並產生字元「Q」和「q」。不過，如果 Android 採用法文鍵盤配置，則 Linux 鍵碼 KEY_Q 會對應至 Android 鍵碼 KEYCODE_A，並產生字元「A」和「a」。

   Android 鍵碼通常會反映鍵的語言特定解讀方式，因此不同語言可能會使用不同的 Android 鍵碼。

2. 0x0c 0x022f AC Zoom 在 HID 中定義為線性控制項，但核心會將其對應為鍵，這可能不正確。

3. Linux 功能鍵 KEY_FN_* 會對應至較簡單的按鍵代碼，但會在 META_FUNCTION 元狀態位元設為 true 的情況下調度。

4. 在 Android Ice Cream Sandwich 4.0 之前，預設的按鍵配置包含對應項目，可用於一些在主線 Linux 核心標頭中未定義的額外按鍵代碼。這些對應項目已遭移除，因為這些先前未定義的鍵碼已在較新的 Linux 核心版本中指派不同的意義。

來源

1. USB HID 用途表 v1.12
2. Linux 2.6.39 核心：include/linux/input.h、drivers/hid/hid-input.c
3. Android ICS：qwerty.kl、Generic.kl、KeyEvent.java