Aprimorar seu widget

Esta página inclui detalhes para melhorias opcionais de widgets disponíveis no Android 12 (nível 31 da API) e versões mais recentes. Esses recursos são opcionais, mas são simples de implementar e melhorar a experiência dos widgets dos usuários.

Usar cores dinâmicas

A partir do Android 12, um widget pode usar as cores de tema do dispositivo para botões, planos de fundo e outros componentes. Isso proporciona transições mais suaves e consistência em diferentes widgets.

Há duas maneiras de conseguir cores dinâmicas:

• Use o tema padrão do sistema (@android:style/Theme.DeviceDefault.DayNight) no layout raiz.

• Use o tema Material 3 (Theme.Material3.DynamicColors.DayNight) da biblioteca Material Components for Android disponível a partir da Material Components for Android v1.6.0.

Depois que o tema é definido no layout raiz, você pode usar atributos de cor comuns na raiz ou em qualquer um dos filhos para captar as cores dinâmicas.

Confira alguns exemplos de atributos de cor que podem ser usados:

• ?attr/primary
• ?attr/primaryContainer
• ?attr/onPrimary
• ?attr/onPrimaryContainer

No exemplo a seguir, que usa o tema do Material 3, a cor do tema do dispositivo é "roxeado". A cor de destaque e o plano de fundo do widget se adaptam aos modos claro e escuro, como mostrado nas Figuras 1 e 2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

Figura 1. Widget no tema claro.

Figura 2. Widget no tema escuro.

Dica: recomendamos usar o tema Material 3 para seguir as diretrizes do Material Design para consistência entre dispositivos e compatibilidade retroativa.

Compatibilidade com versões anteriores para cores dinâmicas

As cores dinâmicas estão disponíveis apenas em dispositivos com o Android 12 ou versões mais recentes. Para fornecer um tema personalizado para versões anteriores, crie um tema padrão com suas cores personalizadas e um novo qualificador (values-v31) usando os atributos padrão.

Confira um exemplo que usa o tema Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Observação: consulte Estilos e temas para conferir um guia detalhado sobre como processar diferentes estilos, cores, atributos e temas.

Ativar o suporte por voz

As Ações no app permitem que o Google Assistente mostre widgets em resposta a comandos de voz relevantes do usuário. Ao configurar o widget para responder a intents integradas (BIIs, na sigla em inglês), o app pode mostrar widgets de forma proativa nas plataformas do Google Assistente, como o Android e o Android Auto. Os usuários têm a opção de fixar widgets mostrados pelo Google Assistente na tela de início, o que incentiva o engajamento no futuro.

Por exemplo, é possível configurar o widget de resumo do treino no app de exercícios para atender aos comandos de voz do usuário que acionam a BI GET_EXERCISE_OBSERVATION. O Google Assistente mostra proativamente seu widget quando os usuários acionam essa BII fazendo solicitações como Ok Google, quantos quilômetros eu corri esta semana no AppDeExemplo?

Existem dezenas de BIIs que abrangem várias categorias de interação do usuário, permitindo que quase todos os apps Android melhorem os widgets para voz. Para começar, consulte Integrar Ações no app com widgets do Android.

Melhorar a experiência com o seletor de widgets do app

O Android 12 permite adicionar visualizações e descrições de widgets dimensionadas. O Android 15 permite melhorar a experiência do seletor de widgets do app com visualizações de widgets geradas.

Para melhorar a experiência do seletor de widgets do app, forneça uma prévia de widget gerada no Android 15 e em dispositivos mais recentes, uma prévia de widget dimensionada (especificando um previewLayout) para dispositivos do Android 12 a Android 14 e um previewImage para versões anteriores.

Adicionar visualizações de widgets gerados ao seletor de widgets

Os apps precisam definir o valor compileSdk como 35 ou mais recente no arquivo build.gradle do módulo para fornecer RemoteViews ao seletor de widgets em dispositivos Android 15 ou mais recentes. Isso significa que os apps podem atualizar o conteúdo no seletor para que ele seja mais representativo do que o usuário vê.

Os apps podem usar os métodos AppWidgetManager, setWidgetPreview e getWidgetPreview para atualizar a aparência dos widgets com informações atualizadas e personalizadas.

Gerar uma visualização atualizada com o Jetpack Glance

Glance.compose executa uma composição. Portanto, nenhuma função de suspensão, fluxos ou chamadas assíncronas semelhantes são usados no corpo do elemento combinável. Em vez disso, é necessário usar dados constantes.

O exemplo abaixo usa o Jetpack Glance para gerar uma prévia atualizada. Uma configuração de build compileSdk de 35 ou mais recente é necessária para que setWidgetPreview seja mostrado como um método neste snippet.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

