Crea un host widget

La schermata Home di Android, disponibile sulla maggior parte dei dispositivi Android, consente all'utente di incorporare widget (o widget) di app per accedere rapidamente ai contenuti. Se stai creando un'app simile o un'app che sostituisce la schermata Home, puoi anche consentire all'utente di incorporare i widget implementando AppWidgetHost. Per la maggior parte delle app questa operazione non è obbligatoria. Se invece ne crei uno, è importante comprendere le obbligazioni contrattuali che l'host accetta implicitamente.

Questa pagina è incentrata 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.

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

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

• ID widget dell'app: a ogni istanza del widget viene assegnato un ID univoco al momento dell'associazione. Consulta bindAppWidgetIdIfAllowed() e, per ulteriori dettagli, la sezione Eseguire il binding dei widget che segue. L'attività ospitante 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 dell'host del widget dell'app: considera AppWidgetHostView come un riquadro in cui viene inserito il widget ogni volta che deve essere visualizzato. Un widget viene associato a un AppWidgetHostView ogni volta che viene visualizzato dall'host.

  • Per impostazione predefinita, il sistema crea un AppWidgetHostView, ma l'host può creare la propria sottoclasse di AppWidgetHostView estendendolo.
  • A partire da Android 12 (livello API 31), AppWidgetHostView introduce i metodi setColorResources() e resetColorResources() per gestire i colori sovraccarichi in modo dinamico. L'organizzatore è responsabile di fornire i colori a questi metodi.

• Pacchetto di opzioni: AppWidgetHost utilizza il pacchetto di opzioni per comunicare al AppWidgetProvider informazioni sulla visualizzazione del widget, ad esempio l'elenco delle fasce di dimensioni, e se il widget si trova nella 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 callback onAppWidgetOptionsChanged() all'AppWidgetProvider.

Widget di rilegatura

Quando un utente aggiunge un widget a un host, si verifica un processo chiamato associazione. Con il termine associazione si fa riferimento all'associazione di un determinato ID widget dell'app a un host e a un AppWidgetProvider specifici.

Le API di binding consentono inoltre a un host di fornire un'interfaccia utente personalizzata per la convalida. Per utilizzare questa procedura, la tua app deve dichiarare l'autorizzazione BIND_APPWIDGET nel file 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 all'app l'autorizzazione per aggiungere un widget all'host. Per verificare se la tua app ha l'autorizzazione per aggiungere il widget, utilizza il metodo bindAppWidgetIdIfAllowed(). Se bindAppWidgetIdIfAllowed() restituisce false, l'app deve mostrare una dialoga 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.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

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 è necessario configurare il widget aggiunto da un utente. Per maggiori informazioni, vedi Consentire 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 modo più dettagliato nelle sezioni seguenti, dall'oggetto AppWidgetProviderInfo associato a un provider di widget.

Indipendentemente dalla versione di Android scelta come target, 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 annullare l'allocazione dell'ID widget.

• Quando aggiungi un widget, controlla se è necessario avviare l'attività di configurazione. In genere, l'attività di configurazione del widget deve essere avviata dall'host se esiste e non è contrassegnata come facoltativa specificando entrambi 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.

• I widget specificano una larghezza e un'altezza predefinite nei metadati AppWidgetProviderInfo. Questi valori sono definiti nelle celle, a partire da Android 12, se vengono specificati targetCellWidth e targetCellHeight, o in dps se vengono specificati solo minWidth e minHeight. Consulta Attributi di dimensionamento dei widget.

  Assicurati che il widget sia impostato con almeno questo numero di pixel per pollice. 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, versioni specifiche della piattaforma introducono funzionalità che richiedono nuove responsabilità all'host.

Definisci il tuo approccio in base alla versione di Android scelta come target

Android 12

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

Esiste un limite di MAX_INIT_VIEW_COUNT (16) per il 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 inoltre gli attributi maxResizeWidth e maxResizeHeight in dps. Consigliamo di fare in modo che un widget che utilizza almeno uno di questi attributi non superi le dimensioni specificate dagli attributi.

Risorse aggiuntive

• Consulta la documentazione di riferimento di Glance.