Consenti agli utenti di configurare i widget di app

I widget delle app possono essere configurabili. 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.

Dichiara l'attività di configurazione

Dichiara l'attività di configurazione come attività normale nel file manifest di Android. L'host del widget dell'app lo avvia con ACTION_APPWIDGET_CONFIGURE 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 la Attributo android:configure. Scopri di più sulla dichiarazione di questo file. Ecco un esempio 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é che non rientrano nell'ambito del pacchetto.

Non serve altro per avviare un'attività di configurazione. Poi devi implementare l'attività effettiva.

Implementa l'attività di configurazione

Ci sono due punti importanti da ricordare quando implementi l'attività:

• L'host del widget dell'app chiama l'attività di configurazione e l'attività di configurazione deve sempre restituire un risultato. Il risultato deve includere il widget App ID trasmesso dall'intent che ha avviato l'attività, salvato nell'intent extra come EXTRA_APPWIDGET_ID
• Il sistema non invia il messaggio di broadcast ACTION_APPWIDGET_UPDATE quando viene lanciata un'attività di configurazione, il che significa che non chiama il metodo onUpdate() quando viene creato il widget. È responsabilità dell'attività di configurazione richiedere un aggiornamento AppWidgetManager quando crei il widget per la prima volta. Tuttavia, onUpdate() viene chiamato per gli aggiornamenti successivi, viene saltato solo la prima volta.

Consulta gli snippet di codice nella sezione seguente per un esempio di come restituire un risultato dalla configurazione e aggiornare il widget.

Aggiorna 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 richiedendo un aggiornamento direttamente dal AppWidgetManager

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

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

   Kotlin

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

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }
   

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

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

   Kotlin

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

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);
   

3. Configura il widget in base alle preferenze dell'utente.

4. Al termine della configurazione, ottieni un'istanza AppWidgetManager chiamando il numero getInstance(Context):

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. Aggiorna il widget con un layout RemoteViews chiamando updateAppWidget(int,RemoteViews):

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

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

   Kotlin

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

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

Consulta le ListWidgetConfigureActivity.kt su GitHub.

Opzioni di configurazione widget

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

Nota: queste opzioni sono disponibili solo a partire da Android 12 (livello API 31). Puoi specificarli per le versioni precedenti di Android, ma il sistema li ignora e segue il comportamento predefinito.

Consentire agli utenti di riconfigurare i widget posizionati

Per consentire agli utenti di riconfigurare i widget esistenti, specifica il flag reconfigurable nell'attributo widgetFeatures di appwidget-provider. Consulta la guida per dichiarare il AppWidgetProviderInfo.xml file per altri contenuti informazioni. Ad esempio:

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

Gli utenti possono ricollegare il widget toccandolo e tenendolo premuto, quindi toccando il pulsante Riconfigura, contrassegnato come 1 nella figura 1.

Figura 1. Pulsante Riconfigura del widget.

Nota: il flag reconfigurable è stato introdotto in Android 9 (livello API 28), ma non è stato ampiamente supportato fino ad Android 12.

Utilizza la configurazione predefinita del widget

Puoi offrire un'esperienza più fluida con il widget, consentendo agli utenti di saltare della configurazione iniziale. Per farlo, specifica sia il configuration_optional e reconfigurable nel campo widgetFeatures. In questo modo viene ignorata la procedura di lancio dell'attività di configurazione dopo che un utente ha aggiunto il widget. Come menzionato in precedenza, l'utente può comunque riconfigurare il widget in seguito. Ad esempio, un widget orologio può bypassare la configurazione iniziale e mostrano 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>