Superfícies no Jetpack Compose Glimmer

Dispositivos XR relevantes

Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.

Saiba mais sobre tipos de dispositivos XR →

Saiba mais sobre tipos de dispositivos XR →

No Glimmer do Jetpack Compose, o surface componente é um elemento básico fundamental que representa uma área visual distinta ou um limite físico para componentes como botões e fichas de informações.

Uma superfície é responsável pelas seguintes propriedades visuais e físicas:

• Recorte: recorta os filhos em uma forma especificada.
• Borda: desenha uma borda interna para enfatizar o limite do componente. Quando focalizada, ela desenha uma borda mais larga com um destaque.
• Plano de fundo: aplica uma cor de plano de fundo à área da superfície.
• Efeitos de profundidade: renderiza DepthEffect sombras com base no estado do componente (como padrão versus focalizado).
• Cor do conteúdo: fornece uma cor para texto e ícones dentro da superfície, calculada por padrão com base na cor de plano de fundo.
• Estados de interação: desenha uma sobreposição pressionada quando a superfície é pressionada e uma borda mais larga com um destaque quando focalizada.

Exemplo: criar uma superfície

O código a seguir cria uma superfície com recorte, um plano de fundo e bordas padrão:

@Composable
fun SurfaceSample() {
    Box(Modifier.surface().padding(horizontal = 24.dp, vertical = 20.dp)) {
        Text("This is a surface")
    }
}

Interação e foco

As superfícies não são focalizáveis por padrão, então os usuários não podem interagir com elas. Na maioria dos casos, as superfícies precisam ser interativas para permitir que os usuários movam o foco e naveguem entre os componentes de maneira consistente. É possível usar o modificador focusable do Compose para superfícies que só podem ser focalizáveis. Da mesma forma, você pode criar uma superfície clicável usando o modificador clickable do Compose. Também é possível usar outros modificadores para superfícies que exigem ações.

O código a seguir mostra exemplos de superfícies focalizáveis e clicáveis:

@Composable
fun FocusableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource),
        contentAlignment = Alignment.Center
    ) {
        Text("Focusable")
    }
}

@Composable
fun ClickableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        modifier = Modifier
            .size(100.dp)
            .surface(interactionSource = interactionSource)
            .focusable(interactionSource = interactionSource)
            .clickable(
                interactionSource = interactionSource,
                indication = null
            ) { /* Handle click action */ },
        contentAlignment = Alignment.Center
    ) {
        Text("Clickable")
    }
}
SurfaceSamples.kt

Principais pontos sobre o código

• Origem de interação compartilhada para superfícies focalizáveis: .surface() e .focusable() precisam compartilhar a mesma interactionSource. Isso permite que a superfície reaja às mudanças de foco.

• Origem de interação compartilhada para superfícies clicáveis: .surface() e .clickable() precisam compartilhar a mesma interactionSource. Isso garante que os estados visuais (como pressionar ou focalizar) sejam sincronizados, permitindo que a superfície reaja visualmente à entrada do usuário.

• Ordenação de modificadores: a sequência de modificadores é fundamental. Como .surface() recorta um layout, colocá-lo antes de .clickable() garante que a área de toque seja restrita à forma da superfície. Se .clickable() vier primeiro, a área de interação poderá se estender além dos limites visíveis e recortados do componente.

SurfaceDepthEffect

A classe SurfaceDepthEffect gerencia a transição de sombras entre estados de interação:

• depthEffect: o efeito de sombra usado quando a superfície está no estado padrão.
• focusedDepthEffect: o efeito de sombra usado quando a superfície está focalizada.