Migliora il widget

Prova Compose

Jetpack Compose è il toolkit UI consigliato per Android. Scopri come creare widget utilizzando le API in stile Compose.

Jetpack Glance →

Questa pagina include i dettagli dei miglioramenti dei widget facoltativi disponibili a partire da Android 12 (livello API 31). Queste funzionalità sono facoltative, ma sono semplici da implementare e migliorano l'esperienza dei widget degli utenti.

Utilizza colori dinamici

A partire da Android 12, un widget può utilizzare i colori del tema del dispositivo per pulsanti, sfondi e altri componenti. Ciò garantisce transizioni più fluide e coerenza 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) dalla libreria Material Components for Android, disponibile a partire da Material Components for Android v1.6.0.

Una volta impostato il tema nel layout principale, puoi utilizzare gli attributi di colore comuni nella radice o in uno dei relativi elementi secondari per selezionare i colori dinamici.

Di seguito sono riportati alcuni esempi di attributi di colore che puoi utilizzare:

• ?attr/primary
• ?attr/primaryContainer
• ?attr/onPrimary
• ?attr/onPrimaryContainer

Nell'esempio seguente che utilizza il tema Material 3, il colore del tema del dispositivo è "violaceo". 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 per i colori dinamici

I colori dinamici sono disponibili solo sui dispositivi con Android 12 o versioni successive. 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 gli attributi del tema predefinito.

Ecco un esempio che utilizza il 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>

Attiva il supporto vocale

Le azioni app consentono all'Assistente Google di visualizzare i widget in risposta ai comandi vocali pertinenti dell'utente. Se configuri il tuo widget in modo che risponda agli intent integrati (BII), la tua app può visualizzare in modo proattivo i widget sulle superfici dell'assistente come Android e Android Auto. Gli utenti hanno la possibilità di aggiungere i widget visualizzati dall'assistente a l launcher, incoraggiando il coinvolgimento futuro.

Ad esempio, puoi configurare il widget di riepilogo dell'allenamento per la tua app di esercizi in modo che soddisfi i comandi vocali dell'utente che attivano il GET_EXERCISE_OBSERVATION BII. L'assistente visualizza in modo proattivo il widget quando gli utenti attivano questo BII effettuando richieste come "Hey Google, quanti chilometri ho percorso questa settimana su EsempioApp?"

Esistono decine di BII che coprono diverse categorie di interazione utente, consentendo a quasi tutte le app per Android di migliorare i propri widget per la voce. Per iniziare, consulta Integrare le azioni app con i widget Android.

Aggiungi un nome al widget

I widget devono avere un nome univoco quando vengono visualizzati nel selettore di widget.

I nomi dei widget vengono caricati dall'attributo label dell'elemento receiver del widget nel file AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Aggiungi una descrizione al widget

A partire da Android 12, fornisci una descrizione per il selettore di widget da visualizzare per il tuo widget.

Fornisci una descrizione per il widget utilizzando l'description attributo dell' <appwidget-provider> elemento:

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

Puoi utilizzare l' descriptionRes attributo nelle versioni precedenti di Android, ma il selettore di widget lo ignora.

Attiva transizioni più fluide

A partire da Android 12, i launcher forniscono una transizione più fluida quando un utente avvia l'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ò utilizzare @android:id/background nelle versioni precedenti di Android senza interruzioni, ma viene ignorata.

Utilizza la modifica in fase di runtime di RemoteViews

A partire da Android 12, puoi sfruttare diversi metodi RemoteViews che consentono la modifica in fase di runtime degli attributi RemoteViews. Per l'elenco completo dei metodi aggiunti, consulta il riferimento API RemoteViews.

L'esempio di codice seguente mostra come utilizzare alcuni di questi metodi.

// 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);