Gestire le azioni della tastiera

Quando l'utente mette a fuoco un componente di testo modificabile, ad esempio un TextField, e al dispositivo è collegata una tastiera hardware, tutto l'input viene gestito dal sistema. Puoi fornire scorciatoie da tastiera gestendo gli eventi chiave.

Scorciatoie da tastiera predefinite

Le seguenti scorciatoie da tastiera sono disponibili immediatamente.

Scorciatoia da tastiera Azione Componibili che supportano la scorciatoia
Shift+Ctrl+Freccia sinistra/Freccia destra Seleziona il testo all'inizio/alla fine della parola BasicTextField, TextField
Shift+Ctrl+Freccia su/Freccia giù Seleziona il testo all'inizio/alla fine del paragrafo BasicTextField, TextField
Shift+Alt+Freccia su/Freccia giù o Shift+Meta+Freccia sinistra/Freccia destra Seleziona il testo all'inizio/alla fine del testo BasicTextField, TextField
Shift+Freccia sinistra/Freccia destra Seleziona i caratteri BasicTextField, TextField
Ctrl+A Seleziona tutto BasicTextField, TextField
Ctrl+C/Ctrl+X/Ctrl+V Copia/taglia/incolla BasicTextField, TextField
Ctrl+Z/Ctrl+Shift+Z Annulla/Ripeti BasicTextField, TextField
PageDown/PageUp Scorri LazyColumn, il modificatore verticalScroll, il modificatore scrollable

Eventi chiave

In Compose, puoi gestire una singola pressione di un tasto con il onKeyEvent modificatore. Il modificatore accetta un'espressione lambda chiamata quando il componente modificato riceve un evento chiave. Un evento chiave è descritto come un KeyEvent oggetto. Puoi ottenere le informazioni di ogni evento chiave facendo riferimento all'oggetto nell'espressione lambda passata al modificatore onKeyEvent.

La pressione di un tasto invia due eventi chiave. Uno viene attivato quando l'utente preme il tasto, l'altro quando il tasto viene rilasciato. Puoi distinguere i due eventi chiave facendo riferimento all'attributo type dell'oggetto KeyEvent.

Il valore restituito dell'espressione lambda onKeyEvent indica se l'evento chiave viene gestito o meno. Restituisci true se la tua app gestisce l'evento chiave, che interrompe la propagazione dell'evento.

Il seguente snippet mostra come chiamare una doSomething() funzione quando l'utente rilascia il tasto S sul componente Box:

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

Tasti di modifica

Un oggetto KeyEvent ha i seguenti attributi che indicano se i tasti di modifica sono premuti o meno:

Descrivi in modo specifico gli eventi chiave gestiti dalla tua app. Il seguente snippet chiama una funzione doSomething() solo se l'utente rilascia solo il tasto S. Se l'utente preme un tasto di modifica, ad esempio il tasto Shift, l'app non chiama la funzione.

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")
}

Eventi di clic sulla barra spaziatrice e sul tasto Invio

Anche la barra spaziatrice e il tasto Invio attivano eventi di clic. Ad esempio, gli utenti possono attivare/disattivare (riprodurre o mettere in pausa) la riproduzione di contenuti multimediali con la barra spaziatrice o il tasto Invio gestendo gli eventi di clic come segue:

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

Il modificatore clickable intercetta gli eventi chiave e chiama il callback onClick() quando viene premuta la barra spaziatrice Spacebar o Invio. Ecco perché la funzione togglePausePlay() viene chiamata premendo la barra spaziatrice o il tasto Invio nello snippet.

Eventi chiave non utilizzati

Gli eventi chiave non utilizzati vengono propagati dal componente in cui si è verificato l'evento al componente esterno di inclusione. Nell'esempio riportato di seguito, il InnerComponent utilizza gli eventi chiave quando viene rilasciato il tasto S, pertanto il OuterComponent non riceve eventi chiave attivati dal rilascio del tasto S. Ecco perché la funzione actionB() non viene mai chiamata.

Altri eventi chiave su InnerComponent, ad esempio il rilascio del tasto D, possono essere gestiti da OuterComponent. La funzione actionC() viene chiamata perché l'evento chiave per il rilascio del tasto D viene propagato a 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
            }
        }
    )
}

Modificatore onKeyPreviewEvent

In alcuni casi d'uso, vuoi intercettare un evento chiave prima che attivi l'azione predefinita. L'aggiunta di scorciatoie personalizzate a un TextField è un caso tipico. Il seguente snippet consente agli utenti di passare al componente selezionabile successivo premendo il tasto 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
        }
    }
)

Per impostazione predefinita, il componente TextField aggiunge un carattere di tabulazione ogni volta che gli utenti premono il tasto Tab, anche se l'evento chiave viene gestito con il modificatore onKeyEvent. Per spostare la selezione della tastiera senza aggiungere caratteri di tabulazione, gestisci l'evento chiave prima di attivare le azioni associate all'evento chiave, come nello snippet. L'onKeyPreviewEvent() lambda intercetta l'evento chiave restituendo true.

Il componente padre può intercettare l'evento chiave che si verifica sui relativi figli. Nel seguente snippet, la funzione previewSKey() viene chiamata quando gli utenti premono il tasto S, anziché chiamare la funzione 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")
    }
}

L'onPreviewKeyEvent() lambda per il componente Box non viene attivata quando gli utenti premono il tasto Tab nemmeno. L'espressione lambda onPreviewKeyEvent() viene chiamata prima sul componente padre, poi viene chiamata onPreviewKeyEvent() nel componente figlio. Puoi implementare scorciatoie da tastiera a schermo intero utilizzando questo comportamento.

Risorse aggiuntive

Avanti
Assistente scorciatoie da tastiera