Adicionar prévias geradas ao seletor de widgets

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:

  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 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 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.