Crea un host widget

La schermata Home di Android, disponibile sulla maggior parte dei dispositivi Android, consente all'utente di incorporare widget di app (o widget) per accedere rapidamente ai contenuti. Se stai creando un'app che sostituisce la schermata Home o un'app simile, puoi anche consentire all'utente di incorporare i widget implementando AppWidgetHost. Non è un'operazione necessaria per la maggior parte delle app, ma se stai creando il tuo host, è importante comprendere le responsabilità contrattuali che un host accetta implicitamente.

Questa pagina si concentra sulle responsabilità relative all'implementazione di un AppWidgetHost personalizzato. Per un esempio specifico di come implementare un AppWidgetHost, consulta il codice sorgente della schermata Home di Android LauncherAppWidgetHost.

Ecco una panoramica delle classi e dei concetti chiave coinvolti nell'implementazione di un AppWidgetHost personalizzato:

• Host di widget per app: AppWidgetHost fornisce l'interazione con il servizio AppWidget per le app che incorporano widget nella propria UI. Un AppWidgetHost deve avere un ID univoco all'interno del pacchetto dell'host. Questo ID persiste in tutti gli utilizzi dell'host. L'ID è in genere un valore impostato come hardcoded che assegni nella tua app.

• ID widget dell'app: a ogni istanza del widget viene assegnato un ID univoco al momento dell'associazione. Consulta bindAppWidgetIdIfAllowed() e, per maggiori dettagli, la sezione Associazione dei widget di seguito. L'host ottiene l'ID univoco utilizzando allocateAppWidgetId(). Questo ID persiste per tutta la durata del widget finché non viene eliminato dall'host. Qualsiasi stato specifico dell'host, ad esempio le dimensioni e la posizione del widget, deve essere mantenuto dal pacchetto di hosting e associato all'ID widget dell'app.

• Visualizzazione host del widget dell'app: pensa a AppWidgetHostView come a un frame in cui il widget viene inserito ogni volta che deve essere visualizzato. Un widget è associato a un AppWidgetHostView ogni volta che viene gonfiato dall'host.

  • 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 setColorResources() e resetColorResources() per la gestione dei colori sovraccaricati dinamicamente. L'host è responsabile di fornire i 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 su una schermata di blocco o sulla 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 i metodi attivano il callback onAppWidgetOptionsChanged() a AppWidgetProvider.

Widget di associazione

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

Le API di associazione consentono inoltre a un host di fornire una UI personalizzata per l'associazione. Per utilizzare questa procedura, l'app deve dichiarare l'autorizzazione BIND_APPWIDGET nel manifest dell'host:

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

Ma questo è solo il primo passo. 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 dispone dell'autorizzazione per aggiungere il widget, utilizza il metodo bindAppWidgetIdIfAllowed(). Se bindAppWidgetIdIfAllowed() restituisce false, l'app deve mostrare 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 future di widget.

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

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

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

Responsabilità dell'organizzatore

Puoi specificare una serie di impostazioni di configurazione per i widget utilizzando i metadati AppWidgetProviderInfo. Puoi recuperare queste opzioni di configurazione, descritte in maggiore dettaglio nelle sezioni seguenti, dall'oggetto AppWidgetProviderInfo associato a un provider di widget.

Tutti gli host hanno le seguenti responsabilità:

• Quando aggiungi un widget, assegna l'ID widget come descritto in precedenza. Quando un widget viene rimosso dall'host, chiama deleteAppWidgetId() per deallocare l'ID widget.

• Quando aggiungi un widget, controlla se l'attività di configurazione deve essere avviata. 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 Aggiorna 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 risultati 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 sono specificati targetCellWidth e targetCellHeight) o in dp se sono specificati solo minWidth e minHeight. Consulta gli attributi di dimensionamento dei widget.

  Assicurati che il widget sia disposto con almeno questo numero di 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.

Suggerimenti per l'approccio

Oltre ai requisiti elencati nella sezione precedente, tieni presente i seguenti suggerimenti:

Il bundle di opzioni può contenere un List<SizeF> che contiene l'elenco delle dimensioni possibili in dp che un'istanza di widget può assumere. 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 pieghevoli.

Esiste un limite di MAX_INIT_VIEW_COUNT (16) per il numero di RemoteViews diversi 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.

Quando i widget specificano 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 documentazione di riferimento di Glance.