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 focado, ele desenha uma borda mais larga com um destaque.
• Segundo plano: aplica uma cor de segundo plano à área da superfície.
• Efeitos de profundidade: renderiza DepthEffect sombras com base no estado do componente (como padrão versus focado).
• Cor do conteúdo: fornece uma cor para texto e ícones dentro da superfície, calculada por padrão na cor de segundo plano.
• Estados de interação: desenha uma sobreposição pressionada quando a superfície é pressionada e uma borda mais larga com um destaque quando focada.

Exemplo: criar uma superfície

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

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

Interaction and Focus

Surfaces aren't focusable by default, so users can't interact with them. In most cases, surfaces should be interactive to let users consistently move focus and navigate between components. You can use the Compose focusable modifer for surfaces that are only intended to be focusable, or the Compose clickable modifer and other modifiers for surfaces that require actions.

You can create a focusable surface by combining a surface modifier with the focusable modifier:

@Composable
fun FocusableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        Modifier.surface(
                // Provide the same interaction source here and to focusable to make sure that
                // surface appears focused when interacted with.
                interactionSource = interactionSource
            )
            .focusable(interactionSource = interactionSource)
            .padding(horizontal = 24.dp, vertical = 20.dp)
    ) {
        Text("This is a focusable surface")
    }
}
SurfaceSamples.kt

Key points about the code

• Shared interaction source: Both .surface() and .focusable() must share the same interactionSource. This lets the surface react to focus changes.

Similarly, you can create a clickable surface:

@Composable
fun ClickableSurfaceSample() {
    val interactionSource = remember { MutableInteractionSource() }
    Box(
        Modifier.surface(
                // Provide the same interaction source here and to clickable to make sure that
                // surface appears focused and pressed when interacted with
                interactionSource = interactionSource
            )
            .clickable(interactionSource = interactionSource, onClick = {})
            .padding(horizontal = 24.dp, vertical = 20.dp)
    ) {
        Text("This is a clickable surface")
    }
}
SurfaceSamples.kt

Principais pontos sobre o código

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

• Ordenação de modificadores: a sequência de modificadores é essencial. 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á focada.