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 simples de implementar e melhorar a experiência de widgets dos usuários.

Usar cores dinâmicas

A partir do Android 12, um widget pode usar as cores do 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 obter cores dinâmicas:

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

• Use o tema do Material 3 (Theme.Material3.DynamicColors.DayNight) da biblioteca Material Components para Android, disponível a partir da versão Componentes do Material Design para 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 abaixo, que usa 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, 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>

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 a versões anteriores, crie um tema padrão com suas cores personalizadas e um novo qualificador (values-v31) usando os atributos de tema padrão.

Aqui está um exemplo usando o tema do Material 3:

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

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

<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

As Ações no app permitem que o Google Assistente exiba 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 superfícies do Google Assistente, como o Android e o Android Auto. Os usuários têm a opção de fixar widgets na tela de início mostrados pelo Google Assistente, incentivando o engajamento futuro.

Por exemplo, você pode configurar o widget de resumo do treino do app de exercícios para atender aos comandos de voz do usuário que acionam a BII GET_EXERCISE_OBSERVATION. O Google Assistente mostra o 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 ExampleApp?".

Existem dezenas de BIIs que abrangem diversas categorias de interação do usuário, permitindo que quase todos os apps Android aprimorem 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 melhorar a experiência do seletor de widgets para o app adicionando visualizações e descrições dinâmicas de widgets.

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

No Android 12 e versões mais recentes, 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, 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 realistas de padrão ou de teste. A maioria dos apps usa os mesmos previewLayout e initialLayout. Para orientações sobre como criar layouts de visualização precisos, consulte a seção a seguir desta página.

Recomendamos especificar os atributos previewLayout e previewImage para que o app possa voltar a usar previewImage caso o dispositivo do usuário não ofereça 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>

Para mostrar uma visualização precisa, você pode fornecer diretamente o layout real do widget com valores padrão seguindo estas etapas:

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

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

Sem os 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 prévia localizado.

Para conhecer as abordagens recomendadas para visualizações mais complexas que contenham ListView, GridView ou StackView, consulte Criar visualizações precisas que incluam itens dinâmicos para mais detalhes.

Compatibilidade com versões anteriores com 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 uma descrição ao widget

A partir do Android 12, forneça uma descrição para o seletor de widgets mostrar seu widget.

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

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

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

Seu app pode usar o @android:id/background em versões anteriores do Android sem interrupções, 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 oferecem a modificação dos atributos RemoteViews durante a execução. 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.

// 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)

// 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);