Layouts de widgets canônicos

Para criar layouts de widgets eficazes, primeiro identifique seu 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, listas e widgets do tipo 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 ao lado do texto.

Somente texto

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

Texto e imagem

Inclua uma imagem para aumentar o impacto visual. Para mais informações, consulte Pontos de interrupção para saber como 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 widgets.

Barra de ferramentas de pesquisa

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

Barra de ferramentas Google

As barras de ferramentas apresentam a marca do app seguida de botões para as tarefas mais usadas, 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 tocável de 48 dp quando houver espaço.

Listas

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

Lista de texto e imagem

Listas de texto e imagens fáceis de ler são perfeitas para mostrar vários tipos de conteúdo, como manchetes de notícias, playlists com arte de álbuns ou mensagens.

Lista de verificação

O layout de checklist é perfeito para mostrar tarefas, oferecendo alvos de toque claros para que os usuários marquem rapidamente os itens como concluídos.

Lista de ações

Ofereça 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 sangrada

Ideal para mostrar imagens imersivas e sem sangria no Android 17 e em versões mais recentes, esse layout usa a rolagem de ajuste para garantir que cada elemento filho se alinhe perfeitamente à altura do contêiner de widgets.

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 uma apresentação ideal.

Imagem e texto

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

Amostras 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 exemplos da plataforma Android.

Layout canônico Arquivos de referência Orientação
Layout da lista de ações
  • Processar ações de itens de lista com callbacks de ação do Glance e garantir atualizações de estado adequadas.
Layout da lista de verificação
  • Implemente a alternância do estado da caixa de seleção usando parâmetros de ação ou callbacks para atualizar os itens da coleta.
  • Use callbacks de ação do Glance, como `actionRunCallback`, `ActionCallback(actionParametersOf(...))` ou `actionStartActivity(...)`, para parâmetros `onClick` do widget para processar eventos de clique, como tocar em uma caixa de seleção.
Layout expressivo da barra de ferramentas
  • 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 plano de fundo sólidas em vez de `ColorProvider`.
Layout de grade de imagens
  • Use cores sólidas (`GlanceModifier.background`) ou elementos gráficos locais para itens de imagem, a menos que uma biblioteca de carregamento de imagens esteja configurada ou solicitada.
Layout de lista de texto da imagem
  • Casos de uso comuns: feeds de notícias, listas de artigos, históricos de treinos, feeds de mensagens e listas de miniaturas verticais.
  • Equilibre a altura da linha da lista e o corte de texto ao combinar imagens em 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: verifique se as dimensões de "dimens.xml" são usadas para padding 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 plano de fundo sólidas em vez de ColorProvider.
Layout de imagem sangrada / rolagem de ajuste
  • Defina `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` em LazyColumn para rolagem de ajuste.
  • Se você implementar a rolagem de ajuste, será necessário usar o Glance 1.3.0-alpha02 ou mais recente, o SDK de compilação 37 (Baklava) ou mais recente e o Plug-in do Android para Gradle (AGP) 9.1.0 ou mais recente.
  • Defina `override val sizeMode: SizeMode = SizeMode.Exact` na classe do provedor de widgets.
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 plano 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 disponíveis do widget.