Aprimorar seu widget

Teste o jeito do Compose
O Jetpack Compose é o kit de ferramentas de UI recomendado para Android. Aprenda a criar widgets usando APIs no estilo Compose.
Jetpack Glance →

Esta página inclui detalhes sobre melhorias opcionais de widgets disponíveis a partir do Android 12 (nível 31 da API). Esses recursos são opcionais, mas são fáceis de implementar e melhoram a experiência dos usuários com widgets.

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 possibilita transições mais suaves e consistência em diferentes widgets.

Há duas maneiras de conseguir cores dinâmicas:

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

Confira alguns exemplos de atributos de cor que você pode usar:

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

No exemplo a seguir, usando o tema do Material 3, a cor do tema do dispositivo é "roxo". A cor de destaque e o plano de fundo do widget se adaptam aos modos claro e escuro, conforme 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>
Widget no tema do modo claro
Figura 1. Widget no tema claro.
Widgets no tema do modo escuro
Figura 2. Widget no tema escuro.

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 do tema padrão.

Confira um exemplo usando 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>

Ativar o suporte por voz

Com as Ações no app, o Google Assistente mostra widgets em resposta a comandos de voz relevantes do usuário. Ao configurar seu widget para responder a intentos integrados (BIIs), seu app pode mostrar widgets de forma proativa em plataformas do Google Assistente, como Android e Android Auto. Os usuários podem fixar widgets mostrados pelo Google Assistente na tela de início, incentivando o engajamento futuro.

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

Há 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 as 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 para seu app com prévias geradas.

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

Adicionar prévias de widgets geradas ao seletor de widgets

Os apps precisam definir o valor compileSdk como 35 ou mais recente no arquivo build.gradle do módulo para oferecer 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 ser 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

O Glance.compose executa uma composição. Portanto, nenhuma função de suspensão, fluxo ou chamada assíncrona semelhante é usada no corpo do elemento combinável. Em vez disso, use dados constantes.

O exemplo a seguir 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 apareça 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 uma prévia atualizada sem o Jetpack Glance

Você pode usar o RemoteViews sem o recurso Em um relance. O exemplo a seguir carrega um recurso de layout de widget XML e o define como a prévia. Uma configuração de build compileSdk de 35 ou mais recente é necessária para que setWidgetPreview apareça 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ê o fornece 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, a visualização não refletia corretamente a aparência dos widgets quando eram 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 prévia precisos, consulte a seção a seguir nesta página.

Recomendamos especificar os atributos previewLayout e previewImage para que seu app possa usar previewImage se o dispositivo do usuário não for compatível com previewLayout. O atributo previewLayout tem precedência sobre o atributo previewImage.

Abordagens recomendadas para criar prévias 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>
Uma imagem mostrando uma prévia de widget
Figura 3. Uma prévia de widget que, por padrão, aparece em uma área de 3x3, mas pode caber em uma área de 3x1 devido ao layout XML.

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

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

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

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

Para abordagens recomendadas de 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 (API de nível 30) ou versões anteriores mostrem prévias do seu widget, especifique o atributo previewImage.

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

Adicione um nome ao widget

Os widgets precisam ter um nome exclusivo quando são mostrados 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

No Android 12, forneça uma descrição para o seletor de widgets mostrar no widget.

Uma imagem mostrando um seletor de widgets com um widget e a descrição dele
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 &lt;appwidget-provider&gt;:

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

Você pode 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>

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, você pode aproveitar vários métodos RemoteViews que permitem a modificação durante a execução dos atributos RemoteViews. Consulte a referência da API RemoteViews para ver 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);