Gerar visualização atualizada sem o Jetpack Glance

É possível usar RemoteViews sem o Glance. O exemplo a seguir carrega um recurso de layout de widget XML e o define como a visualização. Uma configuração de build de compileSdk de 35 ou mais recente é necessária para que setWidgetPreview seja mostrado como um método neste snippet.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

Adicionar visualizações de widgets escalonáveis ao seletor

A partir do Android 12, a visualização do widget exibida no seletor de widgets é escalonável. Você fornece isso como um layout XML definido para o tamanho padrão do widget. Antes, a visualização do widget era um recurso drawable estático, em alguns casos, levando a visualizações que refletiam de forma imprecisa como os widgets aparecem quando eles são adicionados à tela inicial.

Para implementar visualizações de widgets escalonáveis, use o atributo previewLayout do elemento appwidget-provider para fornecer um layout XML:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Recomendamos usar o mesmo layout do widget real, com valores padrão ou de teste realistas. A maioria dos apps usa o mesmo previewLayout e initialLayout. Para orientações sobre como criar layouts de visualização precisos, consulte a próxima seção nesta página.

Recomendamos especificar os atributos previewLayout e previewImage para que o app possa usar previewImage se o dispositivo do usuário não tiver suporte a previewLayout. O atributo previewLayout tem precedência sobre o atributo previewImage.

Abordagens recomendadas para criar visualizações precisas

Para implementar visualizações de widgets escalonáveis, use o atributo previewLayout do elemento appwidget-provider para fornecer um layout XML:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Figura 3. Uma visualização de widget que, por padrão, aparece em uma área 3x3, mas pode caber em uma área 3x1 devido ao layout XML.

Para mostrar uma visualização precisa, forneça diretamente o layout do widget com valores padrão seguindo estas etapas:

• Definindo android:text="@string/my_widget_item_fake_1" para elementos TextView.

  Observação: os valores definidos com a tag tools, como tools:text="@string/my_wdiget_item_fake_1", não são mostrados na visualização.

• Definir uma imagem ou um ícone padrão ou de marcador, como android:src="@drawable/my_widget_icon", para componentes ImageView.

Sem valores padrão, a visualização pode mostrar valores incorretos ou vazios. Um benefício importante dessa abordagem é que você pode fornecer conteúdo de visualização localizado.

Para conferir as abordagens recomendadas para visualizações mais complexas que contêm ListView, GridView ou StackView, consulte Criar visualizações precisas que incluem itens dinâmicos para mais detalhes.

Compatibilidade com versões anteriores usando visualizações de widgets escalonáveis

Para permitir que os seletores de widgets no Android 11 (nível 30 da API) ou versões anteriores mostrem visualizações do widget, especifique o atributo previewImage.

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

Adicionar um nome ao widget

Os widgets precisam ter um nome exclusivo quando aparecem no seletor de widgets.

Os nomes dos widgets são carregados do atributo label do elemento receiver do widget no arquivo AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Adicionar uma descrição ao widget

A partir do Android 12, forneça uma descrição para ser exibida pelo seletor de widgets.

Figura 4. Exemplo de seletor de widgets mostrando um widget e a descrição dele.

Forneça uma descrição para o widget usando o atributo description do elemento <appwidget-provider>:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Observação: seja conciso. Não há limite de caracteres, mas a representação e o espaço disponível para a descrição podem variar dependendo do dispositivo.

É possível usar o atributo descriptionRes em versões anteriores do Android, mas ele é ignorado pelo seletor de widgets.

Ativar transições mais suaves

No Android 12, as telas de início oferecem uma transição mais suave quando um usuário inicia o app de um widget.

Para ativar essa transição melhorada, use @android:id/background ou android.R.id.background para identificar seu elemento de plano de fundo:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Aviso: evite usar trampolins de transmissão. No Android 12 e versões mais recentes, um app ainda pode iniciar uma atividade de um broadcast receiver ou serviço se for iniciada de uma PendingIntent do clique no widget. No entanto, a nova animação do app não é usada para apps iniciados com um broadcast receiver ou serviço, o que causa uma experiência insatisfatória para o usuário.

O app pode usar @android:id/background em versões anteriores do Android sem falhas, mas ele é ignorado.

Usar a modificação de RemoteViews durante a execução

A partir do Android 12, é possível aproveitar vários métodos RemoteViews que permitem a modificação dos atributos RemoteViews durante a execução. Consulte a referência da API RemoteViews para conferir a lista completa de métodos adicionados.

O exemplo de código a seguir mostra como usar alguns desses métodos.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);