Od 27 marca 2025 r. zalecamy używanie android-latest-release zamiast aosp-main do kompilowania i wspołtworzenia AOSP. Więcej informacji znajdziesz w artykule o zmianach w AOSP.

Ta strona została przetłumaczona przez Cloud Translation API.

Pliki mapy klawiszy
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Pliki mapy znaków klucza (pliki .kcm) odpowiadają za mapowanie kombinacji kodów klawiszy Androida z modyfikatorami na znaki Unicode.

Pliki układu klawiszy dla poszczególnych urządzeń są wymagane w przypadku wszystkich wewnętrznych (wbudowanych) urządzeń wejściowych, które mają klawisze, nawet jeśli tylko po to, aby poinformować system, że urządzenie ma specjalne przeznaczenie (nie jest pełną klawiaturą).

Pliki układu klawiszy dla poszczególnych urządzeń są opcjonalne w przypadku klawiatur zewnętrznych i często wcale nie są potrzebne. System udostępnia ogólną mapę znaków klawiszy, która jest odpowiednia dla wielu klawiatur zewnętrznych.

Jeśli nie ma dostępnego pliku układu klawiszy dla danego urządzenia, system wybierze domyślny.

Lokalizacja

Pliki mapy znaków kluczy są zlokalizowane według identyfikatora dostawcy USB, identyfikatora produktu (i opcjonalnie wersji) lub nazwy urządzenia wejściowego.

Poniższe ścieżki są sprawdzane kolejno.

/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

Podczas tworzenia ścieżki pliku zawierającej nazwę urządzenia wszystkie znaki w nazwie urządzenia inne niż „0–9”, „a–z”, „A–Z”, „–” lub „_” są zastępowane znakiem „_”.

Plik z mapą znaków klucza ogólnego

System udostępnia specjalny wbudowany plik mapy znaków klucza o nazwie Generic.kcm. Ta mapa klawiszy ma obsługiwać różne standardowe klawiatury zewnętrzne.

Nie modyfikuj mapy znaków klucza ogólnego.

Plik mapy znaków karty wirtualnej

System udostępnia specjalny wbudowany plik mapy znaków klawiszy o nazwie Virtual.kcm, który jest używany przez wirtualne klawiatury.

Klawiatura wirtualna to syntetyczne urządzenie wejściowe o identyfikatorze -1 (zob. KeyCharacterMap.VIRTUAL_KEYBOARD). Jest dostępne na wszystkich urządzeniach z Androidem, począwszy od Androida Honeycomb 3.0. Celem urządzenia z klawiaturą wirtualną jest zapewnienie znanego wbudowanego urządzenia wejściowego, które może być używane do wstawiania w aplikacji naciśnięć klawiszy przez IME lub narzędzia testowe, nawet na urządzeniach bez wbudowanej klawiatury.

Zakłada się, że klawiatura wirtualna ma pełny układ QWERTY, który jest taki sam na wszystkich urządzeniach. Dzięki temu aplikacje mogą wstawiać naciśnięcia klawiszy za pomocą klawiatury wirtualnej i zawsze uzyskiwać te same wyniki.

Nie modyfikuj mapy znaków klawisza wirtualnego.

Składnia

Plik mapy znaków klucza to zwykły plik tekstowy zawierający deklarację typu klawiatury i zestaw deklaracji kluczy.

Deklaracja typu klawiatury

Deklaracja typu klawiatury opisuje ogólne działanie klawiatury. Plik mapy znaków musi zawierać deklarację typu klawiatury. Dla ułatwienia jest ona często umieszczana u góry pliku.

type FULL

Obsługiwane są te typy klawiatur:

NUMERIC: klawiatura numeryczna (12 klawiszy).

Klawiatura numeryczna umożliwia wpisywanie tekstu za pomocą wielu dotknięć. Aby wygenerować odpowiednią literę lub symbol, może być konieczne kilkakrotne naciśnięcie klawisza.

Ten typ klawiatury jest zazwyczaj przeznaczony do pisania kciukiem.

Odpowiada KeyCharacterMap.NUMERIC.
PREDICTIVE: klawiatura z wszystkimi literami, ale z większą liczbą liter na klawisz.

Ten typ klawiatury jest zazwyczaj przeznaczony do pisania kciukiem.

Odpowiada KeyCharacterMap.PREDICTIVE.
ALPHA: klawiatura ze wszystkimi literami i kilkoma cyframi.

Klawiatura alfabetyczna umożliwia bezpośrednie wpisywanie tekstu, ale może mieć skompresowany układ w małym formacie. W przeciwieństwie do klawiatury FULL niektóre symbole mogą być dostępne tylko za pomocą specjalnych selektorów znaków na ekranie. Aby zwiększyć szybkość i dokładność pisania, framework udostępnia też specjalne funkcje dla klawiatur alfabetycznych, takie jak automatyczne stosowanie wielkich liter i przełączanie / blokowanie klawiszy SHIFT i ALT.

