I widget delle app possono essere configurabili. Ad esempio, un widget dell'orologio può consentire agli utenti configurare il fuso orario da visualizzare.
Se vuoi consentire agli utenti di configurare le impostazioni del widget, crea una configurazione del widget Activity
. L'attività è
avviato automaticamente dall'host del widget dell'app quando viene creato
o una versione successiva, a seconda delle opzioni di configurazione
specificare.
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 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 completamente qualificato, perché il programma di avvio fa riferimento ad essa dall'esterno dell'ambito del pacchetto.
Non serve altro per avviare un'attività di configurazione. Poi devi implementare l'attività effettiva.
Implementare 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 metodoonUpdate()
quando viene creato il widget. È responsabilità dell'attività di configurazione richiedere un aggiornamento dalAppWidgetManager
quando si crea il widget per la prima volta. Tuttavia,onUpdate()
viene chiamato per aggiornamenti successivi, viene ignorato solo il per 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à del
l'attività di aggiornamento del widget al termine della configurazione. Puoi farlo
richiedendo un aggiornamento direttamente dal
AppWidgetManager
.
Di seguito è riportato un riepilogo della procedura per aggiornare correttamente il widget e chiudere la finestra attività di configurazione:
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); }
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);
Configura il widget in base alle preferenze dell'utente.
Al termine della configurazione, recupera un'istanza di
AppWidgetManager
chiamandogetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Aggiorna il widget con un Layout di
RemoteViews
richiamandoupdateAppWidget(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);
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 dei 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 agli utenti di riconfigurare i widget esistenti o saltare la configurazione iniziale dei widget fornendo una configurazione predefinita.
Consenti agli utenti di riconfigurare i widget posizionati
Per consentire agli utenti di riconfigurare i widget esistenti, specifica
reconfigurable
flag nel
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.

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