Pager horizontal 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 →
Óculos de exibição
Saiba mais sobre tipos de dispositivos XR →

No Jetpack Compose Glimmer, GlimmerHorizontalPager é um layout composto de forma lenta e rolável horizontalmente que organiza as páginas sequencialmente. Ele é semelhante ao padrão HorizontalPager encontrado no Compose Foundation, mas personalizado para óculos com tela virtual com comportamentos e valores padrão do Glimmer.

Por padrão, apenas uma página é exibida de forma proeminente por vez. Para oferecer uma experiência refinada, o pager usa animações de ajuste para garantir que uma página sempre se ajuste exatamente aos limites da janela de visualização após o gesto de rolagem de um usuário.

Figura 1. Um exemplo de GlimmerHorizontalPager.

Parâmetros e opções de layout principais

Um GlimmerHorizontalPager oferece parâmetros personalizáveis para controlar o espaçamento, o alinhamento do layout e o carregamento lento. Alguns desses parâmetros são:

Parâmetro Descrição

state

Um GlimmerPagerState objeto que gerencia, observa e controla programaticamente a posição de rolagem e a página ativa do pager.

contentPadding

Padding aplicado aos limites gerais do conteúdo após o recorte, útil para adicionar padding de borda inicial ou final antes da primeira página ou depois da última.

pageSpacing

O espaçamento horizontal entre páginas individuais no pager.

pageIndicator

Um slot combinável que renderiza o indicador de página ativa. O padrão é GlimmerHorizontalPagerDefaults.PageIndicator(state).

beyondViewportPageCount

O número de páginas a serem compostas e dispostas além da janela de visualização visível como uma otimização de pré-carregamento. Evite definir valores grandes para preservar a eficiência da composição lenta.

Consulte a documentação de referência completa para informações sobre todos os parâmetros disponíveis.

Recomendação de movimento de texto animado

Durante as animações de ajuste e transições do pager em óculos com tela virtual, a renderização de texto padrão pode apresentar artefatos de ajuste de pixels. A configuração TextMotion.Animated garante uma renderização suave em animações de layout:

Text(
    text = "Page: $page",
    style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
)

Exemplo: pager horizontal

O código a seguir demonstra como criar um pager horizontal básico com 10 páginas, colocando um card dentro de cada página:

// Hoist the pager state, specifying the total page count with a lambda.
val pagerState = rememberGlimmerPagerState(pageCount = { 10 })

GlimmerHorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxSize(),
) { page ->
    // Use Glimmer components like Card and Text for optimized glasses styling.
    Card(modifier = Modifier.fillMaxWidth()) {
        Text(
            text = "Page: $page",
            // Recommended: use TextMotion.Animated for smooth transitions in a pager.
            style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
        )
    }
}

Principais pontos sobre o código

  • Estado: inicializa um GlimmerPagerState usando rememberGlimmerPagerState(pageCount = { 10 }) para gerenciar o estado do pager.
  • Conteúdo do slot de página: recebe o índice da página page dentro da GlimmerPagerScope lambda para renderizar cada card.
  • Estilo de texto de animação suave: copia LocalTextStyle.current e ativa explicitamente TextMotion.Animated.
  • Indicador de página automático: ao contrário dos pagers padrão do Compose que exigem um componente indicador externo, GlimmerHorizontalPager incorpora automaticamente um indicador de página de estilo de ponto por padrão.

Indicadores de página

Por padrão, GlimmerHorizontalPager renderiza um indicador de página baseado em pontos usando GlimmerHorizontalPagerDefaults.PageIndicator. O indicador adapta automaticamente o esquema de cores:

  • O ponto ativo usa a cor do conteúdo resolvida da surface circundante mais próxima.

Você pode transmitir um PageIndicator personalizado para especificar cores explícitas ou substituir o ponto pelo seu próprio layout personalizado:

GlimmerHorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxSize(),
    // Use a page numbers instead of the default dot-indicator
    pageIndicator = {
        Text(
            text = "${pagerState.currentPage + 1} / ${pagerState.pageCount}",
            style = LocalTextStyle.current.copy(textMotion = TextMotion.Animated),
        )
    }
)