Ordine di attraversamento dello stato attivo

Gli utenti possono spostare la selezione della tastiera tra gli elementi dell'interfaccia utente utilizzando il tasto Tab o i tasti direzionali (freccia / D-pad):

• Tab / Maiusc+Tab: sposta lo stato attivo in avanti o indietro in un ordine di visualizzazione unidimensionale.
• Tasti direzionali: sposta l'elemento attivo in due dimensioni (Su, Giù, Sinistra e Destra).

Attraversamento della messa a fuoco unidimensionale

Nella navigazione dello stato attivo unidimensionale, il tasto Tab sposta lo stato attivo nell'interfaccia utente in base all'ordine di visualizzazione sullo schermo.

Ad esempio, quando quattro pulsanti sono disposti in righe:

Column {
    Row {
        Button(onClick = { /* ... */ }) { Text("1st") }
        Button(onClick = { /* ... */ }) { Text("2nd") }
    }
    Row {
        Button(onClick = { /* ... */ }) { Text("3rd") }
        Button(onClick = { /* ... */ }) { Text("4th") }
    }
}
FocusTraversal.kt

Se premi il tasto Tab, lo stato attivo si sposta in sequenza tra i pulsanti nel seguente ordine:

1. Primo pulsante (in alto all'inizio)
2. Secondo pulsante (estremità superiore)
3. Terzo pulsante (dal basso)
4. Quarto pulsante (in basso)

Se premi Tab sull'ultimo elemento, lo stato attivo di selezione torna al primo elemento. Se premi Maiusc+Tab, lo stato attivo viene spostato in ordine inverso.

Spostamento del focus bidimensionale

La pressione dei tasti Freccia della tastiera o l'utilizzo di un D-pad attiva l'attraversamento dello stato attivo bidimensionale.

Nella navigazione bidimensionale, il sistema esamina le coordinate geometriche e i limiti spaziali degli elementi dell'interfaccia utente per determinare la destinazione più vicina nella direzione richiesta.

L'attraversamento dello stato attivo bidimensionale non viene eseguito in loop. Se l'utente preme il tasto Giù mentre è attivo l'elemento più in basso, lo stato attivo rimane su quell'elemento anziché spostarsi nella parte superiore dello schermo.

Reimpostare l'attraversamento dello stato attivo con i clic del puntatore

Quando passi da una tastiera fisica a un mouse o un touchpad su dispositivi desktop o con schermo di grandi dimensioni:

• Cancella lo stato attivo con un tocco o un clic: se fai clic o tocchi uno spazio non interattivo con un mouse o un touchpad, lo stato attivo viene rilasciato dall'elemento attivo.
• Riavvio della navigazione: dopo aver spostato lo stato attivo, la successiva pressione del tasto Tab riavvia la navigazione unidimensionale dal primo elemento attivo in ordine di visualizzazione, anziché riprendere dall'elemento attivo in precedenza. È uguale all'attraversamento del focus bidimensionale. I tasti direzionali spostano la selezione della tastiera sul target di selezione più vicino nella direzione richiesta.

Per informazioni dettagliate sulla cancellazione programmatica dello stato attivo, vedi Spostare e cancellare lo stato attivo.

Personalizzare l'ordine di attraversamento della selezione

Puoi personalizzare il comportamento di attraversamento con il modificatore focusProperties.

Personalizzare l'ordine di attraversamento unidimensionale

Per ignorare l'attraversamento unidimensionale, specifica la proprietà next o previous con un FocusRequester:

1. Crea un oggetto FocusRequester con remember { FocusRequester() }.
2. Collega FocusRequester al componente componibile di destinazione utilizzando il modificatore focusRequester.
3. Applica il modificatore focusProperties al composable di origine e assegna FocusRequester a next (per Tab) o previous (per Maiusc+Tab).

val (first, second, third) = remember { FocusRequester.createRefs() }

Column {
    Button(
        onClick = { /* ... */ },
        modifier = Modifier
            .focusRequester(first)
            .focusProperties { next = third }
    ) {
        Text("First (Tab jumps to Third)")
    }
    Button(
        onClick = { /* ... */ },
        modifier = Modifier.focusRequester(second)
    ) {
        Text("Second")
    }
    Button(
        onClick = { /* ... */ },
        modifier = Modifier.focusRequester(third)
    ) {
        Text("Third")
    }
}
FocusTraversal.kt

Personalizzare l'ordine di attraversamento bidimensionale

Allo stesso modo, puoi eseguire l'override dell'attraversamento del focus bidimensionale assegnando istanze FocusRequester a up, down, start, end, left o right all'interno di focusProperties:

val (topButton, bottomButton) = remember { FocusRequester.createRefs() }

Button(
    onClick = { /* ... */ },
    modifier = Modifier
        .focusRequester(topButton)
        .focusProperties {
            down = bottomButton
            right = bottomButton
        }
) {
    Text("Top button")
}
Button(
    onClick = { /* ... */ },
    modifier = Modifier.focusRequester(bottomButton)
) {
    Text("Bottom button")
}
FocusTraversal.kt

Per bloccare la navigazione con la messa a fuoco in una direzione specifica (ad esempio, ai limiti del layout), assegna FocusRequester.Cancel a questa proprietà (ad esempio, down = FocusRequester.Cancel). Per mantenere esplicitamente l'algoritmo di attraversamento predefinito del sistema per una determinata direzione, assegna FocusRequester.Default.