按鍵字元對應檔案

按鍵字元對應檔案 (.kcm 檔案) 負責對應組合 的 Android 按鍵碼。

所有內部 (內建) 都必須使用裝置專屬的按鍵版面配置檔案 有按鍵的輸入裝置 (如果只會向系統告知裝置 只有特殊用途 (非全形鍵盤)。

使用外接鍵盤時，可選擇「選用」裝置專屬的按鍵配置檔案。 通常並不需要系統會提供通用的鍵字元對應 適用於多種外接鍵盤

如果沒有裝置專屬的按鍵版面配置檔案，則系統會 請改為選擇預設值。

位置

按鍵字元對應檔位於 USB 供應商、產品 (以及選用版本) 中 或是輸入的裝置名稱

以下將依序查詢下列路徑。

• /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 裝置 從 Android Honeycomb 3.0 開始虛擬鍵盤裝置的用途 提供可用於插入內容的內建輸入裝置 透過 IME 或測試檢測設備，將按鍵輸入應用程式 適用於沒有內建鍵盤的裝置。

系統假設虛擬鍵盤具備完整的 QWERTY 鍵盤配置， 設定。如此一來，應用程式 只要使用虛擬鍵盤裝置按鍵，就能獲得相同的結果。

請勿修改虛擬鍵字元對應！

語法

按鍵字元對應檔案是包含鍵盤類型的純文字檔案 以及一組鍵宣告。

鍵盤類型宣告

鍵盤類型宣告會說明鍵盤的整體行為。 字元對應檔案必須包含鍵盤類型宣告。為求明確， 檔案通常位於檔案頂端

type FULL

可辨識的鍵盤類型如下：

• NUMERIC：數字 (12 鍵) 鍵盤，

  數字鍵盤支援透過多點輕觸方法輸入文字。 您可能需要輕觸按鍵數次，系統才能產生您所需的字母或符號。

  這類鍵盤通常專為拇指輸入而設計。

  對應於 KeyCharacterMap.NUMERIC。

• PREDICTIVE：包含所有字母的鍵盤，但每個按鍵有多個字母。

  這類鍵盤通常專為拇指輸入而設計。

  對應於 KeyCharacterMap.PREDICTIVE。

• ALPHA：包含所有字母，但可能會用到數字的鍵盤。

  字母鍵盤支援直接輸入文字，但可能精簡 提供小型板型規格的版面配置相較於 FULL 鍵盤 符號只有在特殊的畫面中字元挑選器才會顯示。 此外，這套架構可提高輸入速度和準確度， 字母鍵盤的特殊用途，例如自動大寫 以及已鎖定 / 鎖定的 SHIFT 和 ALT 鍵

  這類鍵盤通常專為拇指輸入而設計。

• FULL：完整的 PC 式鍵盤。

  完整鍵盤的運作方式與電腦鍵盤類似。可直接存取所有符號 的按鍵。 使用自動大寫。

  這種鍵盤通常適用於全雙手打字功能。

• SPECIAL_FUNCTION：僅用於執行系統控制功能的鍵盤 不必打字

  特殊功能鍵盤僅包含非列印按鍵，例如 按下主畫面和電源鍵後，鍵盤就會立即消失。

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：指定沒有修飾符時的行為 (應輸入的字元) 按下按鈕。

• <修飾符>或 <modifier1>+<modifier2>+...：指定 使用者按下該鍵且所有 已啟用指定的修飾符。

  舉例來說，修飾符屬性 shift 可指定在 按下左 SHIFT 或右 SHIFT 輔助鍵。

  同樣地，修飾符屬性 rshift+ralt 會指定要套用的行為 同時按下右 SHIFT 和向右 Alt 輔助鍵時。

系統會在修飾符屬性中辨識下列修飾符：

• shift：在按下左 SHIFT 或 RIGHT SHIFT 修飾符時套用。
• lshift：在按下 LEFT SHIFT 修飾符時套用。
• rshift：在按下右 SHIFT 輔助鍵時套用。
• alt：在按下左 ALT 或 RIGHT ALT 輔助鍵時套用。
• lalt：在按下左 ALT 輔助鍵時套用。
• ralt：在按下右 Alt 輔助鍵時套用。
• ctrl：適用於按下左控制項或向右控制修飾符時套用的控制項。
• lctrl：在按下左 CONTROL 輔助鍵時套用。
• rctrl：在按下右 CONTROL 輔助鍵時套用。
• meta：在按下左 META 或 RIGHT META 修飾符時套用。
• lmeta：在按下 LEFT META 修飾符時套用。
• rmeta：在按下 RIGHT META 修飾符時套用。
• sym：在按下 SYMBOL 修飾符時套用。
• fn：在按下 FUNCTION 修飾符時套用。
• capslock：在 CAPS LOCK 修飾符鎖定時套用。
• numlock：在 NUM LOCK 修飾符鎖定時套用。
• scrolllock：在 SCROLL LOCK 修飾符鎖定時套用。

屬性的列出順序相當重要。對應鍵至 某種行為，系統會依序掃描所有相關屬性，並傳回最後一個 應符合的行為

因此，之後再指定的屬性會覆寫 為特定鍵指定的 Pod

行為

每個屬性都會對應到一種行為。最常見的行為是輸入字元 但還有其他資源

我們已辨識以下行為：

• none：請勿輸入字元。

  在未指定任何字元的情況下，此為預設行為。指定 none 選用，但可讓您更清楚瞭解。

• 'X'：輸入指定的字元常值。

  此行為會導致指定字元輸入到焦點所在項目。 文字檢視區塊。字元實字可以是任何 ASCII 字元，也可以是其中一個 以下逸出序列：

  • '\\'：輸入反斜線字元。
  • '\n'：輸入新的行字元 (用於 ENTER / RETURN)。
  • '\t'：輸入 TAB 字元。
  • '\''：輸入單引號字元。
  • '\"'：輸入引號字元。
  • '\uXXXX'：輸入碼點，以 XXXX 表示的萬國碼 (Unicode) 字元。

• fallback <Android 金鑰碼名稱>：如果不是，則執行預設動作 由應用程式處理

  此行為會導致系統在應用程式時模擬不同的按鍵按鍵操作 不會以原生方式處理指定的鍵。用於支援預設行為 表示並非所有應用程式知道如何處理的新金鑰，例如 ESCAPE 或 數字鍵盤按鍵 (未按下數字)。

  執行備用行為時，應用程式會收到兩次按鍵操作： 分別用於原始金鑰和所選備用金鑰。 如果應用程式在金鑰升級期間處理原始金鑰，則備用金鑰 活動將會取消 (KeyEvent.isCanceled 會傳回 true)。

系統會保留兩個 Unicode 字元來執行特殊功能：

• '\uef00'：執行此行為時，文字檢視區塊會使用並移除 此時，遊標前四個字元會解讀為十六進位數字，然後 對應的 Unicode 碼點。

• '\uef01'：執行此行為時，文字檢視區塊會顯示 含有其他符號的字元挑選器對話方塊。

系統會將下列萬國碼 (Unicode) 字元視為結合變音符號死亡功能 主要字元：

• '\u0300'：重音符號。
• '\u0301'：銳音符號。
• '\u0302'：揚抑符號。
• '\u0303'：波狀符號。
• '\u0308'：Umlaut 口音。

如果輸入無效鍵後接另一個字元，就會發生無效鍵和以下輸出內容 字元組成例如：使用者輸入重音符號死燈時 鍵，後面加上字母「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， 也適用於按下按鍵的 Shift + A 鍵。因此系統決定 base 屬性的行為並選擇與預期相關聯的行為 shift 屬性，也就是 'A' (輸入 A 字元)。

然後繼續掃描資料表，但其他屬性並不適用 按下按鍵 (CAPS LOCK 未上鎖，未按下 CONTROL 鍵，兩者皆非 已按下 ALT 鍵，且未按下 META 鍵)。

因此按鍵組合 SHIFT + A 的結果是 'A'。

CONTROL + A

現在，請想想使用者同時按下 A 和 CONTROL 會有什麼影響。

與先前一樣，系統會掃描物業表格。結果會發現 已套用 base 屬性，但也會繼續掃描，直到 該資源最終觸及了 control 屬性。發生此情況時，control 屬性會出現在 base 之後，所以其行為會覆寫 base 行為。

因此組合鍵 CONTROL + A 的結果是 none。

ESCAPE 鍵

現在，假設使用者按下 ESCAPE。

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

這次系統會取得行為 fallback BACK，這是一種備用行為。 由於不會顯示任何字元常值，因此不會輸入任何字元。

處理金鑰時，系統會先將 KEYCODE_ESCAPE 傳送至 應用程式。如果應用程式無法處理，則系統會嘗試 但這次函式會將 KEYCODE_BACK 傳遞至應用程式 由備用行為要求而成

因此，識別及支援 KEYCODE_ESCAPE 的應用程式 但其他應用程式無法直接處理 執行將鍵視為 KEYCODE_BACK 的備用動作。

NUMPAD_0 包含或沒有 NUM LOCK

視數字鍵盤或數字鍵盤而定， NUM LOCK 金鑰已鎖定。

下列重要宣告可確保 KEYCODE_NUMPAD_0 類型 0 按下 NUM LOCK 時出現。當未按下 NUM LOCK 時，系統會提交金鑰 並照常傳送至應用程式，如果未加以處理， 而是改用金鑰 KEYCODE_INSERT。

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

如您所見，備用金鑰宣告可大幅提高相容性 無法識別或直接支援所有金鑰的舊版應用程式 。

範例

完整鍵盤

# 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 版本可能會為多語言鍵盤提供更完善的支援 或使用者選取的鍵盤配置

驗證

請務必使用 驗證按鍵對應配置工具。