Esta página inclui detalhes para 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 melhorar a experiência do widget para os usuários.
Usar cores dinâmicas
A partir do Android 12, widgets podem 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 conseguir cores dinâmicas:
Use o tema padrão do sistema (
@android:style/Theme.DeviceDefault.DayNight
) no layout raiz.Use o tema do Material Design 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 (links em inglês).
Depois que o tema é definido no layout raiz, você pode usar atributos de cor comuns na raiz ou em qualquer um dos filhos para capturar as cores dinâmicas.
Veja alguns exemplos de atributos de cor que podem ser usados:
?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer
No exemplo abaixo, usando o tema do Material 3, a cor do tema do dispositivo é "arroxeada". 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>
![Widget no tema do modo claro](https://developer.android.com/static/images/appwidgets/example-lightmode.png?authuser=7&hl=pt)
![Widgets no tema do modo escuro](https://developer.android.com/static/images/appwidgets/example-darkmode.png?authuser=7&hl=pt)
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 de tema
padrão.
Confira um exemplo usando o tema do 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
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 em plataformas do Google Assistente, como Android e Android Auto. Os usuários têm a opção de fixar widgets mostrados pelo Google Assistente na tela de início, incentivando o engajamento futuro.
Por exemplo, você pode configurar o widget de resumo de treino para o app de exercícios
para atender aos comandos de voz do usuário que acionam a
BII
GET_EXERCISE_OBSERVATION
. O Google Assistente mostra seu widget de maneira 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 widgets de 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 do seu app adicionando visualizações e descrições dinâmicas de widgets.
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. Anteriormente, a visualização do widget era um recurso drawable estático. Em alguns casos, isso levava a visualizações refletindo de forma imprecisa a aparência dos widgets quando eles 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 os mesmos previewLayout
e initialLayout
. Para
orientações sobre como criar layouts de visualização precisos, consulte a seção a seguir nesta
página.
Recomendamos especificar os atributos previewLayout
e previewImage
,
para que seu app possa voltar a usar previewImage
se o dispositivo do usuário
não oferecer 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 widget 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>
![Imagem mostrando uma visualização de widget](https://developer.android.com/static/images/appwidgets/todo-list-groceries.png?authuser=7&hl=pt)
Para mostrar uma visualização precisa, forneça diretamente o layout real do widget com valores padrão seguindo estas etapas:
Definição de
android:text="@string/my_widget_item_fake_1"
para elementosTextView
.Definição de uma imagem ou ícone padrão ou de marcador, como
android:src="@drawable/my_widget_icon"
, para componentesImageView
.
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 visualização localizado.
Para conhecer abordagens recomendadas para visualizações mais complexas que contêm 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 exibir no seu widget.
![Imagem de um seletor de widgets mostrando um widget e a descrição dele](https://developer.android.com/static/images/appwidgets/description.png?authuser=7&hl=pt)
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>
Você pode usar o atributo
descriptionRes
em versões anteriores do Android, mas ele será 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 a @android:id/background
em versões anteriores do Android
sem interrupções, mas ela é ignorada.
Usar a modificação de RemoteViews durante a execução
A partir do Android 12, é possível aproveitar vários
métodos de RemoteViews
que fornecem modificação de 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.
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);