Ten typ klawiatury jest zazwyczaj przeznaczony do pisania kciukiem.
FULL: pełna klawiatura w stylu komputerowym.

Pełna klawiatura działa jak klawiatura komputera. Do wszystkich symboli można uzyskać dostęp bezpośrednio, naciskając klawisze na klawiaturze bez obsługi na ekranie lub funkcji takich jak automatyczne wielkości liter.

Ten typ klawiatury jest zwykle przeznaczony do pisania dwoma rękami.
SPECIAL_FUNCTION: klawiatura używana tylko do wykonywania funkcji sterowania systemem, a nie do pisania.

Specjalna klawiatura funkcyjna składa się tylko z klawiszy niewydrukowalnych, takich jak HOME i POWER, które nie są używane do pisania.

Mapy klawiszy Generic.kcm i Virtual.kcm to obie klawiatury FULL.

Deklaracje kluczy

Deklaracje kluczy składają się z kluczowego słowa key, po którym następuje nazwa kodu klucza Androida, otwierająca klamra klamra klamra, zestaw właściwości i zachowań oraz klamra zamykająca.

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

Właściwości

Każda właściwość klucza określa mapowanie klucza na zachowanie. Aby pliki mapy kluczy znaków były bardziej zwarte, można przypisać kilka właściwości do tego samego zachowania, rozdzielając je przecinkami.

W tym przykładzie właściwości label przypisano zachowanie 'A'. Podobnie właściwości ctrl, alt i meta są jednocześnie przypisane do zachowania none.

Rozpoznawane są te właściwości:

label: określa etykietę wydrukowaną na kluczu, gdy składa się on z jednego znaku. Jest to wartość zwracana przez metodę KeyCharacterMap.getDisplayLabel.
number: określa zachowanie (znak, który powinien zostać wpisany) w przypadku widoku tekstu numerycznego, który ma fokus, np. gdy użytkownik wpisują numer telefonu.

Klawiatury kompaktowe często łączą kilka symboli w jedną klawisz, tak aby można było wpisywać '1' i 'a' lub '#' i 'q' za pomocą tej samej klawisza. W przypadku tych kluczy należy ustawić właściwość number, aby wskazać, który symbol należy wpisać w kontekście liczbowym (jeśli taki istnieje).

Niektóre typowe „cyfry” to cyfry od '0' do '9', '#', '+', '(', ')', ',' i '.'.
base: określa działanie (znak, który powinien zostać wpisany), gdy nie naciśnięto żadnych klawiszy modyfikujących.
<modifier> lub <modifier1>+<modifier2>+...: określa działanie (znak, który powinien zostać wpisany) po naciśnięciu klawisza i aktywowaniu wszystkich określonych modyfikatorów.

Na przykład właściwość modyfikatora shift określa zachowanie, które ma zastosowanie, gdy naciśnięty jest modyfikator LEWY SHIFT lub PRAWY SHIFT.

Podobnie właściwość modyfikatora rshift+ralt określa zachowanie, które ma zastosowanie, gdy jednocześnie naciśnięto oba modyfikatory PRAWY SHIFT i PRAWY ALT.

Właściwości modyfikatorów rozpoznają te modyfikatory:

shift: dotyczy sytuacji, gdy naciśnięty jest klawisz modyfikujący LEWY SHIFT lub PRAWY SHIFT.
lshift: dotyczy się, gdy naciśnięty jest klawisz modyfikujący LEWY SHIFT.
rshift: ma zastosowanie, gdy naciśnięty jest klawisz modyfikujący PRAWY SHIFT.
alt: ma zastosowanie, gdy naciśnięty jest lewy lub prawy klawisz ALT.
lalt: ma zastosowanie, gdy naciśnięty jest modyfikator ALT LEWY.
ralt: dotyczy sytuacji, gdy naciśnięty jest modyfikator PRAWY ALT.
ctrl: ma zastosowanie, gdy naciśnięty jest klawisz modyfikujący LEWY CTRL lub PRAWY CTRL.
lctrl: ma zastosowanie, gdy naciśnięty jest klawisz modyfikujący CTRL LEWY.
rctrl: ma zastosowanie, gdy naciśnięty jest klawisz modyfikujący PRAWY CTRL.
meta: stosuje się, gdy naciśnięty jest modyfikator LEWY META lub PRAWY META.
lmeta: ma zastosowanie, gdy naciśnięty jest lewy klawisz META.
rmeta: dotyczy sytuacji, gdy naciśnięty jest klawisz prawy.
sym: ma zastosowanie, gdy naciśnięty jest modyfikator SYMBOL.
fn: ma zastosowanie, gdy naciśnięty jest klawisz FUNCTION.
capslock: dotyczy, gdy klawisz Caps Lock jest włączony.
numlock: ma zastosowanie, gdy modyfikator NUM LOCK jest zablokowany.
scrolllock: ma zastosowanie, gdy modyfikator SCROLL LOCK jest zablokowany.

