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

Os usuários podem mover o foco do teclado entre os elementos da interface usando a tecla Tab ou as teclas direcionais (seta / 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 aparência 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 nesta ordem:

1. 1º botão (início da parte de cima)
2. Segundo botão (extremidade superior)
3. Terceiro botão (início da parte de baixo)
4. Quarto botão (parte de baixo)

Pressionar Tab no elemento final volta ao 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 o foco estiver no elemento mais abaixo, o foco vai permanecer nesse elemento em vez de pular para a parte de cima da tela.

Redefinir a navegação por foco com cliques do ponteiro

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

• Remover foco ao tocar ou clicar: clicar ou tocar em um espaço não interativo com um mouse ou touchpad remove o foco do elemento ativo.
• Reiniciar travessia: depois que o foco é removido, 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 mais próximo na direção solicitada.

Para detalhes sobre como limpar o foco de maneira 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 navegação unidimensional

Para substituir a navegação 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 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 navegação bidimensional

Da mesma forma, é possível substituir a navegação de foco bidimensional atribuindo instâncias 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 por 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 reter explicitamente o algoritmo de travessia padrão do sistema em uma determinada direção, atribua FocusRequester.Default.