Obsługa działań na klawiaturze

Gdy użytkownik aktywuje komponent tekstu możliwego do edytowania, np. TextField, a do urządzenia jest podłączona klawiatura sprzętowa, wszystkie dane wejściowe są obsługiwane przez system. Skróty klawiszowe możesz udostępniać, obsługując zdarzenia klawiszy.

Domyślne skróty klawiszowe

Te skróty klawiszowe są dostępne od razu.

Skrót klawiszowy Działanie Komponenty obsługujące skrót
Shift+Ctrl+strzałka w lewo/strzałka w prawo Zaznacz tekst do początku/końca słowa BasicTextField, TextField
Shift+Ctrl+strzałka w górę/strzałka w dół Zaznacz tekst do początku/końca akapitu BasicTextField, TextField
Shift+Alt+strzałka w górę/strzałka w dół lub Shift+Meta+strzałka w lewo/strzałka w prawo Zaznacz tekst do początku/końca tekstu BasicTextField, TextField
Shift + strzałka w lewo/strzałka w prawo Wybierz znaki BasicTextField, TextField
Ctrl+A Zaznacz wszystko BasicTextField, TextField
Ctrl+C/Ctrl+X/Ctrl+V Kopiowanie/wycinanie/wklejanie BasicTextField, TextField
Ctrl+Z/Ctrl+Shift+Z Cofnij/Ponów BasicTextField, TextField
PageDown/PageUp Przewiń LazyColumn, modyfikator verticalScroll, modyfikator scrollable

Najważniejsze wydarzenia

W Compose możesz obsługiwać pojedyncze naciśnięcie klawisza za pomocą modyfikatora onKeyEvent. Modyfikator akceptuje funkcję lambda, która jest wywoływana, gdy zmodyfikowany komponent otrzymuje zdarzenie klawisza. Kluczowe zdarzenie jest opisane jako obiekt KeyEvent. Informacje o każdym kluczowym zdarzeniu możesz uzyskać, odwołując się do obiektu w funkcji lambda przekazanej do modyfikatora onKeyEvent.

Naciśnięcie klawisza wysyła 2 zdarzenia klawisza. Jedno jest wywoływane, gdy użytkownik naciśnie klawisz, a drugie, gdy go zwolni. Możesz rozróżnić te 2 kluczowe zdarzenia, odwołując się do atrybutu type obiektu KeyEvent.

Wartość zwracana przez funkcję lambda onKeyEvent wskazuje, czy kluczowe zdarzenie jest obsługiwane. Jeśli aplikacja obsługuje kluczowe zdarzenie, zwróć true, co zatrzyma propagację zdarzenia.

Poniższy fragment kodu pokazuje, jak wywołać funkcję doSomething(), gdy użytkownik zwolni klawisz S w komponencie Box:

Box(
    modifier = Modifier
        .onKeyEvent {
            if (
                it.type == KeyEventType.KeyUp &&
                it.key == Key.S
            ) {
                doSomething()
                true
            } else {
                false
            }
        }
        .focusable()
) {
    Text("Press S key")
}

Klawisze modyfikujące

Obiekt KeyEvent ma te atrybuty, które wskazują, czy klawisze modyfikujące są naciśnięte:

Opisz dokładnie kluczowe zdarzenia, które obsługuje Twoja aplikacja. Poniższy fragment kodu wywołuje funkcję doSomething() tylko wtedy, gdy użytkownik zwolni klawisz S. Jeśli użytkownik naciśnie dowolny klawisz modyfikujący, np. Shift, aplikacja nie wywoła funkcji.

Box(
    modifier = Modifier
        .focusable()
        .onKeyEvent {
            if (
                it.type == KeyEventType.KeyUp &&
                it.key == Key.S &&
                !it.isAltPressed &&
                !it.isCtrlPressed &&
                !it.isMetaPressed &&
                !it.isShiftPressed
            ) {
                doSomething()
                true
            } else {
                false
            }
        }
) {
    Text("Press S key with a modifier key")
}

zdarzenia kliknięcia spacji i klawisza Enter,

Spacja i Enter również wywołują zdarzenia kliknięcia. Użytkownicy mogą na przykład przełączać odtwarzanie multimediów (odtwarzać lub wstrzymywać) za pomocą klawisza Spacja lub Enter, obsługując zdarzenia kliknięcia w ten sposób:

MediaPlayer(modifier = Modifier.clickable { togglePausePlay() })