Kolejność, w której wymienione są usługi, ma znaczenie. Podczas mapowania klucza na zachowanie system skanuje wszystkie odpowiednie właściwości w kolejności i zwraca ostatnie znalezione odpowiednie zachowanie.

W konsekwencji właściwości określone później zastępują właściwości określone wcześniej dla danego klucza.

Zachowania

Każda właściwość jest mapowana na zachowanie. Najczęstszym działaniem jest wpisywanie znaku, ale istnieją też inne.

Rozpoznawane są następujące zachowania:

none: nie wpisuj znaku.

Jest to zachowanie domyślne, gdy nie określono żadnego znaku. Podanie wartości none jest opcjonalne, ale zwiększa przejrzystość.
'X': wpisz określony znak dosłowny.

Dzięki temu określonemu znakowi zostanie przypisany fokus w widoku tekstu. Znak może być dowolnym znakiem ASCII lub jedną z tych sekwencji ucieczki:
- '\\': wpisz znak ukośnika.
- '\n': wpisz znak nowego wiersza (użyj go zamiast ENTER lub RETURN).
- '\t': wpisz znak tabulacji.
- '\'': wpisz znak apostrofu.
- '\"': wpisz znak cudzysłowu.
- '\uXXXX': wpisz znak Unicode, którego punkt kodowy jest podany w sposób szesnastkowy jako XXXX.
fallback <Android key code name>: wykonanie domyślnej czynności, jeśli aplikacja nie obsługuje klucza.

To zachowanie powoduje, że system symuluje naciśnięcie innego klawisza, gdy aplikacja nie obsługuje określonego klawisza natywnie. Służy do obsługi domyślnego zachowania nowych klawiszy, których nie wszystkie aplikacje potrafią obsługiwać, takich jak ESC lub klawisze klawiatury numerycznej (gdy nie jest wciśnięty klawisz NumLock).

Gdy zostanie wykonane działanie zastępcze, aplikacja otrzyma 2 nacisnięcia klawisza: jedno dla pierwotnego klawisza i drugie dla wybranego klawisza zastępczego. Jeśli aplikacja obsłuży pierwotny klucz podczas inicjowania klucza, odwołanie do klucza zapasowego zostanie anulowane (funkcja KeyEvent.isCanceled zwróci wartość true).

System rezerwuje 2 znaki Unicode do wykonywania funkcji specjalnych:

'\uef00': gdy to zachowanie zostanie wykonane, widok tekstu pobiera i usuwa 4 znaki poprzedzające kursor, interpretuje je jako cyfry szesnastkowe i wstawia odpowiedni punkt kodu Unicode.
'\uef01': gdy to zachowanie zostanie wykonane, widok tekstu wyświetli okno wyboru znaków zawierające różne symbole.

System rozpoznaje te znaki Unicode jako znaki diakrytyczne:

'\u0300': akcent słaby.
'\u0301': akcent akustyczny.
'\u0302': akcent przeciągły.
'\u0303': akcent tylda.
'\u0308': akcent umlaut.

Gdy wpiszemy klawisz bez znaku, a następnie inny znak, znaki te zostaną połączone. Jeśli np. użytkownik naciśnie klawisz akcentu grzecznego, a następnie literę „a”, otrzymamy „à”.

Więcej informacji o obsłudze martwych kluczy znajdziesz w artykule KeyCharacterMap.getDeadChar.

Komentarze

Linie komentarzy zaczynają się od znaku „#” i trwają do końca linii. Na przykład:

# A comment!

Puste wiersze są ignorowane.

Jak kombinacje klawiszy są mapowane na zachowania

Gdy użytkownik naciśnie klawisz, system sprawdza zachowanie powiązane z kombinacją tego naciśnięcia i obecnie wciśniętych modyfikatorów.

SHIFT + A

Załóżmy, że użytkownik nacisnął jednocześnie A i SHIFT. Najpierw system wyszukuje zbiór właściwości i zachowań powiązanych z wartością KEYCODE_A.

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

System skanuje właściwości od pierwszej do ostatniej i z lewej do prawej, ignorując właściwości label i number, które są specjalne.

Pierwsza napotkana usługa to base. Właściwość base zawsze dotyczy klawisza, niezależnie od tego, które klawisze modyfikujące są wciśnięte. W podstawie określa domyślne zachowanie klucza, chyba że zostanie zastąpione przez te właściwości. Ponieważ do tego naciśnięcia klawisza ma zastosowanie właściwość base, system zapisuje, że jego działanie to 'a' (wpisz znak a).

