Adicionar prévias geradas ao seletor de widgets

As visualizações de widgets geradas permitem criar visualizações dinâmicas e personalizadas para seus widgets que refletem com precisão a aparência deles na tela inicial de um usuário. Elas são fornecidas por uma API push, o que significa que seu app fornece a visualização a qualquer momento durante o ciclo de vida, sem receber uma solicitação explícita do host do widget.

Este guia aborda como fornecer visualizações para widgets baseados no Glance. Se o seu widget for implementado com RemoteViews, consulte Adicionar visualizações ao seletor de widgets.

Para melhorar a experiência do seletor de widgets do seu app para widgets do Glance, forneça uma visualização de widget gerada usando GlanceAppWidget.providePreview em dispositivos Android 15 e mais recentes e especifique uma previewImage para versões anteriores e como um substituto no Android 15 ou mais recente se uma visualização gerada não estiver disponível.

Para mais informações, consulte Enriquecer seu app com atualizações em tempo real e widgets no YouTube.

Configurar seu app para visualizações de widgets geradas

Para mostrar visualizações de widgets geradas em dispositivos Android 15 ou mais recentes, primeiro defina o compileSdk valor como 35 ou mais recente no arquivo build.gradle do módulo para ter a capacidade de fornecer RemoteViews ao seletor de widgets.

Os apps podem usar setWidgetPreview em GlanceAppWidgetManager. Para evitar abusos e reduzir problemas de integridade do sistema, setWidgetPreview é uma API com limitação de taxa. O limite padrão é de aproximadamente duas chamadas por hora.

Gerar visualização atualizada com o Jetpack Glance

Para widgets criados com o Jetpack Glance, faça o seguinte:

1. Substitua a função GlanceAppWidget.providePreview para fornecer o conteúdo combinável da visualização. Como você faria em provideGlance, carregue os dados do seu app e transmita-os para o conteúdo combinável do widget para que a visualização mostre dados precisos. Ao contrário de provideGlance, essa é uma composição única, sem recomposição ou efeitos.

2. Chame GlanceAppWidgetManager.setWidgetPreviews para gerar e publicar a visualização.

Não há um callback do sistema para fornecer visualizações. Portanto, seu app precisa decidir quando chamar setWidgetPreviews. A estratégia de atualização depende do caso de uso do widget:

• Se o widget tiver informações estáticas ou for uma ação rápida, defina a visualização quando o app for iniciado pela primeira vez.
• Você pode definir a visualização quando o app tiver dados, por exemplo, após o login do usuário ou a configuração inicial.
• É possível configurar uma tarefa periódica para atualizar as visualizações em uma cadência escolhida.

Resolver problemas de visualizações geradas

Um problema comum é que, depois de gerar uma visualização, imagens, ícones ou outros elementos combináveis podem estar ausentes da imagem de visualização, em relação ao tamanho de soltura do widget. Esse tamanho de soltura é definido por targetCellWidth e targetCellHeight se especificados, ou por minWidth e minHeight no arquivo de informações do provedor de widgets do app.

Isso ocorre porque o Android, por padrão, renderiza apenas elementos combináveis visíveis no tamanho mínimo do widget. Em outras palavras, o Android define previewSizeMode como SizeMode.Single por padrão. Ele usa android:minHeight e android:minWidth no XML de informações do provedor de widgets do app para determinar quais elementos combináveis serão desenhados.

Para corrigir isso, substitua previewSizeMode no GlanceAppWidget e defina-o como SizeMode.Responsive, fornecendo um conjunto de valores DpSize. Isso informa ao Android todos os tamanhos de layout necessários para renderizar a visualização, o que garante que todos os elementos sejam exibidos corretamente.

Otimize para formatos específicos. Forneça um ou dois tamanhos, começando pelo mínimo e seguindo os breakpoints do widget. Especifique pelo menos um previewImage para compatibilidade com versões anteriores. Você pode encontrar os valores mínimos de DP adequados para diferentes tamanhos de grade nas orientações de design de widgets.

Compatibilidade com versões anteriores para visualizações de widgets

Para permitir que os seletores de widgets em dispositivos que executam versões anteriores ao Android 15 mostrem visualizações do widget ou como um substituto para visualizações geradas no Android 15 ou mais recente, especifique o previewImage atributo.

Se você mudar a aparência do widget, atualize a imagem de visualização.