Tệp bản đồ ký tự chính

Các tệp bản đồ ký tự chính (tệp .kcm ) chịu trách nhiệm ánh xạ các tổ hợp mã khóa Android với bộ sửa đổi thành ký tự Unicode.

Cần có các tệp bố cục phím dành riêng cho thiết bị cho tất cả các thiết bị đầu vào bên trong (tích hợp) có phím, nếu chỉ để cho hệ thống biết rằng thiết bị này chỉ dành cho mục đích đặc biệt (không phải bàn phím đầy đủ).

Các tệp bố cục phím dành riêng cho thiết bị là tùy chọn cho bàn phím ngoài và thường không cần thiết. Hệ thống cung cấp bản đồ ký tự phím chung phù hợp với nhiều bàn phím ngoài.

Nếu không có sẵn tệp bố cục khóa dành riêng cho thiết bị thì hệ thống sẽ chọn mặc định để thay thế.

Vị trí

Các tệp bản đồ ký tự chính được định vị theo nhà cung cấp USB, id sản phẩm (và phiên bản tùy chọn) hoặc theo tên thiết bị đầu vào.

Các đường dẫn sau đây được tham khảo theo thứ tự.

  • /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

Khi xây dựng đường dẫn tệp chứa tên thiết bị, tất cả các ký tự trong tên thiết bị ngoại trừ '0'-'9', 'a'-'z', 'A'-'Z', '-' hoặc '_' được thay thế bằng '_'.

Tệp bản đồ ký tự khóa chung

Hệ thống cung cấp một tệp bản đồ ký tự khóa tích hợp đặc biệt có tên Generic.kcm . Bản đồ ký tự phím này nhằm mục đích hỗ trợ nhiều loại bàn phím ngoài tiêu chuẩn.

Không sửa đổi bản đồ ký tự khóa chung!

Tệp bản đồ ký tự phím ảo

Hệ thống cung cấp một tệp bản đồ ký tự khóa tích hợp đặc biệt có tên Virtual.kcm được các thiết bị bàn phím ảo sử dụng.

Thiết bị bàn phím ảo là thiết bị đầu vào tổng hợp có id là -1 (xem KeyCharacterMap.VIRTUAL_KEYBOARD ). Nó có mặt trên tất cả các thiết bị Android bắt đầu từ Android Honeycomb 3.0. Mục đích của thiết bị bàn phím ảo là cung cấp một thiết bị đầu vào tích hợp đã biết có thể được sử dụng để đưa tổ hợp phím vào các ứng dụng bằng IME hoặc bằng công cụ kiểm tra, ngay cả đối với các thiết bị không có bàn phím tích hợp.

Bàn phím ảo được cho là có bố cục QWERTY đầy đủ giống nhau trên tất cả các thiết bị. Điều này giúp các ứng dụng có thể thực hiện thao tác nhấn phím bằng thiết bị bàn phím ảo và luôn nhận được kết quả tương tự.

Không sửa đổi bản đồ ký tự phím ảo!

Cú pháp

Tệp bản đồ ký tự khóa là một tệp văn bản thuần túy bao gồm khai báo kiểu bàn phím và một tập hợp các khai báo khóa.

Khai báo kiểu bàn phím

Khai báo loại bàn phím mô tả hành vi tổng thể của bàn phím. Tệp bản đồ ký tự phải chứa khai báo kiểu bàn phím. Để rõ ràng, nó thường được đặt ở đầu tập tin.

type FULL

