按鍵字元對映檔案（ .kcm檔案）負責將帶有修飾符的 Android 按鍵程式碼組合對應到 Unicode 字元。
所有具有按鍵的內部（內建）輸入裝置都需要特定於裝置的按鍵佈局文件，即使只是為了告訴系統該裝置僅供特殊用途（不是完整的鍵盤）。
對於外部鍵盤來說，特定於裝置的按鍵佈局檔案是可選的，而且通常根本不需要。該系統提供了適用於許多外部鍵盤的通用按鍵字元映射表。
如果沒有可用的特定於裝置的按鍵佈局文件，則係統將選擇預設值。
地點
鍵字元對應檔案按 USB 供應商、產品（和選用版本）ID 或輸入裝置名稱定位。
按順序查閱以下路徑。
-
/odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm -
/vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm -
/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm -
/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm -
/odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm -
/vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm -
/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm -
/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm -
/odm/usr/keychars/DEVICE_NAME.kcm -
/vendor/usr/keychars/DEVICE_NAME.kcm -
/system/usr/keychars/DEVICE_NAME.kcm -
/data/system/devices/keychars/DEVICE_NAME.kcm -
/odm/usr/keychars/Generic.kcm -
/vendor/usr/keychars/Generic.kcm -
/system/usr/keychars/Generic.kcm -
/data/system/devices/keychars/Generic.kcm -
/odm/usr/keychars/Virtual.kcm -
/vendor/usr/keychars/Virtual.kcm -
/system/usr/keychars/Virtual.kcm -
/data/system/devices/keychars/Virtual.kcm
當建構包含裝置名稱的檔案路徑時，裝置名稱中除 '0'-'9'、'a'-'z'、'A'-'Z'、'-' 或 '_' 之外的所有字元被替換為“_”。
通用鍵字元映射文件
系統提供了一個特殊的內建按鍵字元映射文件，稱為Generic.kcm 。此按鍵字元映射表旨在支援各種標準外部鍵盤。
不要修改通用按鍵字元圖！
虛擬鍵字元對應文件
系統提供了一個名為Virtual.kcm的特殊內建按鍵字元映射文件，供虛擬鍵盤裝置使用。
虛擬鍵盤設備是合成輸入設備，其 id 為 -1（請參閱KeyCharacterMap.VIRTUAL_KEYBOARD ）。它存在於從 Android Honeycomb 3.0 開始的所有 Android 裝置上。虛擬鍵盤設備的目的是提供一個已知的內建輸入設備，該設備可用於透過 IME 或測試儀器將擊鍵注入到應用程式中，甚至對於沒有內建鍵盤的設備也是如此。
假定虛擬鍵盤具有在所有裝置上相同的完整 QWERTY 佈局。這使得應用程式可以使用虛擬鍵盤裝置注入擊鍵並始終獲得相同的結果。
請勿修改虛擬按鍵字元圖！
句法
鍵字元映射檔案是由鍵盤類型聲明和一組鍵聲明組成的純文字檔案。
鍵盤類型聲明
鍵盤類型聲明描述了鍵盤的整體行為。字元對映檔案必須包含鍵盤類型聲明。為了清楚起見，它通常放置在文件的頂部。
type FULL
可識別以下鍵盤類型：
NUMERIC：數字（12 鍵）鍵盤。數字鍵盤支援使用多次敲擊方法進行文字輸入。可能需要多次敲擊某個鍵才能產生所需的字母或符號。
這種類型的鍵盤通常是為拇指打字而設計的。
對應於
KeyCharacterMap.NUMERIC。PREDICTIVE：包含所有字母的鍵盤，但每個鍵有多個字母。這種類型的鍵盤通常是為拇指打字而設計的。
對應於
KeyCharacterMap.PREDICTIVE。ALPHA：包含所有字母的鍵盤，也許還有一些數字。字母鍵盤直接支援文字輸入，但可能具有尺寸較小的壓縮佈局。與
FULL鍵盤相比，某些符號只能使用特殊的螢幕字元選擇器來存取。此外，為了提高打字速度和準確性，該框架為字母鍵盤提供了特殊的功能，例如自動大寫和切換/鎖定的 SHIFT 和 ALT 鍵。這種類型的鍵盤通常是為拇指打字而設計的。
FULL：完整的 PC 風格鍵盤。全鍵盤的行為類似 PC 鍵盤。所有符號均可透過鍵盤上的按鍵直接存取，無需螢幕支援或自動大寫等功能。
這種類型的鍵盤通常設計用於全雙手打字。
SPECIAL_FUNCTION：僅用於執行系統控制功能而不是用於打字的鍵盤。特殊功能鍵盤僅由非列印鍵（例如 HOME 和 POWER）組成，這些按鍵實際上並未用於打字。
Generic.kcm和Virtual.kcm按鍵字元映射都是FULL鍵盤。
關鍵聲明
每個鍵聲明都包含關鍵字key ，後面跟著 Android 鍵程式碼名稱、左大括號、一組屬性和行為以及右大括號。
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
特性
每個鍵屬性都建立了從鍵到行為的對應。為了使關鍵字元映射檔案更加緊湊，可以透過用逗號分隔多個屬性來將它們對應到相同的行為。
在上面的範例中， label屬性被指派了'A'行為。同樣， ctrl 、 alt和meta屬性都同時指定為none行為。
以下屬性得到認可：
label：指定物理印在按鍵上的標籤（當它由單一字元組成時）。這是KeyCharacterMap.getDisplayLabel方法傳回的值。number：指定當數位文字檢視具有焦點時（例如當使用者鍵入電話號碼時）的行為（應鍵入的字元）。緊湊型鍵盤通常將多個符號組合成一個鍵，這樣同一個鍵可能用於鍵入
'1'和'a'或'#'和'q'。對於這些鍵，應設定number屬性以指示應在數字上下文中鍵入哪個符號（如果有）。一些典型的“數字”符號是數字
'0'到'9'、'#'、'+'、'('、')'、','和'.'。base：指定未按下修飾符時的行為（應鍵入的字元）。<modifier> 或 <modifier1>
+<modifier2>+...：指定按下按鍵且所有指定修飾符均處於活動狀態時的行為（應鍵入的字元）。例如，修飾符屬性
shift指定在按下 LEFT SHIFT 或 RIGHT SHIFT 修飾符時所應用的行為。同樣，修飾符屬性
rshift+ralt指定同時按下 RIGHT SHIFT 和 RIGHT ALT 修飾符時所應用的行為。
修飾符屬性可辨識下列修飾符：
-
shift：按下 LEFT SHIFT 或 RIGHT SHIFT 修飾鍵時套用。 -
lshift：按下 LEFT SHIFT 修飾鍵時套用。 -
rshift：按下 RIGHT SHIFT 修飾鍵時套用。 -
alt：按下 LEFT ALT 或 RIGHT ALT 修飾鍵時套用。 -
lalt：按下 LEFT ALT 修飾鍵時套用。 -
ralt：按下 RIGHT ALT 修改鍵時套用。 -
ctrl：按下 LEFT CONTROL 或 RIGHT CONTROL 修飾鍵時套用。 -
lctrl：按下 LEFT CONTROL 修飾鍵時套用。 -
rctrl：按下 RIGHT CONTROL 修飾鍵時套用。 -
meta：按下 LEFT META 或 RIGHT META 修飾符時套用。 -
lmeta：按下 LEFT META 修改鍵時套用。 -
rmeta：按下 RIGHT META 修改鍵時套用。 -
sym：按下 SYMBOL 修飾符時套用。 -
fn：按下 FUNCTION 修飾符時套用。 -
capslock：當 CAPS LOCK 修改器被鎖定時套用。 -
numlock：當 NUM LOCK 修飾符被鎖定時套用。 -
scrolllock：當 SCROLL LOCK 修飾符被鎖定時套用。
列出屬性的順序很重要。將鍵對應到行為時，系統會依序掃描所有相關屬性，並傳回找到的最後一個適用的行為。
因此，稍後指定的屬性將覆寫先前為給定鍵指定的屬性。
行為
每個屬性都映射到一種行為。最常見的行為是鍵入字符，但還有其他行為。
以下行為得到認可：
none：不輸入字元。當未指定字元時，此行為是預設行為。不指定
none是可選的，但它可以提高清晰度。'X'：鍵入指定的字元文字。此行為會導致指定的字元輸入到焦點文字檢視中。字符文字可以是任何 ASCII 字符，或以下轉義序列之一：
-
'\\'：輸入反斜線字元。 -
'\n'：輸入新行字元（用於 ENTER / RETURN）。 -
'\t'：輸入製表符。 -
'\''：鍵入撇號字元。 -
'\"'：輸入引號字元。 -
'\uXXXX'：鍵入 Unicode 字符，其代碼點由 XXXX 以十六進位形式給出。
-
fallback<Android 鍵程式碼名稱>：如果應用程式不處理該鍵，則執行預設操作。當應用程式本身不處理指定的按鍵時，此行為會導致系統模擬不同的按鍵。它用於支援並非所有應用程式都知道如何處理的新鍵的預設行為，例如 ESCAPE 或數字鍵盤鍵（未按下 numlock 時）。
執行後備行為時，應用程式將收到兩次按鍵操作：一次針對原始按鍵，另一次針對所選的後備按鍵。如果應用程式在按鍵期間處理原始按鍵，則後備按鍵事件將被取消（
KeyEvent.isCanceled將傳回true）。
系統保留兩個Unicode字元來執行特殊功能：
'\uef00'：執行此行為時，文字視圖會消耗並刪除遊標前面的四個字符，將它們解釋為十六進位數字，並插入相應的 Unicode 代碼點。'\uef01'：執行此行為時，文字檢視將顯示一個包含各種符號的字元選擇器對話方塊。
系統將以下 Unicode 字元辨識為組合變音死鍵字元：
-
'\u0300': 重音。 -
'\u0301'：尖銳的口音。 -
'\u0302'：抑揚音。 -
'\u0303'：波浪號重音。 -
'\u0308'：母音變音。
當鍵入死鍵並接著鍵入另一個字元時，死鍵和後續字元將被組合。例如，當使用者鍵入重音死鍵後接字母“a”時，結果是“à”。
有關死鍵處理的更多信息，請參閱KeyCharacterMap.getDeadChar 。
評論
註解行以「#」開始，一直到行尾。像這樣：
# A comment!
空行將被忽略。
組合鍵如何映射到行為
當使用者按下某個鍵時，系統會尋找與該按鍵和目前按下的修飾符的組合相關的行為。
SHIFT + A
假設使用者同時按下 A 和 SHIFT。系統首先定位與KEYCODE_A關聯的屬性和行為集。
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
系統從頭到尾、從左到右掃描屬性，忽略特殊的label和數number屬性。
遇到的第一個屬性是base 。無論按下什麼修飾鍵， base屬性總是適用於某個鍵。它本質上指定了鍵的預設行為，除非它被以下屬性覆寫。由於base屬性適用於此鍵，因此系統會記錄其行為為'a' （鍵入字元a ）這一事實。
然後，系統繼續掃描後續屬性，以防其中任何屬性比base屬性更具體並覆蓋它。它遇到了也適用於按鍵 SHIFT + A 的shift 。因此系統決定忽略base屬性的行為並選擇與shift屬性關聯的行為，即'A' （鍵入字元A ）。
然後它繼續掃描表，但是沒有其他屬性適用於該按鍵（CAPS LOCK 未鎖定，CONTROL 鍵均未按下，ALT 鍵均未按下，META 鍵均未按下）。
因此組合鍵 SHIFT + A 的結果行為是'A' 。
控制+A
現在考慮如果使用者同時按下 A 和 CONTROL 會發生什麼。
和以前一樣，系統將掃描屬性表。它會注意到已套用base屬性，但也會繼續掃描，直到最終到達control屬性。碰巧的是， control屬性出現在base之後，因此它的行為會覆寫base行為。
因此組合鍵 CONTROL + A 的結果行為是none 。
逃脫
現在假設用戶按下了 ESCAPE。
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
這次系統獲得了fallback BACK行為，即fallback行為。由於沒有出現字元文字，因此不會鍵入任何字元。
在處理密鑰時，系統首先將KEYCODE_ESCAPE傳遞給應用程式。如果應用程式不處理它，則係統將再次嘗試，但這次它將按照回退行為的請求將KEYCODE_BACK傳遞給應用程式。
因此，識別並支援KEYCODE_ESCAPE應用程式有機會按原樣處理它，但其他不支援的應用程式可以執行回退操作，將密鑰視為KEYCODE_BACK 。
NUMPAD_0 有或沒有 NUM LOCK
根據 NUM LOCK 鍵是否鎖定，數字鍵盤上的按鍵有非常不同的解釋。
下列鍵聲明可確保按下 NUM LOCK 時KEYCODE_NUMPAD_0鍵入0 。當未按下 NUM LOCK 時，該鍵將照常傳遞給應用程序，如果未處理，則會傳遞回退鍵KEYCODE_INSERT 。
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
正如我們所看到的，後備鍵聲明極大地提高了與舊應用程式的兼容性，這些應用程式無法識別或直接支援完整 PC 風格鍵盤上存在的所有按鍵。
例子
全鍵盤
# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.
type FULL
key C {
label: 'C'
base: 'c'
shift, capslock: 'C'
alt: '\u00e7'
shift+alt: '\u00c7'
ctrl, meta: none
}
key SPACE {
label: ' '
base: ' '
ctrl: none
alt, meta: fallback SEARCH
}
key NUMPAD_9 {
label, number: '9'
base: fallback PAGE_UP
numlock: '9'
ctrl, alt, meta: none
}
字母數字鍵盤
# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard. Some keys are combined, such as `A` and `2`. Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.
type ALPHA
key A {
label: 'A'
number: '2'
base: 'a'
shift, capslock: 'A'
alt: '#'
shift+alt, capslock+alt: none
}
key SPACE {
label: ' '
number: ' '
base: ' '
shift: ' '
alt: '\uef01'
shift+alt: '\uef01'
}
遊戲手把
# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.
type SPECIAL_FUNCTION
key BUTTON_A {
base: fallback BACK
}
key BUTTON_X {
base: fallback DPAD_CENTER
}
key BUTTON_START {
base: fallback HOME
}
key BUTTON_SELECT {
base: fallback MENU
}
相容性說明
在 Android Honeycomb 3.0 之前，Android 鍵字元對應是使用非常不同的語法指定的，並在建置時編譯為二進位檔案格式 ( .kcm.bin )。
儘管新格式使用相同的副檔名.kcm ，但語法卻截然不同（而且更強大）。
從 Android Honeycomb 3.0 開始，所有 Android 按鍵字元對應檔案都必須使用本文檔中所述的新語法和純文字檔案格式。不支援舊語法，且系統無法辨識舊的.kcm.bin檔案。
語言註釋
Android 目前不支援多語言鍵盤。此外，內建通用按鍵字元映射表採用美國英語鍵盤佈局。
如果鍵盤是為其他語言設計的，我們鼓勵 OEM 為其鍵盤提供自訂按鍵字元映射。
Android 的未來版本可能會為多語言鍵盤或使用者可選擇的鍵盤佈局提供更好的支援。
驗證
確保使用驗證鍵盤映射工具驗證您的按鍵字元映射檔案。