Gestire le azioni della tastiera

Quando l'utente attiva 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 Componenti componibili che supportano la scorciatoia
Maiusc+Ctrl+Freccia sinistra/Freccia destra Seleziona il testo all'inizio/alla fine della parola BasicTextField, TextField
Maiusc+Ctrl+Freccia su/Freccia giù Seleziona il testo all'inizio/alla fine del paragrafo BasicTextField, TextField
Maiusc+Alt+Freccia su/Freccia giù o Maiusc+Meta+Freccia sinistra/Freccia destra Seleziona il testo all'inizio/alla fine del testo BasicTextField, TextField
Maiusc+Freccia sinistra/Freccia destra Seleziona caratteri BasicTextField, TextField
Ctrl+A Seleziona tutto BasicTextField, TextField
Ctrl+C/Ctrl+X/Ctrl+V Copia/taglia/incolla BasicTextField, TextField
Ctrl+Z/Ctrl+Maiusc+Z Annulla/ripeti BasicTextField, TextField
Pagina giù/Pagina su Scorri LazyColumn, il modificatore verticalScroll, il modificatore scrollable

Eventi chiave

In Compose, puoi gestire una singola sequenza di tasti con il tasto di modifica onKeyEvent. Il modificatore accetta un comando lambda chiamato quando il componente modificato riceve un evento chiave. Un evento chiave è descritto come oggetto KeyEvent. Puoi ottenere le informazioni di ogni evento chiave facendo riferimento all'oggetto nel lambda passate al modificatore onKeyEvent.

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

Il valore restituito della funzione lambda onKeyEvent indica sulla gestione o meno dell'evento chiave. Restituisce true se l'app gestisce l'evento chiave, interrompendo la propagazione dell'evento.

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

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

Tasti di modifica

Un oggetto KeyEvent ha i seguenti attributi che indicano se i tasti modificatori 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 la chiave S. Se l'utente preme un tasto di modifica, come il tasto Maiusc, 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")
}

Barra spaziatrice e Inserisci eventi di clic sui tasti

Anche la Barra spaziatrice e il tasto Invio attivano gli 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 nel seguente modo:

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

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

Eventi chiave non consumati

Gli eventi chiave non utilizzati vengono propagati dal componente in cui l'evento si è verificato nel relativo componente esterno. Nell'esempio seguente, InnerComponent utilizza eventi chiave quando viene rilasciato il tasto S, pertanto OuterComponent non riceve eventi chiave attivati rilasciando la chiave S. Ecco perché la funzione actionB() non viene mai chiamata.

Altri eventi chiave su InnerComponent, ad esempio il rilascio della chiave D, può essere gestito dal OuterComponent. La funzione actionC() viene chiamata perché l'evento chiave per il rilascio della chiave D viene propagato in 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, si vuole intercettare un evento chiave prima di attivare l'azione predefinita. Un esempio tipico è l'aggiunta di scorciatoie personalizzate a un TextField. Il seguente snippet consente agli utenti di passare al componente attivo 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 tabulazione ogni volta che gli utenti premono il tasto Tab, anche se l'evento chiave viene gestito con il modificatore onKeyEvent. Per spostare lo stato attivo della tastiera senza aggiungere caratteri Tab, gestisci l'evento chiave prima di attivare le azioni associate, come nello snippet. La funzione lambda onKeyPreviewEvent() intercetta l'evento chiave restituendo true.

Il componente principale può intercettare l'evento chiave che si verifica nei componenti secondari. Nel seguente snippet, la funzione previewSKey() è 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")
  }
}

La funzione lambda onPreviewKeyEvent() per il componente Box non viene attivata nemmeno quando gli utenti premono il tasto Tab. La funzione lambda onPreviewKeyEvent() viene chiamata prima sul componente padre, viene chiamato nel componente secondario onPreviewKeyEvent(). Puoi implementare scorciatoie da tastiera a livello di schermo adottando questo comportamento.

Risorse aggiuntive

Avanti
Assistente scorciatoie da tastiera