Esta página inclui detalhes para melhorias opcionais de widgets disponíveis a partir do Android 12 (nível 31 da API). Esses recursos são opcionais, simples de implementar e melhorar experiência com o widget.
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 fornece uma interface transições e consistência em diferentes widgets.
Há duas maneiras de obter cores dinâmicas:
Usar o tema padrão do sistema (
@android:style/Theme.DeviceDefault.DayNight
) no layout raiz.Use o tema do Material 3 (
Theme.Material3.DynamicColors.DayNight
) do Componentes do Material Design para Android disponível a partir de Componentes do Material Design para Android v1.6.0
Após o tema ser definido no layout raiz, é possível usar atributos de cor comuns no a raiz ou 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, 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 para claros e escuros diferentes, 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=9&hl=pt)
![Widgets no tema do modo escuro](https://developer.android.com/static/images/appwidgets/example-darkmode.png?authuser=9&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 superior. 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 o padrão
de tema de temas.
Aqui está 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 exibir widgets em resposta a comandos de voz relevantes do usuário. Ao configurar suas para responder a intents integradas (BIIs, na sigla em inglês), seu app pode exibir widgets proativamente nas superfícies do Google Assistente, como Android e Android Auto Os usuários têm a opção de fixar widgets mostrados pelo Google Assistente aos próprios acesso rápido, incentivando o envolvimento futuro.
Por exemplo, você pode configurar o widget de resumo de treino para seu aplicativo de exercícios
para atender aos comandos de voz do usuário que acionam o
GET_EXERCISE_OBSERVATION
BII Quando os usuários acionarem essa BII, o Google Assistente vai mostrar o widget de forma proativa.
fazendo solicitações como: "Ok Google, quantos quilômetros eu corri esta semana
AppDeExemplo?"
Existem dezenas de BIIs que abrangem diversas categorias de interação do usuário, permitindo que quase todos os apps Android aprimorem os 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 para seus 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 mostrada na o seletor de widgets é escalonável. Você o fornece como um layout XML definido para o formato tamanho padrão. Antes, a visualização do widget era um recurso drawable estático, em alguns casos levam a visualizações que refletem de forma imprecisa como os widgets aparecem ao eles são adicionados à tela inicial.
Para implementar visualizações de widgets escalonáveis, use o
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 um padrão realista
ou valores de teste. A maioria dos apps usa os mesmos previewLayout
e initialLayout
. Para
orientações sobre como criar layouts precisos de visualização, consulte a seção a seguir nesta
página.
Recomendamos especificar os atributos previewLayout
e previewImage
.
para que o app possa voltar a usar previewImage
se o dispositivo do usuário
não oferece 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
appwidget-provider
para fornecer um layout XML:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
![Imagem mostrando uma prévia de um widget](https://developer.android.com/static/images/appwidgets/todo-list-groceries.png?authuser=9&hl=pt)
Para mostrar uma visualização precisa, forneça o widget real diretamente com valores padrão concluindo as seguintes etapas:
Definindo
android:text="@string/my_widget_item_fake_1"
paraTextView
os elementos.Definir uma imagem ou um ícone padrão ou de marcador de posição, como
android:src="@drawable/my_widget_icon"
, para componentesImageView
.
Sem os valores padrão, a visualização pode mostrar valores incorretos ou vazios. Um O importante benefício dessa abordagem é que você pode oferecer prévias localizadas conteúdo.
Para abordagens recomendadas para visualizações mais complexas que contêm ListView
,
GridView
ou StackView
, consulte Criar visualizações precisas que incluem dinâmicas
itens 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 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, fornecer uma descrição para o widget seletor a ser exibido para seu widget.
![Uma imagem mostrando um seletor de widgets mostrando um widget e a descrição dele](https://developer.android.com/static/images/appwidgets/description.png?authuser=9&hl=pt)
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>
Você pode usar o
descriptionRes
nas versões anteriores do Android, mas é ignorado pelo widget
seletor.
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 corrompidas, mas são ignoradas.
Usar a modificação de RemoteViews durante a execução
A partir do Android 12, você tem vários
Métodos RemoteViews
que fornecem a modificação de RemoteViews
no momento da execução.
atributos. Consulte a API RemoteViews
para obter 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);