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

Các 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 phím mã phím Android có đối tượng sửa đổi thành các ký tự Unicode.

Các tệp bố cục khoá dành riêng cho thiết bị là bắt buộc đối với tất cả các tệp nội bộ (tích hợp) thiết bị đầu vào có khoá, nếu chỉ để cho hệ thống biết rằng thiết bị chỉ dùng 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 bên 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ị nào, thì hệ thống sẽ hãy chọn một ứng dụng mặc định.

Vị trí

Tệp bản đồ ký tự chính được định vị theo nhà cung cấp USB, sản phẩm (và phiên bản không bắt buộc) id hoặc theo tên thiết bị đầu vào.

Các đường dẫn sau đượ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ả 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 ánh xạ ký tự chính chung

Hệ thống cung cấp một tệp ánh xạ ký tự phím đặc biệt được tích hợp sẵn có tên là Generic.kcm. Sơ đồ ký tự chính này nhằm hỗ trợ nhiều tiêu chuẩn bên ngoài bàn phím.

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

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

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

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

Đừng sửa đổi sơ đồ ký tự khoá ảo!

Cú pháp

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

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

Phần khai báo loại bàn phím mô tả hành vi chung của bàn phím. Tệp ánh xạ ký tự phải chứa khai báo loại bàn phím. Để cho rõ ràng, phần này thường được đặt ở đầu tệp.

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 phương pháp nhấn nhiều lần. Bạn có thể cần phải nhấn vào một phím nhiều lần để tạo chữ cái hoặc biểu tượng 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 chứa tất cả chữ cái nhưng có nhiều chữ cái trên mỗi phím.

    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ả chữ cái và có thể là một vài chữ số.

    Bàn phím chữ cái hỗ trợ trực tiếp việc nhập văn bản nhưng có thể có một ký tự rút gọn có kiểu dáng nhỏ gọn. Trái ngược với bàn phím FULL, một số chỉ có thể truy cập vào các biểu tượng 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 độ nhập và độ chính xác, khung này còn cung cấp các thành phần tương tác đặc biệt cho bàn phím chữ cái như tự động viết hoa và bật/tắt/bị 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 như bàn phím máy tính. Bạn có thể truy cập trực tiếp vào tất cả các biểu tượng bằng cách nhấn các phím trên bàn phím không có tính năng hỗ trợ trên màn hình hoặc các thành phần tương tác như làm tự động viết hoa.

    Loại bàn phím này thường được thiết kế để nhập toàn bộ bằng 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 được, chẳng hạn như HOME và POWER không thực sự được dùng để nhập dữ liệu.

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

Nội dung khai báo khoá

Mỗi nội dung khai báo khoá bao gồm từ khoá key, theo sau là một 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à một 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ột mối liên kết từ một khoá đến một hành vi. Để giúp tệp ánh xạ ký tự chính gọn gàng hơn, một vài thuộc tính có thể được ánh xạ tới bằng cách dùng dấu phẩy để phân tách chúng.

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 được công nhận:

  • label: Chỉ định nhãn được in thực trên khoá khi có một ký tự duy nhất. Đâ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 nhập) khi một số chế độ xem văn bản tập trung vào 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 thành một phím duy nhất, để có thể dùng cùng một khoá để nhập '1' và 'a' hoặc '#' và 'q'. Đối với các khoá này, bạn phải đặt thuộc tính number để cho biết ký hiệu nào phải được nhập văn bản dạng số, nếu có.

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

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

  • <đối tượng sửa đổi> hoặc <modifier1>+<modifier2>+...: Chỉ định hành vi (ký tự cần nhập) khi nhấn phím và tất cả đối tượng sửa đổi được chỉ định đ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 cần nhấn phím bổ trợ LEFT SHIFT hoặc RIGHT SHIFT.

    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 cả hai phím bổ trợ RIGHT SHIFT và RIGHT ALT được nhấn đồng thời.

Các đối tượng sửa đổi sau đây được công nhận trong các thuộc tính đối tượng 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 người dùng 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 ALT ALT.
  • lalt: Áp dụng khi người dùng nhấn phím bổ trợ LEFT ALT.
  • ralt: Áp dụng khi nhấn phím bổ trợ ALT PHẢI.
  • ctrl: Áp dụng khi nhấn phím bổ trợ Điều khiển TRÁI hoặc KIỂM SOÁT PHẢI.
  • lctrl: Áp dụng khi nhấn đối tượng sửa đổi LEFT CONTROL.
  • rctrl: Áp dụng khi nhấn phím bổ trợ ĐIỀU KHIỂN PHẢI.
  • meta: Áp dụng khi nhấn phím bổ trợ LEFT META hoặc META META.
  • lmeta: Áp dụng khi người dùng nhấn phím bổ trợ LEFT META.
  • rmeta: Áp dụng khi người dùng nhấn phím bổ trợ META PHẢI.
  • sym: Áp dụng khi nhấn đối tượng sửa đổi SYMBOL.
  • fn: Áp dụng khi người dùng nhấn đối tượng sửa đổi FUNCTION.
  • capslock: Áp dụng khi đối tượng 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 phím bổ trợ CUỘN LOCK bị khoá.

Thứ tự liệt kê các cơ sở lưu trú là rất quan trọng. Khi ánh xạ khoá đến thì 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ề thuộc tính cuối cùng hành vi có thể áp dụng mà công cụ tìm thấy.

