Consenti agli utenti di configurare i widget di app

Progetta il widget in modo che gli utenti possano configurare tratti specifici. Ad esempio, un widget orologio può consentire agli utenti di configurare il fuso orario da visualizzare.

Se vuoi consentire agli utenti di configurare le impostazioni del widget, crea una configurazione del widget Activity. Questa attività viene avviata automaticamente dall' host del widget dell'app al momento della creazione del widget o in un secondo momento, a seconda delle opzioni di configurazione specificate.

Dichiarare l'attività di configurazione

Dichiara l'attività di configurazione come attività normale nel file manifest Android. L'host del widget dell'app lo avvia con l'ACTION_APPWIDGET_CONFIGURE azione, quindi l'attività deve accettare questo intent. Ad esempio:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Dichiara l'attività nel file AppWidgetProviderInfo.xml con l'attributo android:configure. Scopri di più sulla dichiarazione di questo file. Ecco un esempio di come dichiarare l'attività di configurazione:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

L'attività viene dichiarata con uno spazio dei nomi completo, perché il launcher fa riferimento a essa dall'esterno dell'ambito del pacchetto.

Questo è tutto ciò che ti serve per avviare un'attività di configurazione. Ora devi implementare l'attività vera e propria.

Implementare l'attività di configurazione

Quando implementi l'attività, devi tenere presente due punti importanti:

• L'host del widget dell'app chiama l'attività di configurazione e quest'ultima deve sempre restituire un risultato. Il risultato deve includere l'ID del widget dell'app passato dall'intent che ha avviato l'attività salvata negli extra dell'intent come EXTRA_APPWIDGET_ID.
  • Il sistema non invia la ACTION_APPWIDGET_UPDATE trasmissione quando viene avviata un'attività di configurazione, il che significa che non chiama inizialmente gli aggiornamenti del widget quando viene creato. È responsabilità dell'attività di configurazione richiedere un aggiornamento da GlanceAppWidget quando crei il widget per la prima volta. Tuttavia, gli aggiornamenti vengono attivati automaticamente per i cicli successivi.

Nella sezione seguente sono riportati snippet di codice che mostrano come restituire un risultato dalla configurazione e aggiornare il widget Glance.

Aggiornare il widget dall'attività di configurazione

Quando un widget utilizza un'attività di configurazione, è responsabilità dell'attività aggiornare il widget al termine della configurazione. Puoi farlo attivando un aggiornamento manuale direttamente dall'istanza GlanceAppWidget.

Ecco un riepilogo della procedura per aggiornare correttamente il widget e chiudere l'attività di configurazione:

1. Recupera l'ID del widget dell'app dall'intent che ha avviato l'attività:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Imposta il risultato dell'attività su RESULT_CANCELED.

   In questo modo, se l'utente esce dall'attività prima di raggiungere la fine, il sistema notifica all'host del widget dell'app che la configurazione è stata annullata e l'host non aggiunge il widget:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Configura il widget in base alle preferenze dell'utente, ad esempio scrivendo le selezioni in Datastore persistente o in un database locale.

4. Al termine della configurazione, recupera GlanceId corrispondente all'ID del widget della piattaforma:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Aggiorna i contenuti del widget chiamando la funzione di sospensione update sull'istanza GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Crea l'intent di restituzione, impostalo con il risultato dell'attività e completa l'attività:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Opzioni di configurazione del widget

Per impostazione predefinita, l'host del widget dell'app avvia l'attività di configurazione una sola volta, subito dopo che l'utente ha aggiunto il widget alla schermata Home. Tuttavia, puoi specificare opzioni che consentono all'utente di riconfigurare i widget esistenti o di saltare la configurazione iniziale del widget fornendo una configurazione predefinita.

Consentire agli utenti di riconfigurare i widget inseriti

Per consentire agli utenti di riconfigurare i widget esistenti, specifica il reconfigurable flag nell'attributo widgetFeatures di appwidget-provider. Ad esempio:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Gli utenti possono riconfigurare il widget toccandolo e tenendolo premuto e toccando il pulsante Riconfigura, etichettato con 1 nella Figura 1.

Utilizzare la configurazione predefinita del widget

Puoi offrire un'esperienza del widget più fluida consentendo agli utenti di saltare il passaggio di configurazione iniziale. Per farlo, specifica i configuration_optional e reconfigurable flag nel widgetFeatures campo. In questo modo, l'attività di configurazione non viene avviata dopo che un utente ha aggiunto il widget. Come accennato in precedenza, l'utente può comunque riconfigurare il widget in un secondo momento. Ad esempio, un widget orologio può ignorare la configurazione iniziale e mostrare il fuso orario del dispositivo per impostazione predefinita.

Ecco un esempio di come contrassegnare l'attività di configurazione come riconfigurabile e facoltativa:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>