As prévias geradas de widgets permitem criar prévias dinâmicas e personalizadas para seus widgets que refletem com precisão como eles vão aparecer na tela inicial do usuário. Eles são fornecidos por uma API push, o que significa que o app fornece a prévia em qualquer momento do ciclo de vida sem receber uma solicitação explícita do host do widget.
Este guia mostra como fornecer prévias para widgets baseados no Resumo. Se o
widget for implementado com RemoteViews, consulte Adicionar prévias ao seletor de
widgets.
Para melhorar a experiência do seletor de widgets do seu app para widgets do Resumo, forneça uma
prévia gerada usando GlanceAppWidget.providePreview em
dispositivos Android 15 e versões mais recentes e especifique um previewImage
para versões anteriores e como substituto no Android 15 ou mais recente se
uma prévia gerada não estiver disponível.
Para mais informações, assista Enrich your app with atualizações em tempo real and widgets no YouTube.
Configurar o app para visualizações de widgets gerados
Para mostrar prévias de widgets geradas em um dispositivo com o Android 15 ou versões mais recentes, primeiro defina o
valor de compileSdk como 35 ou mais no arquivo build.gradle do módulo para ativar
as prévias geradas no seletor de widgets.
Os apps podem usar setWidgetPreview em GlanceAppWidgetManager. Para evitar
abusos e reduzir as preocupações com a integridade do sistema, a setWidgetPreview é uma API com limitação de
taxa. O limite padrão é de aproximadamente duas chamadas por hora.
Gerar uma prévia atualizada com o Jetpack Glance
Para widgets criados com o Jetpack Glance, faça o seguinte:
Substitua a função
GlanceAppWidget.providePreviewpara fornecer o conteúdo combinável para a prévia. Como você faria emprovideGlance, carregue os dados do app e transmita-os para o combinável de conteúdo do widget para que a prévia mostre dados precisos. Ao contrário deprovideGlance, essa é uma única composição sem recomposição ou efeitos.Chame
GlanceAppWidgetManager.setWidgetPreviewspara gerar e publicar a visualização.
Não há um callback do sistema para fornecer prévias. Portanto, o 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 prévia quando o app for iniciado pela primeira vez.
- É possível definir a prévia 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 prévias em uma frequência escolhida.
Resolver problemas com as prévias geradas
Um problema comum é que, depois de gerar uma prévia, imagens, ícones ou outros
elementos de composição podem estar ausentes na imagem de prévia, em relação ao tamanho
de soltura do widget. Esse tamanho é definido por targetCellWidth e
targetCellHeight, se especificado, ou por minWidth e minHeight no
arquivo de informações do provedor do widget do app.
Isso ocorre porque o Android, por padrão, renderiza apenas os elementos que podem ser compostos visíveis no
tamanho mínimo do widget. Em outras palavras, o Android define o 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 como
SizeMode.Responsive, fornecendo um conjunto de valores DpSize. Isso informa ao Android
todos os tamanhos de layout que ele precisa renderizar para a prévia, o que garante que todos
os elementos sejam mostrados corretamente.
Otimize para formatos específicos. Forneça um ou dois tamanhos, começando pelo
mínimo e seguindo os pontos de interrupção do widget. Especifique pelo menos um
previewImage para oferecer suporte a versões anteriores do Android. Encontre os
valores mínimos de DP apropriados para diferentes tamanhos de grade no
guia de design de widgets.
Suporte a versões anteriores do Android
Para mostrar prévias de widgets em dispositivos com o Android 14 e versões anteriores
ou quando uma prévia gerada não estiver disponível no Android 15 e versões mais recentes,
especifique o atributo previewImage.
Se você mudar a aparência do widget, atualize a imagem de visualização.