Tệp sơ đồ ký tự chính

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tệp bản đồ ký tự phím (tệp .kcm) chịu trách nhiệm liên kết các tổ hợp mã phím Android với đối tượng sửa đổi cho ký tự Unicode.

Bạn bắt buộc phải có tệp bố cục phím dành riêng cho thiết bị đối với tất cả thiết bị đầu vào nội bộ (tích hợp) có phím, nếu chỉ để cho hệ thống biết rằng thiết bị đó 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à không bắt buộc đối với bàn phím ngoài và thường không cần thiết. Hệ thống cung cấp một 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ó tệp bố cục phím dành riêng cho thiết bị, thì hệ thống sẽ chọn một bố cục mặc định.

Vị trí

Các tệp bản đồ ký tự phím được tìm theo mã nhận dạng nhà cung cấp USB, sản phẩm (và phiên bản tuỳ 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 tạo đường dẫn tệp chứa tên thiết bị, tất cả ký tự trong tên thiết bị ngoại trừ "0"-"9", "a"-"z", "A"-"Z", "-" hoặc "_" sẽ được thay thế bằng "_".

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

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

Đừng sửa đổi bản đồ ký tự khoá chung!

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

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

Thiết bị bàn phím ảo là một thiết bị nhập dữ liệu tổng hợp có mã nhận dạng là -1 (xem KeyCharacterMap.VIRTUAL_KEYBOARD). Thiết bị này có 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ể dùng để chèn thao tác nhấn phím vào ứng dụng bằng IME hoặc bằng thiết bị đo lường thử nghiệm, 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 giả định có bố cục QWERTY đầy đủ giống nhau trên tất cả thiết bị. Điều này cho phép các ứng dụng chèn thao tác nhấn phím bằng cách sử dụng thiết bị bàn phím ảo và luôn nhận được kết quả giống nhau.

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

Cú pháp

Tệp bản đồ ký tự phím là một tệp văn bản thuần tuý bao gồm phần khai báo loại bàn phím và một tập hợp các phần khai báo phím.

Khai báo loại bàn phím

Nội dung 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 nội dung khai báo loại bàn phím. Để rõ ràng, thường đặt phần này ở đầu tệp.

type FULL

Các loại bàn phím sau đây đượ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 phương pháp nhấn nhiều lần. Bạn có thể phải nhấn vào một phím nhiều lần để tạo 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ế để nhập 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 mỗi phím có nhiều chữ cái.

  Loại bàn phím này thường được thiết kế để nhập 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ể có một số chữ 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 thu gọn với kích thước nhỏ. Trái ngược với bàn phím FULL, một số biểu tượng có thể chỉ truy cập được bằ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 nhập, khung này cung cấp các tính năng đặc biệt cho bàn phím chữ cái, chẳng hạn như tự động viết hoa và bật / khoá phím SHIFT và ALT.

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

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

  Bàn phím đầy đủ hoạt động giống như bàn phím máy tính. Tất cả các ký hiệ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ợ hoặc các tính năng trên màn hình như tự động viết hoa.

  Loại bàn phím này thường được thiết kế để nhập bằng cả hai tay.

• SPECIAL_FUNCTION: Bàn phím chỉ dùng để thực hiện các chức năng điều khiển hệ thống thay vì để nhập.

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

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

Khai báo khoá

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

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

Thuộc tính

Mỗi thuộc tính khoá thiết lập mối liên kết từ khoá đến hành vi. Để làm cho các tệp bản đồ ký tự chính trở nên nhỏ gọn hơn, bạn có thể liên kết một số thuộc tính với cùng một hành vi bằng cách phân tách các thuộc tính đó 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ự, các thuộc tính ctrl, alt và meta đều được chỉ định đồng thời hành vi none.

Các thuộc tính sau đây được nhận dạng:

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

• number: Chỉ định hành vi (ký tự cần nhập) khi thành phần hiển thị 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 thu gọn thường kết hợp nhiều ký hiệu vào một phím duy nhất, chẳng hạn như có thể sử dụng cùng một phím để nhập '1' và 'a' hoặc '#' và 'q'. Đối với các khoá này, bạn nên đặt thuộc tính number để cho biết ký hiệu nào cần được nhập trong ngữ cảnh số (nếu có).

  Một số ký hiệu "số" thông thường là các chữ số '0' đến '9', '#', '+', '(', ')', ',' và '.'.

• base: Chỉ định hành vi (ký tự cần nhập) khi không nhấn phím sửa đổi nào.

• <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 đối tượng sửa đổi được chỉ định đều đang hoạt động.

  Ví dụ: thuộc tính đối tượng sửa đổi shift chỉ định một hành vi áp dụng khi nhấn phím sửa đổi SHIFT TRÁI hoặc SHIFT PHẢI.

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

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

• shift: Áp dụng khi nhấn phím bổ trợ SHIFT TRÁI hoặc SHIFT PHẢI.
• lshift: Áp dụng khi nhấn phím bổ trợ SHIFT BÊN TRÁI.
• rshift: Áp dụng khi nhấn phím sửa đổi SHIFT PHẢI.
• alt: Áp dụng khi nhấn phím bổ trợ ALT TRÁI hoặc ALT PHẢI.
• lalt: Áp dụng khi nhấn phím sửa đổi ALT BÊN TRÁI.
• ralt: Áp dụng khi nhấn phím sửa đổi ALT PHẢI.
• ctrl: Áp dụng khi nhấn phím bổ trợ LEFT CONTROL (CTRL trái) hoặc RIGHT CONTROL (CTRL phải).
• lctrl: Áp dụng khi nhấn phím sửa đổi LEFT CONTROL (KIỂM SOÁT TRÁI).
• rctrl: Áp dụng khi nhấn phím sửa đổi RIGHT CONTROL (KIỂM SOÁT PHẢI).
• meta: Áp dụng khi nhấn phím sửa đổi META TRÁI hoặc META PHẢI.
• lmeta: Áp dụng khi nhấn phím sửa đổi META BÊN TRÁI.
• rmeta: Áp dụng khi nhấn phím sửa đổi META PHẢI.
• sym: Áp dụng khi nhấn đối tượng sửa đổi SYMBOL.
• fn: Áp dụng khi nhấn phím sửa đổi FUNCTION (Hàm).
• capslock: Áp dụng khi phím sửa đổi CAPS LOCK bị khoá.
• numlock: Áp dụng khi đối tượng sửa đổi NUM LOCK bị khoá.
• scrolllock: Áp dụng khi đối tượng sửa đổi SCROLL LOCK (Khoá cuộn) bị khoá.

Thứ tự liệt kê các thuộc tính rất quan trọng. Khi liên kết một khoá vớ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 có thể áp dụng gần đây nhất mà hệ thống 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 khoá nhất định.

Thao tác

Mỗi thuộc tính liên kết với một hành vi. Hành vi phổ biến nhất là nhập một ký tự, nhưng cũng có những hành vi khác.

Hệ thống nhận dạng được các hành vi sau:

• none: Không nhập ký tự.

  Hành vi này là mặc định khi không chỉ định ký tự nào. Bạn không bắt buộc phải chỉ định none nhưng việc này sẽ giúp tăng độ rõ ràng.

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

  Hành vi này sẽ khiến ký tự đã chỉ định được nhập vào thành phần hiển thị văn bản được lấy tiêu điểm. Ký tự cố định có thể là bất kỳ ký tự ASCII nào hoặc một trong các trình tự thoát sau:

  • '\\': Nhập ký tự dấu gạch chéo ngược.
  • '\n': Nhập ký tự dòng mới (dùng cho ENTER / RETURN).
  • '\t': Nhập ký tự TAB.
  • '\'': Nhập ký tự dấu nháy đơn.
  • '\"': Nhập ký tự dấu ngoặc kép.
  • '\uXXXX': Nhập ký tự Unicode có điểm mã được cung cấp theo hệ thập lục phân bằng XXXX.

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

  Hành vi này khiến hệ thống mô phỏng một thao tác nhấn phím khác khi ứng dụng không xử lý phím được chỉ định theo cách gốc. Phương thức này được 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ư phím ESCAPE hoặc phím số trên bàn phím (khi không nhấn phím numlock).

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

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

• '\uef00': Khi thực hiện hành vi này, thành phần hiển thị văn bản sẽ sử dụng và xoá bốn ký tự đứng trước con trỏ, diễn giải các ký tự đó dưới dạng chữ số thập lục phân và chèn điểm mã Unicode tương ứng.

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

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

• '\u0300': Dấu trọng âm.
• '\u0301': Dấu sắc.
• '\u0302': Dấu mũ.
• '\u0303': Dấu trọng âm dấu ngã.
• '\u0308': Dấu trọng âm dấu hai chấm.

Khi bạn nhập một phím chết, theo sau là một ký tự khác, phím chết và các ký tự sau đó sẽ được kết hợp. Ví dụ: khi người dùng nhập phím dấu trọng âm grave, theo sau là chữ cái "a", kết quả sẽ là "à".

Tham khảo KeyCharacterMap.getDeadChar để biết thêm thông tin về cách xử lý phím không hoạt động.

Bình luận

Dòng nhận xét bắt đầu bằng "#" và tiếp tục đến cuối dòng. Ví dụ:

# A comment!

Các dòng trống sẽ bị bỏ qua.

Cách liên kết tổ hợp phím vớ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 kết với tổ hợp nhấn phím đó và các phím sửa đổi đang được nhấn.

SHIFT + A

Giả sử người dùng nhấn đồng thời phím A và SHIFT. Trước tiên, hệ thống sẽ xác định vị trí của nhóm thuộc tính và hành vi 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 đặ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 khoá, bất kể bạn nhấn phím sửa đổi nào. Về cơ bản, thuộc tính này chỉ định hành vi mặc định cho khoá, trừ phi hành vi này bị ghi đè bởi các thuộc tính sau. Vì thuộc tính base áp dụng cho thao tác nhấn phím này, nên hệ thống sẽ lưu ý rằng hành vi của thao tác này là 'a' (nhập ký tự a).

Sau đó, hệ thống sẽ 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ố đó cụ thể hơn base và ghi đè thuộc tính này. Phương thức này gặp shift cũng áp dụng cho tổ hợp phím 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 kết với thuộc tính shift, đó là 'A' (nhập ký tự A).

Sau đó, hàm này 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 thao tác nhấn phím này (CAPS LOCK không bị khoá, không nhấn phím CONTROL, không nhấn phím ALT và không nhấn phím META).

Do đó, hành vi kết quả cho tổ hợp phím SHIFT + A là 'A'.

CONTROL + A

Bây giờ, hãy xem xét điều gì sẽ xảy ra nếu người dùng nhấn đồng thời phím A và CONTROL.

Giống như trước đây, hệ thống sẽ quét bảng thuộc tính. Phương thức này sẽ nhận thấy 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 này xảy ra, thuộc tính control sẽ xuất hiện sau base, vì vậy, hành vi của thuộc tính này sẽ ghi đè hành vi của base.

Vì vậy, hành vi kết quả cho tổ hợp phím CONTROL + A là none.

PHÍM ESCAPE

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

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

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

Khi xử lý khoá, trước tiên, hệ thống sẽ phân phối KEYCODE_ESCAPE cho ứng dụng. Nếu ứng dụng không xử lý, thì hệ thống sẽ thử lại nhưng lần này sẽ phân phối KEYCODE_BACK cho ứ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ý như hiện tại, nhưng các ứng dụng khác không thể thực hiện thao tác dự phòng là coi khoá như thể 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 diễn giải rất khác nhau tuỳ thuộc vào việc phím NUM LOCK có bị khoá hay không.

Nội dung khai báo khoá sau đây đảm bảo rằng KEYCODE_NUMPAD_0 nhập 0 khi nhấn phím NUM LOCK. Khi không nhấn phím NUM LOCK, phím sẽ được phân phối đến ứng dụng như bình thường và nếu không được xử lý, thì phím dự phòng KEYCODE_INSERT sẽ được phân phối.

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 phím dự phòng giúp 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 không hỗ trợ trực tiếp tất cả các phím có trên bàn phím kiểu máy tính đầ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'
}

Tay điều khiển trò chơi

# 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ú về khả năng tương thích

Trước Android Honeycomb 3.0, bản đồ ký tự phím Android được chỉ định bằng một 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 tạo bản dựng.

Mặc dù định dạng mới sử dụng cùng một đuôi tệp .kcm, nhưng cú pháp lại khá khác biệt (và mạnh mẽ hơn nhiều).

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

Lưu ý về 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ự phím chung tích hợp sẵn giả định bố cục bàn phím tiếng Anh Hoa Kỳ.

Các nhà sản xuất thiết bị gốc (OEM) nên cung cấp bản đồ ký tự phím tuỳ chỉnh cho bàn phím của họ nếu bàn phím đượ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 chọn.

Xác nhận kết quả

Hãy nhớ xác thực các tệp bản đồ ký tự chính bằng công cụ Xác thực bản đồ phím.