Questa pagina contiene i dettagli dei miglioramenti facoltativi dei widget disponibili a partire da Android 12 (livello API 31). Queste funzionalità sono facoltative, ma sono semplice da implementare e migliorare l'esperienza dei widget degli utenti.
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 transizioni e uniformi più fluide tra i diversi 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
) della raccolta Material Components per Android, 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 nella directory principale o in uno qualsiasi dei relativi elementi secondari per individuare 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 alle modalità Luce e Buio, 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>
Compatibilità con le versioni precedenti dei colori dinamici
I colori dinamici sono disponibili solo nei dispositivi con Android 12 o versioni successive. Per fornire un tema personalizzato alle versioni precedenti, crea un tema predefinito con i tuoi colori personalizzati e un nuovo qualificatore (values-v31
) utilizzando gli attributi del tema predefiniti.
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, l'Assistente Google consente di visualizzare widget in risposta a comandi vocali pertinenti dell'utente. Configurando il widget per rispondere agli intent integrati (BII), la tua app può mostrare in modo proattivo i widget sulle piattaforme con l'assistente, come Android e Android Auto. Gli utenti hanno la possibilità di bloccare i widget visualizzati dall'assistente su Avvio app, incoraggiando il coinvolgimento in futuro.
Ad esempio, puoi configurare il widget di riepilogo dell'allenamento per la tua app Allenamento
per soddisfare i comandi vocali dell'utente che attivano l'intent integrato
GET_EXERCISE_OBSERVATION
. L'assistente mostra in modo proattivo il tuo widget quando gli utenti attivano questo intent integrato
effettuando richieste come "Hey Google, quanti chilometri ho corso questa settimana su
ExampleApp?"
Esistono decine di intent integrati che coprono diverse categorie di interazione degli utenti e quasi tutte le app per Android possono migliorare i propri widget per la voce. Per iniziare, consulta Integrare le Azioni app con i widget Android.
Migliora l'esperienza di selezione widget della tua app
Android 12 consente di migliorare l'esperienza del selettore widget per la tua app aggiungendo anteprime e descrizioni dei widget dinamici.
Aggiungi anteprime scalabili al selettore widget
A partire da Android 12, l'anteprima del widget mostrata nel selettore dei widget è scalabile. Lo fornisci come layout XML impostato sulle dimensioni predefinite del widget. In precedenza, l'anteprima del widget era una risorsa disegnabile statica, in alcuni casi che portava ad anteprime che riflettevano in modo errato l'aspetto dei widget quando vengono aggiunti alla schermata Home.
Per implementare le anteprime scalabili dei widget, utilizza invece l'attributo 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 valori predefiniti realistici
o di test. La maggior parte delle app usa gli stessi previewLayout
e initialLayout
. Per
guida alla creazione di layout di anteprima precisi, consulta la sezione seguente in questa
pagina.
Ti consigliamo di specificare entrambi gli attributi previewLayout
e previewImage
,
in modo che la tua app possa utilizzare previewImage
nel caso in cui il dispositivo dell'utente
non supporti previewLayout
. L'attributo previewLayout
ha la precedenza
sull'attributo previewImage
.
Approcci consigliati per creare anteprime accurate
Per implementare le anteprime scalabili dei widget, utilizza l'attributo previewLayout
dell'elemento
appwidget-provider
per fornire un layout XML:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Per visualizzare un'anteprima accurata, puoi fornire direttamente il layout effettivo del widget con i valori predefiniti svolgendo i seguenti passaggi:
Impostazione di
android:text="@string/my_widget_item_fake_1"
per gli elementiTextView
.Impostazione di un'immagine o un'icona predefinita o segnaposto, ad esempio
android:src="@drawable/my_widget_icon"
, per i componentiImageView
.
Senza valori predefiniti, l'anteprima potrebbe mostrare valori errati o vuoti. Un importante vantaggio di questo approccio è la possibilità di fornire contenuti di anteprima localizzati.
Per conoscere gli approcci consigliati per le anteprime più complesse contenenti ListView
,
GridView
o StackView
, consulta Creare anteprime accurate che includano elementi dinamici per maggiori dettagli.
Compatibilità con le versioni precedenti con le anteprime dei widget scalabili
Per consentire ai selettori dei widget su Android 11 (livello API 30) o versioni precedenti di mostrare le anteprime del tuo
widget, specifica l'attributo 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 selettore widget da visualizzare per il widget.
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 l'attributo descriptionRes
nelle versioni precedenti di Android, ma viene ignorato dal selettore del widget.
Consenti transizioni più fluide
A partire da Android 12, l'Avvio app offre una transizione più fluida quando un utente avvia la tua app da un widget.
Per attivare questa transizione migliorata, utilizza @android:id/background
o
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 subire interruzioni, ma viene ignorato.
Utilizzo della modifica del runtime di RemoteView
A partire da Android 12, puoi sfruttare diversi metodi RemoteViews
che consentono la modifica del runtime degli attributi RemoteViews
. Consulta il riferimento dell'API RemoteViews
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);