Layouts de widgets canônicos

Crie layouts de widget eficazes identificando primeiro o conteúdo principal. O layout determina como as informações e os elementos interativos são organizados no widget. O Android oferece vários layouts pré-criados para barras de ferramentas, texto e widgets de lista e grade para simplificar esse processo.

Texto

Os layouts de texto são ideais para mostrar informações concisas. Melhore o apelo visual do widget incluindo uma imagem opcionalmente ao lado do texto.

Somente texto

Ideal para títulos, atualizações de status, descrições curtas ou qualquer cenário onde uma única linha de texto transmita a mensagem de maneira eficaz.

Texto e imagem

Inclua uma imagem para aumentar o impacto visual. Para mais informações, consulte Pontos de interrupção para aprender a adaptar esse layout a diferentes tamanhos de tela.

Barras de ferramentas

Use layouts de barra de ferramentas para oferecer aos usuários acesso rápido a tarefas usadas com frequência no seu app, em um layout flexível que se adapta a tamanhos de widget.

Barra de ferramentas de pesquisa

Um layout de barra de ferramentas de pesquisa é projetado intencionalmente para focar na pesquisa como uma ação principal na barra de ferramentas. Outros botões úteis podem oferecer acesso rápido a funções usadas com frequência.

Barra de ferramentas

As barras de ferramentas apresentam a marca do app seguida de botões para as tarefas mais usadas que são ideais para configurações alternáveis ou links de tarefas. Ao redimensionar, as opções menos usadas com frequência podem ser ocultadas em favor de ações mais comuns. Use Pontos de interrupção para adicionar um novo botão clicável mínimo de 48 dp quando houver espaço.

Listas

Use layouts de lista para organizar vários itens em um formato claro e verificável. Isso é ideal para manchetes de notícias, listas de tarefas ou mensagens. Organize o conteúdo em uma lista estruturada e verificável. Escolha entre a apresentação em contêiner ou sem contêiner com base nas necessidades de conteúdo.

Lista de texto e imagem

Listas de texto e imagem verificáveis são perfeitas para mostrar vários tipos de conteúdo, como manchetes de notícias, playlists com arte do álbum ou mensagens.

Lista de verificação

O layout da lista de verificação é perfeito para mostrar tarefas, oferecendo destinos de toque claros para que os usuários marquem rapidamente os itens como concluídos.

Lista de ações

Forneça um agrupamento de controle intuitivo com listas de ações, em que os estados visuais ativado/desativado oferecem feedback imediato sobre os status dos itens.

Imagem de sangria total

Ideal para mostrar imagens imersivas de sangria total no Android 17 e mais recentes, esse layout usa a rolagem de ajuste para garantir que cada elemento filho esteja perfeitamente alinhado à altura do contêiner do widget.

Grade

Apresente imagens em uma grade compacta, flexível e visualmente rica com rótulos opcionais. Use colunas e linhas que se adaptam a diferentes tamanhos de tela.

Somente imagem

Crie galerias de imagens roláveis e visualmente impactantes usando grades somente de imagens. As linhas e colunas se adaptam automaticamente a vários tamanhos de tela para apresentação ideal.

Imagem e texto

Você também pode incorporar rótulos e descrições de texto, enriquecendo o conteúdo da grade de imagens com mais contexto e informações.

Exemplos de código

A tabela a seguir mapeia cada layout canônico para a implementação correspondente do Jetpack Glance no repositório do GitHub de amostras da plataforma Android.

Layout canônico Arquivos de referência Orientação
Layout de lista de ações
  • Gerencie ações de itens de lista com callbacks de ação do Glance e garanta atualizações de estado adequadas.
Layout de lista
  • Implemente a alternância do estado da caixa de seleção usando parâmetros de ação ou callbacks para atualizar itens de coleção.
  • Use callbacks de ação do Glance, como `actionRunCallback`, `ActionCallback(actionParametersOf(...))` ou `actionStartActivity(...)`, para parâmetros `onClick` de widget para processar eventos de clique, como tocar em uma caixa de seleção.
Layout da barra de ferramentas expressiva
  • Evite erros de importação de `ColorProvider`: importe `androidx.glance.unit.ColorProvider` e use `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Use `GlanceModifier.background(Color)` diretamente para cores de fundo sólidas em vez de `ColorProvider`.
Layout da grade de imagens
  • Use cores sólidas (`GlanceModifier.background`) ou drawables locais para itens de imagem, a menos que uma biblioteca de carregamento de imagens esteja configurada ou solicitada.
Layout de lista de texto com imagem
  • Casos de uso comuns: feeds de notícias, listas de artigos, históricos de exercícios, feeds de mensagens e listas de miniaturas verticais.
  • Equilibre a altura da linha da lista e o recorte de texto ao combinar imagens de miniatura com texto principal/secundário.
Layout de texto longo
  • Se você multiplicar valores `Dp`, como `2 * padding`, importe `androidx.compose.ui.unit.times`.
  • Siga as regras de dimensionamento: garanta que as dimensões de `dimens.xml` sejam usadas para preenchimento e escalonamento de tipografia.
Layout da barra de ferramentas de pesquisa
  • Evite erros de importação de `ColorProvider`: importe `androidx.glance.unit.ColorProvider` e use `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Use `GlanceModifier.background(Color)` diretamente para cores de fundo sólidas em vez de ColorProvider.
Layout de imagem de sangria total / rolagem de ajuste
  • Defina `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` em LazyColumn para rolagem de ajuste.
  • Se você implementar a rolagem de ajuste, o Glance 1.3.0-alpha02 ou mais recente, o SDK 37 (Baklava) ou mais recente e o Plug-in do Android para Gradle (AGP) 9.1.0 ou mais recente serão necessários.
  • Defina `override val sizeMode: SizeMode = SizeMode.Exact` na classe do provedor de widget.
Layout da barra de ferramentas padrão
  • Consulte Solução de problemas para evitar erros de importação de `ColorProvider`: use `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Use `GlanceModifier.background(Color)` diretamente para cores de fundo sólidas em vez de `ColorProvider`.
Layout de texto com imagem
  • Siga as regras de dimensionamento de layout responsivo para acomodar texto e imagem lado a lado ou empilhados com base nas dimensões de widget disponíveis.