Migliora il widget

Questa pagina contiene i dettagli dei miglioramenti facoltativi del widget disponibili a partire da Android 12 (livello API 31). Queste funzionalità sono facoltative, ma sono facili da implementare e migliorano l'esperienza con i 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. In questo modo, le transizioni sono più fluide e la coerenza è garantita 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 libreria Material Components for Android, disponibile a partire dalla versione 1.6.0 di Material Components for Android.

Una volta impostato il tema nel layout principale, puoi utilizzare gli attributi di colore comuni nel layout 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 intenso e lo sfondo del widget si adattano al tema chiaro e scuro 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>

Attivare il supporto vocale

Azioni app consente all'Assistente Google di visualizzare i widget in risposta ai comandi vocali pertinenti dell'utente. Configurando il tuo per rispondere agli intent integrati (BII), può mostrare in modo proattivo i widget sulle piattaforme con l'assistente, come Android e Android Auto. Gli utenti possono fissare widget mostrati dall'assistente alle sue Avvio app, incoraggiando un 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 visualizza proattivamente il tuo widget quando gli utenti attivano questo intent integrato facendo richieste come "Hey Google, quanti chilometri ho corso questa settimana App di esempio?"

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 l'articolo Integrare le Azioni app con i widget Android.

Migliorare l'esperienza del selettore di widget dell'app

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

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 disegnabile statica, in alcuni casi portano ad anteprime che riflettono in modo impreciso come appaiono i widget e verranno 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 sulla creazione di layout di anteprima precisi, consulta la seguente sezione .

Ti consigliamo di specificare entrambi gli attributi previewLayout e previewImage, in modo che la tua app possa tornare a utilizzare previewImage se il dispositivo dell'utente non supporta 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>

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.

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

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

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.

Aggiungi una descrizione per il widget

A partire da Android 12, fornisci una descrizione per il widget selettore da mostrare 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 lo descriptionRes sulle versioni precedenti di Android, ma viene ignorato dal widget selettore.

Consenti transizioni più fluide

A partire da Android 12, i lanciatori 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>

La tua app può usare @android:id/background sulle versioni precedenti di Android senza interruzioni, ma viene ignorato.

Utilizzare la modifica di RemoteViews in fase di runtime

A partire da Android 12, puoi sfruttare diversi metodi RemoteViews che consentono la modifica in fase di runtime degli attributi RemoteViews. Consulta la documentazione di 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);