Consenti agli utenti di configurare i widget di app

I widget delle app possono essere configurabili. Ad esempio, un widget orologio consente agli utenti di configurare il fuso orario.

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 Android. L'host del widget dell'app la avvia con l'azione ACTION_APPWIDGET_CONFIGURE, pertanto 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 completamente qualificato, perché il programma di avvio fa riferimento ad essa dall'esterno dell'ambito del pacchetto.

Non ti serve altro per avviare un'attività di configurazione. Successivamente, 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 l'ID del widget dell'app passato dall'intent che ha avviato l'attività, salvato negli extra dell'intent come EXTRA_APPWIDGET_ID.
  • Il sistema non invia la trasmissione di ACTION_APPWIDGET_UPDATE all'avvio di 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 dal AppWidgetManager quando si crea il widget per la prima volta. Tuttavia, onUpdate() viene chiamato per aggiornamenti successivi e 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. 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 esce dall'attività prima di raggiungere 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);

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

  4. Al termine della configurazione, recupera un'istanza di AppWidgetManager chiamando 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 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, vedi la classe di esempio 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.

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. Per saperne di più, consulta la guida per dichiarare il file AppWidgetProviderInfo.xml. 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.

Il pulsante viene visualizzato nell&#39;angolo in basso a destra
Figura 1. Pulsante Riconfigura del widget.

Utilizza la configurazione predefinita del widget

Puoi offrire un'esperienza con i widget più fluida consentendo agli utenti di saltare il passaggio di configurazione iniziale. A tale scopo, specifica sia i flag configuration_optional sia reconfigurable nel campo widgetFeatures. In questo modo viene ignorato l'avvio dell'attività di configurazione dopo che l'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ò 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>