Questa pagina contiene i dettagli dei miglioramenti facoltativi del widget disponibili a partire da Android 12 (livello API 31). Queste funzionalità sono facoltative, ma è semplice implementare e migliorare widget.
Utilizzare colori dinamici
A partire da Android 12, un widget può usare i colori del tema del dispositivo per pulsanti, sfondi e altri componenti. Ciò garantisce una maggiore fluidità transizioni e coerenza tra vari widget.
Esistono due modi per ottenere colori dinamici:
Utilizza il tema predefinito del sistema (
@android:style/Theme.DeviceDefault.DayNight
) nel layout principale.Utilizza il tema Material 3 (
Theme.Material3.DynamicColors.DayNight
) del Componenti dei materiali per Android libreria, disponibile a partire da Material Components per Android v1.6.0.
Dopo aver impostato il tema nel layout principale, puoi utilizzare gli attributi colore comuni nelle alla radice o a uno qualsiasi dei suoi elementi secondari per acquisire i colori dinamici.
Alcuni esempi di attributi di colore che puoi utilizzare sono i seguenti:
?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer
Nel seguente esempio in cui viene utilizzato il tema Material 3, il colore del tema del dispositivo è "viola". Il colore intenso e lo sfondo del widget si adattano al tema chiaro e scuro come mostrato nelle figure 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 con tema in modalità Luce](https://developer.android.google.cn/static/images/appwidgets/example-lightmode.png?authuser=0000&hl=it)
![Widget con il tema modalità Buio](https://developer.android.google.cn/static/images/appwidgets/example-darkmode.png?authuser=0000&hl=it)
Compatibilità con le versioni precedenti dei colori dinamici
I colori dinamici sono disponibili solo nei dispositivi con Android 12
o superiore. Per fornire un tema personalizzato per le versioni precedenti, crea un tema predefinito
con i tuoi colori personalizzati e un nuovo qualificatore (values-v31
) utilizzando il
del tema.
Ecco un esempio in cui viene utilizzato il 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>
Attiva supporto vocale
Con Azioni app puoi attivare l'Assistente Google mostrare widget in risposta a comandi vocali pertinenti dell'utente. Configurando il tuo per rispondere agli intent integrati (BII), può mostrare in modo proattivo i widget sulle piattaforme con l'assistente, come Android e Android Auto. Gli utenti possono fissare widget mostrati dall'assistente alle sue Avvio app, incoraggiando un coinvolgimento futuro.
Ad esempio, puoi configurare il widget di riepilogo degli esercizi per la tua app Allenamento
per eseguire i comandi vocali dell'utente che attivano il
GET_EXERCISE_OBSERVATION
intent integrato. L'assistente visualizza proattivamente il tuo widget quando gli utenti attivano questo intent integrato
facendo richieste come "Hey Google, quanti chilometri ho corso questa settimana
App di esempio?"
Esistono decine di intent integrati che coprono diverse categorie di interazioni degli utenti, consentendo a quasi tutte le app per Android di migliorare i propri widget per la voce. Per iniziare, consulta l'articolo Integrare le Azioni app con i widget Android.
Migliora l'esperienza di selezione widget della tua app
Android 12 ti consente di migliorare l'esperienza di selezione widget per il tuo dell'app aggiungendo anteprime e descrizioni dei widget dinamici.
Aggiungi anteprime scalabili al selettore widget
A partire da Android 12, l'anteprima del widget viene visualizzata nella il selettore widget è scalabile. Viene fornito come layout XML impostato sulla base dimensioni predefinite. In precedenza, l'anteprima del widget era una risorsa disegnabile statica, in alcuni casi portano ad anteprime che riflettono in modo impreciso come appaiono i widget e verranno aggiunti alla schermata Home.
Per implementare le anteprime scalabili dei widget, utilizza
previewLayout
dell'elemento appwidget-provider
per fornire un layout XML:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Ti consigliamo di utilizzare lo stesso layout del widget effettivo, con un valore predefinito realistico
o verificare i valori. La maggior parte delle app usa gli stessi previewLayout
e initialLayout
. Per
sulla creazione di layout di anteprima precisi, consulta la seguente sezione
.
Ti consigliamo di specificare entrambi gli attributi previewLayout
e previewImage
,
in modo che la tua app possa tornare a utilizzare previewImage
se il dispositivo dell'utente
non supporta previewLayout
. L'attributo previewLayout
ha la precedenza
rispetto all'attributo previewImage
.
Approcci consigliati per creare anteprime accurate
Per implementare le anteprime scalabili dei widget, utilizza l'attributo previewLayout
dell'attributo
Elemento appwidget-provider
per fornire un layout XML:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
![Un'immagine che mostra l'anteprima di un widget](https://developer.android.google.cn/static/images/appwidgets/todo-list-groceries.png?authuser=0000&hl=it)
Per visualizzare un'anteprima accurata, puoi fornire direttamente il widget effettivo con valori predefiniti, completando i seguenti passaggi:
Impostazione di
android:text="@string/my_widget_item_fake_1"
perTextView
elementi.Impostare un'immagine o un'icona predefinita o segnaposto, ad esempio
android:src="@drawable/my_widget_icon"
, perImageView
componenti.
Senza valori predefiniti, l'anteprima potrebbe mostrare valori errati o vuoti. Un L'importante vantaggio di questo approccio è che puoi fornire un'anteprima localizzata contenuti.
Per gli approcci consigliati per le anteprime più complesse contenenti ListView
,
GridView
o StackView
, consulta Creare anteprime accurate che includano contenuti
articoli per i dettagli.
Compatibilità con le versioni precedenti con le anteprime dei widget scalabili
Per consentire ai selettori di widget su Android 11 (livello API 30) o versioni precedenti di mostrare le anteprime del tuo
del widget, specifica la previewImage
.
Se modifichi l'aspetto del widget, aggiorna l'immagine di anteprima.
Aggiungere una descrizione per il widget
A partire da Android 12, fornisci una descrizione per il widget selettore da mostrare per il widget.
![Un'immagine che mostra un selettore di widget che mostra un widget e la relativa descrizione](https://developer.android.google.cn/static/images/appwidgets/description.png?authuser=0000&hl=it)
Fornisci una descrizione del widget utilizzando l'attributo description
dell'
Elemento <appwidget-provider>
:
<appwidget-provider
android:description="@string/my_widget_description">
</appwidget-provider>
Puoi utilizzare lo
descriptionRes
sulle versioni precedenti di Android, ma viene ignorato dal widget
selettore.
Consenti transizioni più fluide
A partire da Android 12, l'app Avvio app consente una transizione più fluida Quando un utente avvia l'app da un widget.
Per attivare questa transizione migliorata, usa @android:id/background
oppure
android.R.id.background
per identificare l'elemento di sfondo:
// Top-level layout of the widget.
<LinearLayout
android:id="@android:id/background">
</LinearLayout>
La tua app può usare @android:id/background
sulle versioni precedenti di Android
senza interruzioni, ma viene ignorato.
Utilizzo della modifica del runtime di RemoteView
A partire da Android 12, puoi usufruire di diverse
RemoteViews
metodi che consentono la modifica del runtime di RemoteViews
attributi. Vedi l'API RemoteViews
di riferimento per l'elenco completo dei metodi aggiunti.
Il codice di esempio riportato di seguito mostra come utilizzare alcuni di questi metodi.
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);