Crea un host widget

La schermata Home di Android, disponibile sulla maggior parte dei dispositivi Android, consente all' utente di incorporare i widget delle app (o i widget) per un accesso rapido ai contenuti. Se stai creando una sostituzione della schermata Home o un'app simile, puoi anche consentire all'utente di incorporare i widget implementando AppWidgetHost. Questa operazione non è necessaria per la maggior parte delle app, ma se stai creando il tuo host, è importante comprendere gli obblighi contrattuali che un host accetta implicitamente.

Questa pagina è incentrata sulle responsabilità coinvolte nell'implementazione di un AppWidgetHost personalizzato. Per un esempio specifico di come implementare un AppWidgetHost, consulta il codice sorgente della schermata Home di Android LauncherAppWidgetHost.

Di seguito è riportata una panoramica delle classi e dei concetti chiave coinvolti nell'implementazione di un AppWidgetHost personalizzato:

Host del widget dell'app: AppWidgetHost fornisce l'interazione con il servizio AppWidget per le app che incorporano i widget nella loro UI. Un AppWidgetHost deve avere un ID univoco all'interno del pacchetto dell'host. Questo ID persiste in tutti gli utilizzi dell'host. In genere, l'ID è un valore hardcoded che assegni nella tua app.
ID del widget dell'app: a ogni istanza del widget viene assegnato un ID univoco al momento del binding. Consulta bindAppWidgetIdIfAllowed() e, per maggiori dettagli, la sezione Binding dei widget che segue. L' host ottiene l'ID univoco utilizzando allocateAppWidgetId(). Questo ID persiste per tutta la durata del widget fino a quando non viene eliminato dall'host. Qualsiasi stato specifico dell'host, come le dimensioni e la posizione del widget, deve essere mantenuto dal pacchetto di hosting e associato all'ID del widget dell'app.
Visualizzazione dell'host del widget dell'app: considera AppWidgetHostView come un frame in cui il widget viene inserito ogni volta che deve essere visualizzato. Un widget è associato a un AppWidgetHostView ogni volta che l'host lo espande.
- Per impostazione predefinita, il sistema crea un AppWidgetHostView, ma l'host può creare la propria sottoclasse di AppWidgetHostView estendendola.
- A partire da Android 12 (livello API 31), AppWidgetHostView introduce i metodi the setColorResources() e resetColorResources() per la gestione dei colori sovraccaricati dinamicamente. L'host è responsabile della fornitura dei colori a questi metodi.
Bundle di opzioni: AppWidgetHost utilizza il bundle di opzioni per comunicare informazioni a AppWidgetProvider su come viene visualizzato il widget, ad esempio l' elenco degli intervalli di dimensioni—e se il widget si trova in una schermata di blocco o nella schermata Home. Queste informazioni consentono a AppWidgetProvider di personalizzare i contenuti e l'aspetto del widget in base a come e dove viene visualizzato. Puoi utilizzare updateAppWidgetOptions() e updateAppWidgetSize() per modificare il bundle di un widget. Entrambi questi metodi attivano il onAppWidgetOptionsChanged() callback a AppWidgetProvider.

Binding dei widget

Quando un utente aggiunge un widget a un host, si verifica un processo chiamato binding. Il binding si riferisce all'associazione di un ID di widget dell'app specifico a un host specifico e a un AppWidgetProvider specifico.

Le API di binding consentono inoltre a un host di fornire una UI personalizzata per il binding. Per utilizzare questo processo, la tua app deve dichiarare l' BIND_APPWIDGET autorizzazione nel manifest dell'host:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Ma questo è solo il primo passaggio. In fase di runtime, l'utente deve concedere esplicitamente l'autorizzazione alla tua app per consentirle di aggiungere un widget all'host. Per verificare se la tua app ha l'autorizzazione per aggiungere il widget, utilizza il bindAppWidgetIdIfAllowed() metodo. Se bindAppWidgetIdIfAllowed() restituisce false, la tua app deve visualizzare una finestra di dialogo che chiede all'utente di concedere l'autorizzazione: "Consenti" per l'aggiunta del widget corrente o "Consenti sempre" per coprire tutte le aggiunte di widget future.

Questo snippet fornisce un esempio di come visualizzare la finestra di dialogo:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

L'host deve verificare se il widget aggiunto da un utente richiede la configurazione. Per maggiori informazioni, consulta Consentire agli utenti di configurare i widget delle app widgets.

Responsabilità dell'host

Puoi specificare una serie di impostazioni di configurazione per i widget utilizzando i AppWidgetProviderInfo metadati. Puoi recuperare queste opzioni di configurazione, trattate in modo più dettagliato nelle sezioni seguenti, dall' AppWidgetProviderInfo oggetto associato a un fornitore di widget.

Indipendentemente dalla versione di Android di cui hai come target, tutti gli host hanno le seguenti responsabilità:

Quando aggiungi un widget, alloca l'ID del widget come descritto in precedenza. Quando un widget viene rimosso dall'host, chiama deleteAppWidgetId() per deallocare l'ID del widget.
Quando aggiungi un widget, verifica se è necessario avviare l'attività di configurazione. In genere, l'host deve avviare l'attività di configurazione del widget se esiste e non è contrassegnata come facoltativa specificando i flag configuration_optional e reconfigurable. Per maggiori dettagli, consulta Aggiornare il widget dall'attività di configurazione. Questo è un passaggio necessario per molti widget prima che possano essere visualizzati.

Nota: gestisci i casi irregolari in cui l'attività di configurazione non restituisce o termina con errori.
I widget specificano una larghezza e un'altezza predefinite nei metadati AppWidgetProviderInfo. Questi valori sono definiti in celle, a partire da Android 12, se vengono specificati targetCellWidth e targetCellHeight, o in dp se vengono specificati solo minWidth e minHeight. Consulta Attributi di dimensionamento dei widget.

Assicurati che il widget sia disposto con almeno questi dp. Ad esempio, molti host allineano icone e widget in una griglia. In questo scenario, per impostazione predefinita l'host aggiunge un widget utilizzando il numero minimo di celle che soddisfano i vincoli minWidth e minHeight.

Oltre ai requisiti elencati nella sezione precedente, le versioni specifiche della piattaforma introducono funzionalità che impongono nuove responsabilità all'host.

Determinare l'approccio in base alla versione di Android di cui hai come target

Android 12

Android 12 (livello API 31) include un List<SizeF> aggiuntivo che contiene l'elenco delle possibili dimensioni in dp che un'istanza del widget può assumere nel bundle di opzioni. Il numero di dimensioni fornite dipende dall'implementazione dell'host. In genere, gli host forniscono due dimensioni per gli smartphone (verticale e orizzontale) e quattro dimensioni per i dispositivi pieghevoli.

Esiste un limite di MAX_INIT_VIEW_COUNT (16) al numero di diversi RemoteViews che un AppWidgetProvider può fornire a RemoteViews. Poiché gli oggetti AppWidgetProvider mappano un oggetto RemoteViews a ogni dimensione in List<SizeF>, non fornire più di MAX_INIT_VIEW_COUNT dimensioni.

Android 12 introduce anche gli attributi maxResizeWidth e maxResizeHeight in dp. Ti consigliamo di non superare le dimensioni specificate dagli attributi per un widget che utilizza almeno uno di questi attributi.

Risorse aggiuntive

Consulta la Glance documentazione di riferimento.