Adicionar prévias geradas ao seletor de widgets

Com as visualizações geradas de widgets, você cria visualizações dinâmicas e personalizadas que refletem com precisão como eles vão aparecer na tela inicial de um usuário. Elas são fornecidas por uma API push, o que significa que seu app fornece a prévia a qualquer momento durante o ciclo de vida sem receber uma solicitação explícita do host do widget.

Este guia explica como fornecer prévias para widgets baseados no Glance. 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 app para widgets do Glance, forneça uma prévia gerada usando GlanceAppWidget.providePreview em dispositivos Android 15 e mais recentes e especifique um previewImage para versões anteriores e como um substituto no Android 15 ou mais recente se uma prévia gerada não estiver disponível.

Para mais informações, assista Enriqueça seu app com atualizações em tempo real e widgets no YouTube.

Configurar o app para visualizações de widgets gerados

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

Em seguida, os apps podem usar setWidgetPreview em GlanceAppWidgetManager. Para evitar abusos e reduzir problemas de 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:

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

2. Chame GlanceAppWidgetManager.setWidgetPreviews para gerar e publicar a prévia.

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.
• Você pode definir a prévia depois que o app tiver dados, por exemplo, após um início de sessão do usuário ou uma configuração inicial.
• É possível configurar uma tarefa periódica para atualizar as prévias na cadência escolhida.

Solução de problemas com visualizações geradas

Um problema comum é que, depois de gerar uma prévia, imagens, ícones ou outros combináveis podem estar faltando na imagem de prévia, em relação ao tamanho de soltar do widget. Esse tamanho de redução é definido por targetCellWidth e targetCellHeight, se especificado, ou por minWidth e minHeight no arquivo de informações do provedor de widget de 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 de app para determinar quais elementos combináveis precisam ser 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 necessários para renderizar a prévia, garantindo 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 pontos de interrupção 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 no guia de design de widgets.

Observação: prefira SizeMode.Exact em vez de SizeMode.Responsive ao dimensionar seu widget (não a visualização). Consulte a documentação para uma visão geral do SizeMode.

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

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

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