Các loại bàn phím sau được nhận dạng:

  • NUMERIC : Bàn phím số (12 phím).

    Bàn phím số hỗ trợ nhập văn bản bằng cách sử dụng phương pháp nhấn nhiều lần. Có thể cần phải nhấn một phím nhiều lần để tạo ra chữ cái hoặc ký hiệu mong muốn.

    Loại bàn phím này thường được thiết kế để gõ bằng ngón tay cái.

    Tương ứng với KeyCharacterMap.NUMERIC .

  • PREDICTIVE : Bàn phím có tất cả các chữ cái, nhưng có nhiều hơn một chữ cái trên mỗi phím.

    Loại bàn phím này thường được thiết kế để gõ bằng ngón tay cái.

    Tương ứng với KeyCharacterMap.PREDICTIVE .

  • ALPHA : Bàn phím có tất cả các chữ cái và có thể một số số.

    Bàn phím chữ cái hỗ trợ nhập văn bản trực tiếp nhưng có thể có bố cục cô đọng với kiểu dáng nhỏ. Ngược lại với bàn phím FULL , một số ký hiệu chỉ có thể truy cập được bằng cách sử dụng bộ chọn ký tự đặc biệt trên màn hình. Ngoài ra, để cải thiện tốc độ và độ chính xác khi gõ, khung này còn cung cấp các khả năng đặc biệt cho bàn phím chữ cái như tự động viết hoa và các phím SHIFT và ALT được bật/khóa.

    Loại bàn phím này thường được thiết kế để gõ bằng ngón tay cái.

  • FULL : Bàn phím kiểu PC đầy đủ.

    Bàn phím đầy đủ hoạt động giống như bàn phím PC. Tất cả các ký hiệu đều được truy cập trực tiếp bằng cách nhấn các phím trên bàn phím mà không cần hỗ trợ trên màn hình hoặc khả năng chi trả như tự động viết hoa.

    Loại bàn phím này thường được thiết kế để gõ hoàn toàn bằng hai tay.

  • SPECIAL_FUNCTION : Bàn phím chỉ được sử dụng để thực hiện các chức năng điều khiển hệ thống chứ không phải để gõ.

    Bàn phím chức năng đặc biệt chỉ bao gồm các phím không in được như HOME và POWER mà thực tế không được sử dụng để gõ.

Bản đồ ký tự phím Generic.kcm và Virtual.kcm đều là bàn phím FULL .

Khai báo khóa

Mỗi phần khai báo khóa bao gồm key từ khóa, theo sau là tên mã khóa Android, dấu ngoặc nhọn mở, tập hợp các thuộc tính và hành vi cũng như dấu ngoặc nhọn đóng.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Của cải

Mỗi thuộc tính khóa thiết lập ánh xạ từ khóa đến hành vi. Để làm cho các tệp bản đồ ký tự chính nhỏ gọn hơn, một số thuộc tính có thể được ánh xạ tới cùng một hành vi bằng cách phân tách chúng bằng dấu phẩy.

Trong ví dụ trên, thuộc tính label được gán hành vi 'A' . Tương tự như vậy, các thuộc tính ctrl , alt và meta đều được gán đồng thời hành vi none .

Các thuộc tính sau được công nhận:

  • label : Chỉ định nhãn được in vật lý trên phím khi nó bao gồm một ký tự đơn. Đây là giá trị được trả về bởi phương thức KeyCharacterMap.getDisplayLabel .

  • number : Chỉ định hành vi (ký tự cần được nhập) khi chế độ xem văn bản số có tiêu điểm, chẳng hạn như khi người dùng đang nhập số điện thoại.

    Bàn phím nhỏ gọn thường kết hợp nhiều ký hiệu thành một phím duy nhất, sao cho có thể sử dụng cùng một phím để gõ '1' và 'a' hoặc '#' và 'q' . Đối với các khóa này, thuộc tính number phải được đặt để cho biết ký hiệu nào sẽ được nhập trong ngữ cảnh số, nếu có.

    Một số ký hiệu "số" điển hình là các chữ số từ '0' đến '9' , '#' , '+' , '(' , ')' , ',' và '.' .

  • base : Chỉ định hành vi (ký tự cần được nhập) khi không có từ bổ nghĩa nào được nhấn.

  • <modifier> hoặc <modifier1> + <modifier2> + ...: Chỉ định hành vi (ký tự cần nhập) khi nhấn phím và tất cả các sửa đổi được chỉ định đều hoạt động.

    Ví dụ: thuộc tính của công cụ sửa đổi shift chỉ định một hành vi áp dụng khi nhấn công cụ sửa đổi LEFT SHIFT hoặc RIGHT SHIFT.

    Tương tự, thuộc tính công cụ sửa đổi rshift+ralt chỉ định hành vi áp dụng khi cả hai công cụ sửa đổi RIGHT SHIFT và RIGHT ALT được nhấn cùng nhau.