Do đó, các thuộc tính được chỉ định sau này sẽ ghi đè các thuộc tính đang được chỉ định trước đó cho khoá cụ thể.

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 ký tự nhưng vẫn có những người khác.

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

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

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

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

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

    • '\\': Nhập ký tự dấu gạch chéo ngược.
    • '\n': Nhập một ký tự dòng mới (sử dụng ký tự này cho ENTER / TRẢ LẠI).
    • '\t': Nhập ký tự TAB.
    • '\'': Nhập một ký tự dấu nháy đơn.
    • '\"': Nhập một ký tự trích dẫn.
    • '\uXXXX': Nhập ký tự Unicode có điểm mã được xác định theo hệ thập lục phân x XXXX.

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

    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 một ứng dụng không xử lý khoá được chỉ định một cách tự nhiên. Tham số này được dùng để hỗ trợ hành vi mặc định cho các khoá 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 phím số).

    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 cho khoá ban đầu và một cho khoá dự phòng đã chọn. Nếu ứng dụng xử lý khoá gốc trong quá trình khởi động khoá, thì khoá dự phòng sự kiện 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 hàm đặc biệt:

  • '\uef00': Khi hành vi này được thực hiện, khung 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 chúng dưới dạng số hex và chèn điểm mã Unicode tương ứng.

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

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

  • '\u0300': Dấu huyền.
  • '\u0301': Giọng cấp tính.
  • '\u0302': Dấu mũ.
  • '\u0303': Dấu sóng.
  • '\u0308': Giọng Umlaut.

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

Hãy tham khảo KeyCharacterMap.getDeadChar để biết thêm thông tin về cách xử lý khoá bị hỏng.

Bình luận

Các dòng nhận xét bắt đầu bằng "#" và tiếp tục đến cuối dòng. Chẳng hạn như:

# A comment!

Hệ thống sẽ bỏ qua các dòng trống.

Cách liên kết các 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 quan đến tổ hợp phím nhấn phím đó với 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 xác định được tập hợp các 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. Đây là những thuộc tính đặc biệt.

Thuộc tính đầu tiên bạn gặp phải là base. Thuộc tính base luôn áp dụng cho một phím, bất kể bạn nhấn phím bổ trợ nào. Về cơ bản, API này chỉ định giá trị mặc định cho khoá trừ khi bị các thuộc tính sau ghi đè. 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ẽ ghi chú cho thấy hành vi của hàm là 'a' (nhập ký tự a).

Sau đó, hệ thống sẽ tiếp tục quét các tài sản tiếp theo nếu có bất kỳ tài sản nào cụ thể hơn base và ghi đè lên. Hàm này gặp shift cũng áp dụng cho thao tác nhấn 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 được liên kết với thuộc tính shift, đó là 'A' (nhập ký tự A).

Sau đó, Trợ lý sẽ tiếp tục quét bảng, nhưng không có thuộc tính nào khác áp dụng cho lệnh này nhấn phím (CAPS LOCK không được khoá, không có phím CONTROL được nhấn, cả hai phím này không Nhấn phím ALT và không nhấn phím META).

Vì vậy, hành vi thu được cho tổ hợp phím SHIFT + A là 'A'.

ĐIỀU KHIỂN + A

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

Như trước đây, hệ thống sẽ quét bảng cơ sở lưu trú. Bạn sẽ nhận thấy đã áp dụng thuộc tính base nhưng cũng sẽ tiếp tục quét cho đến cuối cùng nó vẫn đến thuộc tính control. Khi điều đó xảy ra, control thuộc tính này xuất hiện sau base, vì vậy hành vi của thuộc tính đó sẽ ghi đè hành vi base.

Vì vậy, hành vi thu được 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ẽ lấy hành vi fallback BACK, một hành vi dự phòng. Vì không có ký tự 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 đến . Nếu ứng dụng không xử lý, thì hệ thống sẽ thử nhưng lần này sẽ phân phối KEYCODE_BACK đến ứng dụng dưới dạng mà hành vi dự phòng yêu cầu.

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

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

Cách diễn giải của các phím trên bàn phím số rất khác nhau, tuỳ thuộc vào việc khoá NUM LOCK đã bị khoá.

Nội dung khai báo khoá sau đây đảm bảo rằng KEYCODE_NUMPAD_0 loại 0 khi nhấn NUM LOCK. Khi không được nhấn NUM LOCK, khoá sẽ được chuyển vào ứng dụng như bình thường và nếu không được xử lý thì phương thức dự phòng thay vào đó, khoá KEYCODE_INSERT sẽ được gửi đ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 khoá 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ũ hơn 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 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 cầm đ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, sơ đồ ký tự phím của Android được chỉ định bằng cách sử dụ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 phần mở rộng .kcm, cú pháp 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ự phím 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 tuý được mô tả trong tài liệu này. Cú pháp cũ không được hỗ trợ và tệp .kcm.bin cũ không được nhận dạng bị hệ thống tạo ra.

Ghi chú ngôn ngữ

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

OEM nên cung cấp bản đồ ký tự phím tuỳ chỉnh cho bàn phím 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ể sẽ tăng cường hỗ trợ bàn phím đa ngôn ngữ hoặc bố cục bàn phím mà người dùng có thể chọn.

Xác nhận kết quả

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