I widget delle app possono essere configurabili. Ad esempio, con il widget orologio gli utenti possono 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
Dichiarare l'attività di configurazione come una normale attività nel file manifest Android. L'host del widget dell'app la avvia con l'azione
ACTION_APPWIDGET_CONFIGURE
, quindi l'attività deve accettare questo intent. Ecco alcuni esempi:
<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ù su come dichiarare 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é in Avvio applicazioni fa riferimento all'esterno dell'ambito del pacchetto.
Questo è tutto ciò che serve per avviare un'attività di configurazione. Poi, devi implementare l'attività effettiva.
Implementare l'attività di configurazione
Quando implementi l'attività, tieni a mente due punti importanti:
- L'host del widget dell'app chiama l'attività di configurazione e questa deve sempre restituire un risultato. Il risultato deve includere l'ID widget dell'app trasmesso dall'intent che ha avviato l'attività, salvato negli extra dell'intent come
EXTRA_APPWIDGET_ID
. - Il sistema non invia la trasmissione
ACTION_APPWIDGET_UPDATE
quando viene avviata 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 daAppWidgetManager
quando crei il widget per la prima volta. Tuttavia,onUpdate()
viene chiamato per aggiornamenti successivi: viene ignorato 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à aggiornarlo al termine della configurazione. Per farlo, puoi richiedere un aggiornamento direttamente dal AppWidgetManager
.
Ecco un riepilogo della procedura per aggiornare correttamente il widget e chiudere l'attività di configurazione:
Recupera l'ID widget 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 ritira l'attività prima di aver raggiunto la fine, il sistema comunica all'host del widget dell'app che la configurazione è stata annullata e 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, ottieni un'istanza di
AppWidgetManager
chiamandogetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Aggiorna il widget con un layout
RemoteViews
chiamandoupdateAppWidget(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 termina 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();
Per un esempio, consulta la classe di esempio di 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 ha aggiunto il widget alla schermata Home. Tuttavia, puoi specificare opzioni che consentono agli utenti di riconfigurare i widget esistenti o di saltare la configurazione iniziale del widget fornendo una configurazione predefinita del widget.
Consenti 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
. Per ulteriori informazioni, consulta la guida per dichiarare il file AppWidgetProviderInfo.xml
. Ecco alcuni esempi:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Gli utenti possono riconfigurare il widget toccando e tenendo premuto il widget, quindi toccando il pulsante Riconfigura, con l'etichetta 1 nella figura 1.
Utilizza la configurazione predefinita del widget
Puoi offrire un'esperienza più fluida con i widget consentendo agli utenti di saltare il
passaggio iniziale della configurazione. Per farlo, specifica entrambi i flag configuration_optional
e reconfigurable
nel campo widgetFeatures
. Ciò ignora
l'avvio dell'attività di configurazione dopo che un utente ha aggiunto il widget. Come accennato in precedenza, l'utente può ancora riconfigurare il widget in seguito. Ad esempio, un widget orologio può ignorare la configurazione iniziale e
mostrare il fuso orario del dispositivo per impostazione predefinita.
Di seguito è riportato 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>
Consenti agli utenti di fissare un widget
Sui dispositivi con Android 8.0 (livello API 26) e versioni successive, gli strumenti di avvio, che consentono agli utenti di creare scorciatoie bloccate, consentono anche di bloccare i widget sulla schermata Home. Analogamente alle scorciatoie bloccate, questi widget bloccati consentono agli utenti di accedere a attività specifiche nella tua app e possono essere aggiunti alla schermata Home direttamente dall'app, come mostrato nel seguente video.
Nella tua app, puoi creare una richiesta al sistema di bloccare un widget su un'Avvio app supportato svolgendo i seguenti passaggi:
Assicurati di dichiarare un widget nel file manifest dell'app.
Chiama il metodo
requestPinAppWidget()
, come mostrato nello snippet di codice che segue:
Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context) val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java) if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). val successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT) appWidgetManager.requestPinAppWidget(myProvider, null, successCallback) }
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class); if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). PendingIntent successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ new Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT); appWidgetManager.requestPinAppWidget(myProvider, null, successCallback); }