Các công cụ sửa đổi sau đây được nhận dạng trong các thuộc tính của công cụ sửa đổi:

  • shift : Áp dụng khi nhấn phím bổ trợ LEFT SHIFT hoặc RIGHT SHIFT.
  • lshift : Áp dụng khi nhấn phím bổ trợ LEFT SHIFT.
  • rshift : Áp dụng khi nhấn phím bổ trợ RIGHT SHIFT.
  • alt : Áp dụng khi nhấn phím bổ trợ LEFT ALT hoặc RIGHT ALT.
  • lalt : Áp dụng khi nhấn phím bổ trợ LEFT ALT.
  • ralt : Áp dụng khi nhấn phím bổ trợ RIGHT ALT.
  • ctrl : Áp dụng khi nhấn công cụ sửa đổi ĐIỀU KHIỂN TRÁI hoặc KIỂM SOÁT PHẢI.
  • lctrl : Áp dụng khi nhấn phím bổ trợ ĐIỀU KHIỂN TRÁI.
  • rctrl : Áp dụng khi nhấn phím bổ trợ RIGHT Control.
  • meta : Áp dụng khi nhấn phím bổ trợ LEFT META hoặc RIGHT META.
  • lmeta : Áp dụng khi nhấn phím bổ trợ LEFT META.
  • rmeta : Áp dụng khi nhấn phím sửa đổi RIGHT META.
  • sym : Áp dụng khi nhấn phím sửa đổi SYMBOL.
  • fn : Áp dụng khi nhấn phím sửa đổi FUNCTION.
  • capslock : Áp dụng khi công cụ sửa đổi CAPS LOCK bị khóa.
  • numlock : Áp dụng khi công cụ sửa đổi NUM LOCK bị khóa.
  • scrolllock : Áp dụng khi công cụ sửa đổi SCROLL LOCK bị khóa.

Thứ tự liệt kê các thuộc tính là rất quan trọng. Khi ánh xạ khóa tới một hành vi, hệ thống sẽ quét tất cả các thuộc tính có liên quan theo thứ tự và trả về hành vi áp dụng cuối cùng mà nó tìm thấy.

Do đó, các thuộc tính được chỉ định sau sẽ ghi đè các thuộc tính được chỉ định trước đó cho một khóa nhất định.

Hành vi cư xử

Mỗi thuộc tính ánh xạ tới một hành vi. Hành vi phổ biến nhất là gõ một ký tự nhưng cũng có những ký tự khác.

Các hành vi sau đây được công nhận:

  • none : Không gõ một ký tự.

    Hành vi này là mặc định khi không có ký tự nào được chỉ định. Việc chỉ định none là tùy chọn nhưng nó cải thiện sự rõ ràng.

  • 'X' : Nhập ký tự được chỉ định.

    Hành vi này khiến ký tự được chỉ định được nhập vào chế độ xem văn bản tập trung. Ký tự chữ có thể là bất kỳ ký tự ASCII nào hoặc một trong các chuỗi thoát sau:

    • '\\' : Nhập ký tự dấu gạch chéo ngược.
    • '\n' : Nhập ký tự dòng mới (sử dụng ký tự này cho ENTER / RETURN).
    • '\t' : Nhập ký tự TAB.
    • '\'' : Nhập ký tự dấu nháy đơn.
    • '\"' : Nhập ký tự trích dẫn.
    • '\uXXXX' : Nhập ký tự Unicode có điểm mã được cung cấp dưới dạng hex bởi XXXX.

  • fallback <tên mã khóa Android>: Thực hiện hành động mặc định nếu ứng dụng không xử lý khóa.

    Hiện tượng này khiến hệ thống mô phỏng một lần nhấn phím khác khi ứng dụng không xử lý nguyên bản phím được chỉ định. Nó được sử dụng để hỗ trợ hành vi mặc định cho các phím mới mà không phải ứng dụng nào cũng biết cách xử lý, chẳng hạn như ESCAPE hoặc các phím trên bàn phím số (khi không nhấn numlock).

    Khi hành vi dự phòng được thực hiện, ứng dụng sẽ nhận được hai lần nhấn phím: một cho phím gốc và một cho phím dự phòng đã được chọn. Nếu ứng dụng xử lý khóa gốc trong quá trình khóa, thì sự kiện khóa dự phòng sẽ bị hủy ( KeyEvent.isCanceled sẽ trả về true ).

