Migliora il widget

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

Utilizzare 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 widget diversi.

Esistono due modi per ottenere colori dinamici:

• Utilizza il tema predefinito del sistema (@android:style/Theme.DeviceDefault.DayNight) nel layout principale.

• Usa il tema Material 3 (Theme.Material3.DynamicColors.DayNight) dalla libreria Material Componenti per Android, disponibile a partire da Material Componenti per Android v1.6.0.

Dopo aver impostato il tema nel layout principale, puoi utilizzare gli attributi di colore comuni nella directory principale o in uno qualsiasi dei suoi elementi secondari per scegliere i colori dinamici.

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

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

Nell'esempio seguente in cui viene utilizzato il tema Material 3, il colore del tema del dispositivo è "viola". Il colore di contrasto 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 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 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

Azioni app consente all'Assistente Google di mostrare widget in risposta a comandi vocali pertinenti degli utenti. Se configuri il widget in modo che risponda agli intent integrati (BII), la tua app può mostrare in modo proattivo i widget sulle piattaforme dell'assistente come Android e Android Auto. Gli utenti possono bloccare i widget visualizzati dall'assistente in Avvio app per incoraggiare il coinvolgimento in futuro.

Ad esempio, puoi configurare il widget Riepilogo esercizio per la tua app Allenamento in modo da eseguire i comandi vocali dell'utente che attivano lo standard BII GET_EXERCISE_OBSERVATION. L'assistente mostra proattivamente il tuo widget quando gli utenti attivano questo BII facendo richieste come "Hey Google, quanti chilometri ho corso questa settimana su ExampleApp?"

Esistono decine di BII che coprono diverse categorie di interazione degli utenti, in modo che quasi tutte le app Android possano migliorare i propri widget vocali. Per iniziare, consulta la sezione Integrare Azioni app con i widget Android.

Migliora l'esperienza del selettore widget della tua app

Android 12 ti consente di migliorare l'esperienza del selettore widget per la tua app aggiungendo anteprime e descrizioni dinamiche dei widget.

Aggiungi anteprime scalabili dei widget al selettore dei widget

A partire da Android 12, l'anteprima del widget mostrata nel selettore dei widget è scalabile. Forniscilo come layout XML impostato sulla dimensione predefinita del widget. In precedenza, l'anteprima dei widget era una risorsa tracciabile statica. In alcuni casi, le anteprime mostravano impropriamente il modo in cui i widget venivano visualizzati quando vengono aggiunti alla schermata Home.

Per implementare 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>

Consigliamo di utilizzare lo stesso layout del widget effettivo, con valori predefiniti o di test realistici. La maggior parte delle app usa gli stessi previewLayout e initialLayout. Per indicazioni sulla creazione di layout di anteprima accurati, consulta la sezione seguente in questa pagina.

Ti consigliamo di specificare entrambi gli attributi previewLayout e previewImage, in modo che la tua app possa ricorrere all'utilizzo di previewImage se il dispositivo dell'utente non supporta previewLayout. L'attributo previewLayout ha la precedenza sull'attributo previewImage.

Approcci consigliati per la creazione di anteprime accurate

Per implementare 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 valori predefiniti completando 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 vantaggio importante di questo approccio è che puoi fornire contenuti in 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 i dettagli.

Compatibilità con le versioni precedenti dei widget scalabili

Per consentire ai selettori dei widget su Android 11 (livello API 30) o inferiore di mostrare le anteprime del tuo widget, specifica l'attributo previewImage.

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

Aggiungi una descrizione per il widget

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

Fornisci una descrizione per il 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 verrà ignorato dal selettore di widget.

Consenti transizioni più fluide

A partire da Android 12, Avvio app offrono 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>

L'app può usare l'autorizzazione @android:id/background sulle versioni precedenti di Android senza interruzioni, ma questa operazione viene ignorata.

Utilizzare la modifica di runtime di RemoteView

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

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