Migliora il widget

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 facili da implementare e migliorano l'esperienza degli utenti con i widget.

Utilizza colori dinamici

A partire da Android 12, un widget può usare i colori del tema del dispositivo per pulsanti, sfondi e altri componenti. In questo modo, le transizioni sono più fluide e la coerenza è garantita tra i diversi widget.

Esistono due modi per ottenere colori dinamici:

Una volta impostato il tema nel layout principale, puoi utilizzare gli attributi di colore comuni nel elemento principale o in uno dei suoi elementi secondari per rilevare i colori dinamici.

Ecco 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 di accento 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>
Widget in tema modalità Luce
Figura 1. Widget con tema chiaro.
Widget con il tema modalità Buio
Figura 2. Widget in tema scuro.

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:

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

Attivare il supporto vocale

Azioni app consente all'Assistente Google di visualizzare i widget in risposta ai comandi vocali pertinenti dell'utente. Se configuri il widget in modo che risponda agli intent integrati (BIIs), la tua app può mostrare in modo proattivo i widget sulle piattaforme dell'assistente come Android e Android Auto. Gli utenti hanno la possibilità di bloccare i widget visualizzati dall'assistente nel proprio Avvio app, incoraggiando così il coinvolgimento futuro.

Ad esempio, puoi configurare il widget di riepilogo dell'allenamento per la tua app di allenamento per soddisfare i comandi vocali dell'utente che attivano il BII GET_EXERCISE_OBSERVATION. L'assistente mostra in modo proattivo il tuo widget quando gli utenti attivano questa BII facendo richieste come "Hey Google, quanti chilometri ho corso questa settimana su ExampleApp?"

Esistono dozzine di intent integrati 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.

Migliorare l'esperienza del selettore di widget dell'app

Android 12 consente di aggiungere anteprime e descrizioni dei widget in scala. Android 15 ti consente di migliorare l'esperienza di selezione dei widget per la tua app con le anteprime dei widget generate.

Per migliorare l'esperienza del selettore di widget della tua app, fornisci un'anteprima del widget generato sui dispositivi Android 15 e versioni successive, un'anteprima del widget scalata (specificando un previewLayout) per i dispositivi Android 12-Android 14 e un previewImage per le versioni precedenti.

Aggiungi le anteprime dei widget generate al selettore widget

Le app devono impostare il valore compileSdk su 35 o versioni successive nel file del modulo build.gradle per poter fornire RemoteViews al selettore di widget su dispositivi Android 15 o versioni successive. Ciò significa che le app possono aggiornare i contenuti nel selettore in modo che siano più rappresentativi di ciò che l'utente vede.

Le app possono utilizzare i metodi AppWidgetManager, setWidgetPreview e getWidgetPreview per aggiornare l'aspetto dei propri widget con informazioni aggiornate e personalizzate.

Generare un'anteprima aggiornata con Jetpack Glance

Glance.compose esegue una composizione, pertanto nel corpo del composable non vengono utilizzate funzioni di sospensione, flussi o chiamate asincrone simili. Devi invece utilizzare dati costanti.

L'esempio seguente utilizza Jetpack Glance per generare un'anteprima aggiornata. È necessaria un'impostazione di compilazione compileSdk pari o successiva alla 35 per visualizzare setWidgetPreview come metodo in questo snippet.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Generare un'anteprima aggiornata senza Jetpack Glance

Puoi usare RemoteViews senza Riepilogo. L'esempio seguente carica una risorsa di layout del widget XML e la imposta come anteprima. Affinché setWidgetPreview venga visualizzato come metodo in questo snippet, è richiesta un'impostazione di build compileSdk pari o superiore a 35.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

Aggiungere anteprime dei widget scalabili al selettore di widget

A partire da Android 12, l'anteprima del widget visualizzata nel selettore dei widget è ridimensionabile. Lo fornisci come layout XML impostato sulle dimensioni predefinite del widget. In precedenza, l'anteprima del widget era una risorsa drawable statica, in alcuni casi le anteprime non riflettevano con precisione l'aspetto dei widget quando venivano aggiunti alla schermata Home.

Per implementare le anteprime dei widget scalabili, utilizza 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 o di test realistici. La maggior parte delle app utilizza gli stessi previewLayout e initialLayout. Per indicazioni sulla creazione di layout di anteprima accurati, consulta la sezione seguente di 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 dei widget scalabili, utilizza l'attributo previewLayout dell'elemento appwidget-provider per fornire un layout XML:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Un&#39;immagine che mostra un&#39;anteprima del widget
Figura 3. Un'anteprima del widget che per impostazione predefinita viene visualizzata in un'area 3x3, ma può essere adattata a un'area 3x1 grazie al layout XML.

Per visualizzare un'anteprima accurata, puoi fornire direttamente il layout del widget effettivo con i valori predefiniti seguendo questi passaggi:

  • Impostazione di android:text="@string/my_widget_item_fake_1" per gli elementi TextView.

  • Impostazione di un'immagine o un'icona predefinita o segnaposto, ad esempio android:src="@drawable/my_widget_icon", per i componenti ImageView.

Senza valori predefiniti, l'anteprima potrebbe mostrare valori errati o vuoti. Un vantaggio importante di questo approccio è che puoi fornire contenuti di anteprima localizzati.

Per gli approcci consigliati per anteprime più complesse che contengono ListView, GridView o StackView, consulta Creare anteprime accurate che includono elementi dinamici per maggiori dettagli.

Compatibilità con le versioni precedenti per 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 widget, specifica l'attributo previewImage.

Se modifichi l'aspetto del widget, aggiorna l'immagine di anteprima.

Aggiungere un nome al widget

I widget devono avere un nome univoco quando vengono visualizzati nel selettore dei 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 per il widget

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

Un&#39;immagine che mostra un selettore di widget che mostra un widget e la relativa descrizione
Figura 4. Selettore widget di esempio che mostra un widget e la relativa descrizione.

Fornisci una descrizione del widget utilizzando l'attributo description dell'elemento &lt;appwidget-provider&gt;:

<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 di widget.

Attiva 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ò utilizzare @android:id/background sulle versioni precedenti di Android senza interruzioni, ma viene ignorata.

Utilizzare la modifica di RemoteViews in fase di runtime

A partire da Android 12, puoi sfruttare diversi metodi RemoteViews che consentono la modifica del runtime degli attributi RemoteViews. Consulta la documentazione di riferimento dell'API RemoteViews per l'elenco completo dei metodi aggiunti.

Il seguente esempio di codice 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);