Hệ thống dành sẵn hai ký tự Unicode để thực hiện các chức năng đặc biệt:

  • '\uef00' : Khi hành vi này được thực hiện, chế độ xem văn bản sẽ sử dụng và xóa bốn ký tự trước con trỏ, diễn giải chúng dưới dạng chữ số hex và chèn điểm mã Unicode tương ứng.

  • '\uef01' : Khi hành vi này được thực hiện, chế độ xem văn bản sẽ hiển thị hộp thoại bộ chọn ký tự có chứa các ký hiệu linh tinh.

Hệ thống nhận dạng các ký tự Unicode sau đây là sự kết hợp của các ký tự khóa chết có dấu phụ:

  • '\u0300' : Giọng nghiêm túc.
  • '\u0301' : Giọng cấp tính.
  • '\u0302' : Dấu tròn.
  • '\u0303' : Dấu ngã.
  • '\u0308' : Giọng âm sắc.

Khi một phím chết được gõ theo sau bởi một ký tự khác, phím chết và các ký tự sau sẽ được tạo thành. Ví dụ: khi người dùng gõ một phím chết có dấu huyền theo sau là chữ 'a', kết quả là 'à'.

Tham khảo KeyCharacterMap.getDeadChar để biết thêm thông tin về cách xử lý khóa chết.

Bình luận

Dòng chú thích bắt đầu bằng '#' và tiếp tục đến cuối dòng. Như thế này:

# A comment!

Các dòng trống được bỏ qua.

Cách kết hợp phím được ánh xạ tới hành vi

Khi người dùng nhấn một phím, hệ thống sẽ tra cứu hành vi liên quan đến sự kết hợp giữa thao tác nhấn phím đó và các phím bổ trợ hiện được nhấn.

SHIFT + A

Giả sử người dùng nhấn A và SHIFT cùng nhau. Trước tiên, hệ thống sẽ định vị tập hợp thuộc tính và hành vi được liên kết với KEYCODE_A .

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Hệ thống quét các thuộc tính từ đầu đến cuối và từ trái sang phải, bỏ qua các thuộc tính label và number là những thuộc tính đặc biệt.

Thuộc tính đầu tiên gặp phải là base . Thuộc tính base luôn áp dụng cho một khóa, bất kể phím bổ trợ nào được nhấn. Về cơ bản, nó chỉ định hành vi mặc định cho khóa trừ khi nó bị ghi đè bởi các thuộc tính sau. Vì thuộc tính base áp dụng cho lần nhấn phím này nên hệ thống sẽ lưu ý rằng hành vi của nó là 'a' (nhập ký tự a ).

Sau đó, hệ thống tiếp tục quét các thuộc tính tiếp theo trong trường hợp bất kỳ thuộc tính nào trong số chúng cụ thể hơn base và ghi đè lên nó. Nó gặp phải shift cũng áp dụng cho phím nhấn SHIFT + A. Vì vậy, hệ thống quyết định bỏ qua hành vi của thuộc tính base và chọn hành vi liên quan đến thuộc tính shift , đó là 'A' (nhập ký tự A ).

Sau đó, nó tiếp tục quét bảng, tuy nhiên không có thuộc tính nào khác áp dụng cho lần nhấn phím này (CAPS LOCK không bị khóa, không có phím ĐIỀU KHIỂN nào được nhấn, không có phím ALT nào được nhấn và cũng không có phím META nào được nhấn).

Vì vậy, hành vi kết quả của tổ hợp phím SHIFT + A là 'A' .

