鍵盤裝置

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 值來編寫程式碼 或在按下該按鍵時掃描圖碼目前還沒有這項資訊 更是如此

5. 鍵盤驅動程式應支援在寫入 EV_LED 時設定 LED 狀態 。hid-input 驅動程式會自動處理這項作業。 撰寫本文時，Android 會使用 LED_CAPSLOCK、LED_SCROLLLOCK、 和 LED_NUMLOCK。只有在發生緊急情況時 但鍵盤上其實有相關指示燈

6. 嵌入式鍵盤的鍵盤驅動程式 (例如使用 GPIO 矩陣) 對任何符合下列條件的鍵，請務必傳送EV_KEY值為 0 的事件 在裝置進入休眠時仍會按下。如果沒有， 並自動重複執行該動作

鍵盤操作

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

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

2. InputReader 會耗用原始事件，並更新中繼鍵狀態。 例如，如果按下 Shift 鍵或釋放滑鼠左鍵，讀取器則會 視需要設定或重設 META_SHIFT_LEFT_ON 和 META_SHIFT_ON 位元。

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

4. InputDispatcher 要求 WindowManagerPolicy 如何處理金鑰 呼叫 WindowManagerPolicy.interceptKeyBeforeQueueing 取得。這個方法 是關鍵路徑之一，使用者可在 特定按鍵EventHub 可有效保留 Wake Lock 務必沿著這個關鍵路徑執行，確保容器執行完畢

5. 如果 InputFilter 正在使用中，InputDispatcher 會為其提供 使用或轉換鍵的機會。InputFilter 可用於實作 低階系統通用的無障礙政策

6. InputDispatcher 會將金鑰排入佇列，以便在調度執行緒上處理。

7. InputDispatcher 將鍵移出佇列時，會給 WindowManagerPolicy 第二個機會攔截按鍵事件，方法是呼叫 WindowManagerPolicy.interceptKeyBeforeDispatching。這個方法可以處理系統 捷徑和其他功能

8. 接著，InputDispatcher 就會識別重要事件目標 (聚焦視窗) 等待它們準備就緒接著，InputDispatcher 會傳遞 傳送至應用程式的重要事件

9. 在應用程式中，按鍵事件會向下傳播檢視區塊階層至 透過聚焦檢視畫面瞭解 IME 之前的按鍵分派。

10. 如果輸入法編輯器分派並未處理重要事件，且輸入法編輯器正在使用中， 傳送到 IME。

11. 如果輸入法編輯器未使用重要事件，則會傳播重要事件 將檢視區塊階層向下移動至焦點檢視畫面，以進行標準鍵派作業。

12. 應用程式會向 InputDispatcher 回報，指出索引鍵是否 事件。如未消耗事件，InputDispatcher 呼叫 WindowManagerPolicy.dispatchUnhandledKey 以套用「備用」行為 視備用動作而定，系統可能會重新啟動重要事件分派週期 使用不同的按鍵碼例如，如果應用程式沒有 KEYCODE_ESCAPE，系統可能會改為將按鍵事件重新分派為 KEYCODE_BACK。

鍵盤設定

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

請參閱下列各節，進一步瞭解會 參與鍵盤設定：

• 主要版面配置檔案
• 索引鍵字元對應檔案
• 輸入裝置的設定檔

屬性

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

鍵盤配置

定義： keyboard.layout = <name>

指定與輸入裝置相關聯的按鍵版面配置檔案名稱。 但 .kl 擴充功能除外。如果找不到這個檔案，輸入系統 就會改用預設的按鍵配置

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

詳情請參閱主要版面配置檔案說明文件。

Keyboard.characterMap

定義： keyboard.characterMap = <name>

指定與輸入裝置相關聯的鍵字元對應檔名稱。 但 .kcm 擴充功能除外。如果找不到這個檔案，輸入系統 將改用預設按鍵字元對應。

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

詳情請參閱索引鍵字元對應檔案說明文件。

鍵盤.orientationAware

定義： keyboard.orientationAware = 0 |1

指定鍵盤是否要回應螢幕方向變更。

• 如果值為 1，系統會在 相關的螢幕方向變更。

• 如果值為 0，鍵盤就不會變更顯示方向。

預設值為 0。

螢幕方向感知功能是用來支援方向鍵鍵盤的旋轉功能 例如 Motorola 機器人例如，當裝置旋轉裝置時 從自然方向依順時針方向為 90 度，KEYCODE_DPAD_UP 是 自「向上」重新對應以產生 KEYCODE_DPAD_RIGHT鑰匙朝上 「右」裝置直立擺放。

鍵盤建構

定義： keyboard.builtIn = 0 |1

指定是否為內建鍵盤 (實體連接) 鍵盤。

如果裝置名稱結尾是 -keypad，則預設值為 1，否則預設值為 0。

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

對內建鍵盤使用 0 ID 相當重要 與 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。重要 也截然不同，但架構不支援 電腦式全鍵盤或外接鍵盤。

將裝置升級至 Honeycomb 時，請務必建立或更新必要的 設定和索引鍵對應檔