Modyfikator clickable przechwytuje zdarzenia klawiszy i wywołuje wywołanie zwrotne onClick() po naciśnięciu spacji lub klawisza Enter. Dlatego funkcja togglePausePlay() jest wywoływana przez naciśnięcie klawisza spacji lub Enter we fragmencie kodu.

Nieskonsumowane kluczowe zdarzenia

Nieskonsumowane kluczowe zdarzenia są przekazywane z komponentu, w którym wystąpiło zdarzenie, do otaczającego komponentu zewnętrznego. W przykładzie poniżej InnerComponent wykorzystuje zdarzenia klawiszy, gdy klawisz S jest zwolniony, więc OuterComponent nie otrzymuje żadnych zdarzeń klawiszy wywołanych przez zwolnienie klawisza S. Dlatego funkcja actionB() nigdy nie jest wywoływana.

Inne kluczowe zdarzenia w InnerComponent, takie jak zwolnienie klawisza D, mogą być obsługiwane przez OuterComponent. Funkcja actionC() jest wywoływana, ponieważ kluczowe zdarzenie zwolnienia klawisza D jest przekazywane do elementu OuterComponent.

OuterComponent(
    modifier = Modifier.onKeyEvent {
        when {
            it.type == KeyEventType.KeyUp && it.key == Key.S -> {
                actionB() // This function is never called.
                true
            }

            it.type == KeyEventType.KeyUp && it.key == Key.D -> {
                actionC()
                true
            }

            else -> false
        }
    }
) {
    InnerComponent(
        modifier = Modifier.onKeyEvent {
            if (it.type == KeyEventType.KeyUp && it.key == Key.S) {
                actionA()
                true
            } else {
                false
            }
        }
    )
}

Modyfikator onKeyPreviewEvent

W niektórych przypadkach możesz chcieć przechwycić zdarzenie klawisza, zanim wywoła ono działanie domyślne. Typowym przykładem jest dodawanie niestandardowych skrótów do TextField. Poniższy fragment kodu umożliwia użytkownikom przechodzenie do następnego komponentu, który można zaznaczyć, przez naciśnięcie klawisza Tab.

val focusManager = LocalFocusManager.current
var textFieldValue by remember { mutableStateOf(TextFieldValue()) }

TextField(
    textFieldValue,
    onValueChange = {
        textFieldValue = it
    },
    modifier = Modifier.onPreviewKeyEvent {
        if (it.type == KeyEventType.KeyUp && it.key == Key.Tab) {
            focusManager.moveFocus(FocusDirection.Next)
            true
        } else {
            false
        }
    }
)

Domyślnie komponent TextField dodaje znak tabulacji za każdym razem, gdy użytkownik naciśnie klawisz Tab, nawet jeśli zdarzenie klawisza jest obsługiwane za pomocą modyfikatora onKeyEvent. Aby przenieść zaznaczenie klawiatury bez dodawania znaków tabulacji, obsłuż zdarzenie klawisza przed wywołaniem powiązanych z nim działań, tak jak we fragmencie kodu. Wyrażenie lambda onKeyPreviewEvent() przechwytuje kluczowe zdarzenie, zwracając true.

Komponent nadrzędny może przechwytywać zdarzenie klawisza występujące w komponentach podrzędnych. W tym fragmencie kodu funkcja previewSKey() jest wywoływana, gdy użytkownicy naciskają klawisz S, zamiast wywoływać funkcję actionForPreview().

Column(
    modifier = Modifier.onPreviewKeyEvent {
        if (it.key == Key.S) {
            previewSKey()
            true
        } else {
            false
        }
    }
) {
    Box(
        modifier = Modifier
            .focusable()
            .onPreviewKeyEvent {
                actionForPreview(it)
                false
            }
            .onKeyEvent {
                actionForKeyEvent(it)
                true
            }
    ) {
        Text("Press any key")
    }
}

Funkcja lambda onPreviewKeyEvent() dla komponentu Box nie jest też wywoływana, gdy użytkownicy naciskają klawisz Tab. Najpierw wywoływana jest funkcja lambda onPreviewKeyEvent() w komponencie nadrzędnym, a następnie onPreviewKeyEvent() w komponencie podrzędnym. Możesz wdrożyć skróty klawiszowe na całym ekranie, korzystając z tego zachowania.

Dodatkowe materiały

Dalej
Pomoc dotycząca skrótów klawiszowych