KIỂM SOÁT + A

Bây giờ hãy xem xét điều gì sẽ xảy ra nếu người dùng nhấn A và KIỂM SOÁT cùng nhau.

Như trước đây, hệ thống sẽ quét bảng thuộc tính. Nó sẽ nhận thấy rằng thuộc tính base được áp dụng nhưng cũng sẽ tiếp tục quét cho đến khi đạt đến thuộc tính control . Khi điều đó xảy ra, thuộc tính control xuất hiện sau base nên hành vi của nó sẽ ghi đè hành vi base .

Vì vậy, hành vi kết quả đối với tổ hợp phím Control + A là none .

BỎ TRỐN

Bây giờ giả sử người dùng nhấn ESCAPE.

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

Lần này hệ thống nhận được hành vi fallback BACK , một hành vi dự phòng. Bởi vì không có ký tự nào xuất hiện nên sẽ không có ký tự nào được gõ.

Khi xử lý khóa, trước tiên hệ thống sẽ phân KEYCODE_ESCAPE cho ứng dụng. Nếu ứng dụng không xử lý được thì hệ thống sẽ thử lại nhưng lần này nó sẽ gửi KEYCODE_BACK đến ứng dụng theo yêu cầu của hành vi dự phòng.

Vì vậy, các ứng dụng nhận dạng và hỗ trợ KEYCODE_ESCAPE có cơ hội xử lý nguyên trạng nhưng các ứng dụng khác không thể thực hiện hành động dự phòng là xử lý khóa như thể nó là KEYCODE_BACK .

NUMPAD_0 có hoặc không có NUM LOCK

Các phím trên bàn phím số có cách hiểu rất khác nhau tùy thuộc vào việc phím NUM LOCK có bị khóa hay không.

Khai báo khóa sau đây đảm bảo rằng KEYCODE_NUMPAD_0 loại 0 khi nhấn NUM LOCK. Khi không nhấn NUM LOCK, khóa sẽ được gửi đến ứng dụng như bình thường và nếu nó không được xử lý thì khóa dự phòng KEYCODE_INSERT sẽ được gửi thay thế.

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

Như chúng ta có thể thấy, việc khai báo khóa dự phòng cải thiện đáng kể khả năng tương thích với các ứng dụng cũ không nhận dạng hoặc hỗ trợ trực tiếp tất cả các phím có trên bàn phím kiểu PC đầy đủ.

Ví dụ

Bàn phím đầy đủ

# 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
}

Bàn phím chữ và số

# 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'
}

Bàn chơi game

# 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
}

Ghi chú tương thích

Trước Android Honeycomb 3.0, bản đồ ký tự khóa Android được chỉ định bằng cú pháp rất khác và được biên dịch thành định dạng tệp nhị phân ( .kcm.bin ) tại thời điểm xây dựng.

Mặc dù định dạng mới sử dụng cùng phần mở rộng .kcm nhưng cú pháp khá khác (và mạnh hơn nhiều).

Kể từ Android Honeycomb 3.0, tất cả các tệp bản đồ ký tự chính của Android phải sử dụng cú pháp mới và định dạng tệp văn bản thuần túy được mô tả trong tài liệu này. Cú pháp cũ không được hỗ trợ và các tệp .kcm.bin cũ không được hệ thống nhận dạng.

Lưu ý ngôn ngữ

Android hiện không hỗ trợ bàn phím đa ngôn ngữ. Hơn nữa, bản đồ ký tự khóa chung được tích hợp sẵn giả định bố cục bàn phím tiếng Anh Mỹ.

OEM được khuyến khích cung cấp bản đồ ký tự phím tùy chỉnh cho bàn phím của họ nếu chúng được thiết kế cho các ngôn ngữ khác.

Các phiên bản Android trong tương lai có thể hỗ trợ tốt hơn cho bàn phím đa ngôn ngữ hoặc bố cục bàn phím do người dùng lựa chọn.

Thẩm định

Đảm bảo xác thực các tệp bản đồ ký tự chính của bạn bằng công cụ Xác thực sơ đồ bàn phím .