HID 使用情形、Linux 金鑰代碼和 Android 金鑰碼

系統會根據 抽象層

針對 HID 裝置，每個金鑰都有相關聯的 HID 用量。Linux hid-input 驅動程式及相關廠商及裝置專屬的 HID 驅動程式負責 ，剖析 HID 報告，以及將 HID 使用情形對應至 Linux 按鍵碼。

Android 從 Linux 核心讀取 EV_KEY 事件時，會轉譯每個 根據 裝置的主要版面配置檔案。

將按鍵事件分派給應用程式時，android.view.KeyEvent 執行個體會將 Linux 金鑰程式碼回報為 getScanCode() 的值， Android 金鑰碼做為 getKeyCode() 的值。就 架構，只有 getKeyCode() 的值才很重要。

請注意，Android 本身或 傳遞到應用程式

程式碼資料表

下表說明 HID 使用情形、Linux 金鑰碼和 Android 按鍵碼彼此相關。

LKC 欄會以十六進制指定 Linux 金鑰碼。

AKC 資料欄會指定十六進位的 Android 金鑰代碼。

「附註」欄指的是表格之後張貼的附註。

「Version」欄會指定 Android 平台的第一個版本 ，將此金鑰納入預設按鍵對應配置。有多個資料列 顯示會在預設按鍵對應不同版本之間變更時使用。 最舊的版本為 1.6。

• 在 Gingerbread (2.3) 以下版本中，預設按鍵對應配置為 qwerty.kl。這個按鍵對應配置僅限與 Android 裝置搭配使用 模擬器並非用來支援任意 以及外接鍵盤不過，一些原始設備製造商 (OEM) 新增了藍牙 讓鍵盤支援平台，並仰賴 qwerty.kl 提供必要的鍵盤對應。因此 對開發模型的原始設備製造商來說 這些裝置的周邊裝置。請注意，對應 明顯與現行版本之間有很大的差異 與 HOME 鍵的處理方式不同。建議 確保所有新的周邊裝置 都會根據 Honeycomb 或 近期按鍵對應配置 (例如標準 HID)。

• 截至 Honeycomb (3.0) 為止，預設按鍵對應為 Generic.kl。 這張機碼對應設計為支援全電腦樣式鍵盤。 標準 HID 鍵盤的大多數功能應該都能正常運作 方塊內。

按鍵程式碼的對應方式可能會因 Linux 核心和 Android 版本而異， 如果 Android 預設按鍵對應中有已知的變更， 就會列在「版本」欄中

裝置專屬的 HID 驅動程式和按鍵對應配置可能適用不同的對應項目 而不是本文的說明。

HID 鍵盤和撥號鍵盤頁面 (0x07)

HID 一般電腦版網頁 (0x01)

HID 消費者頁面 (0x0c)

其他非 HID 對應

這些對應描述了未顯示在 HID 中，但適用於 Linux 的函式 已產生按鍵碼。

舊版不支援的金鑰

這些對應項目出現在舊版 Android 中，但與 HID 或非標準 Linux 金鑰碼。系統已停止支援這些格式。

附註

1. 與常見英數字元和符號相關聯的 Android 金鑰代碼 按鍵可能因鍵盤配置和語言而異。 基於歷史原因，實體掃描代碼和 HID 使用情形 通常與鍵盤上的按鍵相關 即使這些金鑰上列印的標籤不同 轉換成另一種語言

   在美式英文 (QWERTY) 鍵盤上，左上角的字母按鍵是 並加上標籤使用法文 (AZERTY) 鍵盤上的按鍵必須同樣是 位置標示為 A。無論輸入標籤為何，在兩個鍵盤上 左上方的字母金鑰指的是使用 HID 金鑰 對應至 Linux 金鑰代碼 KEY_Q 的 0x07 0x0014。

   如果 Android 設定美式英文鍵盤配置， Linux 金鑰碼 KEY_Q 會對應至 Android 金鑰碼 KEYCODE_Q，然後會產生「Q」字元和「q」。 不過，如果 Android 設定法文鍵盤配置， 系統會將 Linux 金鑰代碼 KEY_Q 對應至 Android 金鑰碼 KEYCODE_A，然後會產生「A」字元和「a」

   Android 金鑰碼通常反映各語言專屬的 因此其他 Android 金鑰程式碼 以支援不同語言

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

3. Linux 函式鍵 KEY_FN_* 對應至更簡單 按鍵碼，但透過 META_FUNCTION 中繼狀態分派 位元設為 true。

4. Android Ice Cream Sandwich 4.0 之前的預設按鍵配置 包含某些未定義的額外按鍵碼的對應 。這些對應的對應關係， 已移除，因為這些先前未定義的按鍵碼 因為在較新版本中 Linux kernel 的元件數量

來源

1. USB HID 使用表 1.12 版
2. Linux 2.6.39 核心：include/linux/input.h、drive/hid/hid-input.c
3. Android ICS：qwerty.kl、Generic.kl、KeyEvent.java