Focus traversal order (ordem de apresentação do foco)

Os usuários podem mover o foco do teclado pelos elementos da interface usando a tecla Tab ou as teclas direcionais (setas / botão direcional):

• Tab / Shift+Tab: move o foco para frente ou para trás em uma ordem de aparência unidimensional.
• Teclas direcionais: movem o foco em duas dimensões (Para cima, Para baixo, Para a esquerda e Para a direita).

Transição de foco unidimensional

Na transição de foco unidimensional, a tecla Tab avança o foco pela interface com base na ordem de exibição visual na tela.

Por exemplo, quando quatro botões são organizados em linhas:

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

Pressionar a tecla Tab move o foco sequencialmente pelos botões na seguinte ordem:

1. 1º botão (parte de cima, à esquerda)
2. Segundo botão (parte de cima)
3. 3º botão (parte de baixo, início)
4. 4º botão (parte de baixo)

Pressionar Tab no elemento final volta para o primeiro destino de foco. Pressionar Shift+Tab move o foco na ordem inversa.

Transição de foco bidimensional

Pressionar as teclas de seta do teclado ou usar um botão direcional aciona a transição de foco bidimensional.

Na transição bidimensional, o sistema inspeciona as coordenadas geométricas e os limites espaciais dos elementos da interface para determinar o alvo mais próximo na direção solicitada.

A transição de foco bidimensional não permite o retorno. Se o usuário pressionar a tecla Para baixo enquanto estiver focado no elemento mais abaixo, o foco vai permanecer nesse elemento, em vez de pular para a parte de cima da tela.

Redefinir a travessia de foco com cliques do ponteiro

Ao alternar entre um teclado físico e um mouse ou touchpad em computadores ou dispositivos de tela grande:

• Limpar o foco ao tocar ou clicar: clicar ou tocar em um espaço não interativo com um mouse ou touchpad libera o foco do elemento ativo.
• Reiniciar a travessia: depois que o foco é limpo, a próxima tecla Tab pressionada reinicia a travessia unidimensional no primeiro alvo de foco na ordem de aparência visual, em vez de retomar do elemento ativo anteriormente. É igual à transição de foco bidimensional. As teclas direcionais movem o foco do teclado para o alvo de foco mais próximo na direção solicitada.

Para detalhes sobre como limpar o foco de forma programática, consulte Mover e limpar o foco.

Personalizar a ordem de apresentação do foco

É possível personalizar o comportamento de travessia com o modificador focusProperties.

Personalizar a ordem de apresentação unidimensional

Para substituir a travessia unidimensional, especifique a propriedade next ou previous com um FocusRequester:

1. Crie um objeto FocusRequester com remember { FocusRequester() }.
2. Anexe o FocusRequester ao elemento combinável de destino usando o modificador focusRequester.
3. Aplique o modificador focusProperties ao elemento combinável de origem e atribua o FocusRequester a next (para Tab) ou previous (para Shift+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

Personalizar a ordem de apresentação bidimensional

Da mesma forma, é possível modificar a travessia de foco bidimensional atribuindo instâncias de FocusRequester a up, down, start, end, left ou right em 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

Para bloquear a navegação de foco em uma direção específica (por exemplo, nos limites do layout), atribua FocusRequester.Cancel a essa propriedade (por exemplo, down = FocusRequester.Cancel). Para manter explicitamente o algoritmo de travessia padrão do sistema para uma determinada direção, atribua FocusRequester.Default.