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

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

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