Następnie system skanuje kolejne właściwości, aby sprawdzić, czy któraś z nich jest bardziej szczegółowa niż base, i zastąpić tę pierwszą. Spotyka się z shift, co dotyczy też naciśnięcia klawiszy SHIFT + A. System zignoruje zachowanie usługi base i wybierze zachowanie powiązane z usługą shift, które jest 'A' (wpisz znak A).

Następnie kontynuuje skanowanie tabeli, ale do tego naciśnięcia klawisza nie mają zastosowania żadne inne właściwości (blokada wielkich liter jest wyłączona, nie naciśnięto klawisza CTRL, nie naciśnięto klawisza ALT i nie naciśnięto klawisza META).

W przypadku kombinacji klawiszy SHIFT + A działanie jest następujące: 'A'.

CONTROL + A

Zastanów się, co się stanie, jeśli użytkownik naciśnie A i CTRL jednocześnie.

Podobnie jak wcześniej system skanowałby tabelę właściwości. Zauważy, że zastosowano właściwość base, ale będzie też kontynuować skanowanie, aż dojdzie do właściwości control. Właściwość control pojawia się po właściwości base, więc jej zachowanie zastępuje zachowanie właściwości base.

W przypadku kombinacji klawiszy CTRL + A działanie to none.

ESCAPE

Załóżmy, że użytkownik nacisnął klawisz ESC.

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

Tym razem system uzyskuje zachowanie fallback BACK, które jest zachowaniem zapasowym. Ponieważ nie pojawia się żaden znak dosłowny, nie zostanie wpisany żaden znak.

Podczas przetwarzania klucza system najpierw prześle KEYCODE_ESCAPE do aplikacji. Jeśli aplikacja nie obsłuży tej operacji, system spróbuje ponownie, ale tym razem przekaże aplikacji wartość KEYCODE_BACK zgodnie z działaniem zastępczym.

Aplikacje, które rozpoznają i obsługują KEYCODE_ESCAPE, mogą przetwarzać ten klucz w takim stanie, ale inne aplikacje, które tego nie robią, mogą zamiast tego wykonać działanie zastępcze, traktując klucz tak, jakby był kluczem KEYCODE_BACK.

NUMPAD_0 z opcją NUM LOCK lub bez niej

Klawisze klawiatury numerycznej mają bardzo różne interpretacje w zależności od tego, czy klawisz NUM LOCK jest zablokowany.

Poniższa deklaracja klucza zapewnia, że KEYCODE_NUMPAD_0 będzie wpisywać 0 po naciśnięciu klawisza Num Lock. Gdy klawisz numeryczny nie jest wciśnięty, klucz jest dostarczany do aplikacji w zwykły sposób. Jeśli nie zostanie obsłużony, zamiast niego zostanie dostarczony klucz awaryjny KEYCODE_INSERT.

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

Jak widać, deklaracje klawiszy zapasowych znacznie poprawiają zgodność ze starszymi aplikacjami, które nie rozpoznają lub nie obsługują bezpośrednio wszystkich klawiszy obecnych na pełnej klawiaturze w stylu PC.

Przykłady

Pełna klawiatura

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

Klawiatura alfanumeryczna

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

Game pad

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

Uwaga dotycząca zgodności

Przed Androidem 3.0 Honeycomb mapa znaków kluczy w Androidzie była określana za pomocą bardzo odmiennej składni i była kompilowana w formacie pliku binarnego (.kcm.bin) w momencie kompilacji.

Chociaż nowy format używa tej samej rozszerzonej składni .kcm, jego składnia jest zupełnie inna (i znacznie bardziej zaawansowana).

Od Androida 3.0 Honeycomb wszystkie pliki mapy znaków kluczowych na Androidzie muszą używać nowej składni i formatu pliku tekstowego opisanego w tym dokumencie. Stara składnia nie jest obsługiwana, a system nie rozpoznaje starych plików .kcm.bin.

Uwaga dotycząca języka

Android nie obsługuje obecnie klawiatur wielojęzycznych. Co więcej, wbudowana ogólna mapa znaków klawiszy zakłada układ klawiatury angielskiej (amerykańskiej).

Producentów OEM zachęcamy do udostępniania niestandardowych map znaków klawiszy na klawiaturach, jeśli są one przeznaczone do innych języków.

Przyszłe wersje Androida mogą lepiej obsługiwać klawiatury wielojęzyczne lub układy klawiatury wybierane przez użytkownika.

Weryfikacja

Sprawdź pliki mapy kluczy za pomocą narzędzia Sprawdzanie map kluczy.

Pliki mapy klawiszy Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.