Aprimorar seu widget

Experimente trabalhar com o Compose

O Jetpack Compose é o kit de ferramentas de interface recomendado para o Android. Aprenda a criar widgets usando APIs no estilo do Compose.

Jetpack Glance →

Esta página inclui detalhes sobre melhorias opcionais de widgets que estão disponíveis a partir do Android 12 (nível 31 da API). Esses recursos são opcionais, mas são simples de implementar e melhoram a experiência do widget 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 para Android, disponível a partir da versão 1.6.0.

Depois que o tema for definido no layout raiz, você poderá usar atributos de cor comuns na raiz ou em qualquer um dos filhos dela para escolher 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, usando o tema 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>

Compatibilidade com versões anteriores para cores dinâmicas

As cores dinâmicas só estão disponíveis 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 de tema padrão.

Confira um exemplo usando o tema 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 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 seu widget para responder a intents integrados (BIIs), seu app pode mostrar widgets de forma proativa em 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 em sua tela de início, incentivando o engajamento futuro.

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

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.

Adicionar 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

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

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

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

Você pode usar o descriptionRes atributo 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 de atributos RemoteViews durante a execução. Consulte a RemoteViews API referência para conferir 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);