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 vuoi creare un'app per sostituire la schermata Home o un'app simile, puoi anche consentire all'utente di incorporare dei widget implementando AppWidgetHost
. Non è
un aspetto che la maggior parte delle app ha bisogno di fare, ma se si crea un host proprio, è importante comprendere le obbligazioni contrattuali che quest'ultimo accetta implicitamente.
Questa pagina è incentrata sulle responsabilità relative all'implementazione di un AppWidgetHost
personalizzato. Per un esempio specifico di come implementare un AppWidgetHost
,
guarda il codice sorgente della schermata Home di Android
LauncherAppWidgetHost
.
Ecco una panoramica delle classi e dei concetti chiave relativi all'implementazione di un elemento AppWidgetHost
personalizzato:
Host widget app:
AppWidgetHost
fornisce l'interazione con il servizio AppWidget per le app che incorporano widget nella loro UI. Un elementoAppWidgetHost
deve avere un ID univoco all'interno del pacchetto dell'host. Questo ID persiste per tutti gli utilizzi dell'host. L'ID è in genere un valore hardcoded che assegni nell'app.ID widget app: a ogni istanza del widget viene assegnato un ID univoco al momento dell'associazione. Consulta la sezione
bindAppWidgetIdIfAllowed()
e, per maggiori dettagli, la sezione Widget di associazione che segue. L'host ottiene l'ID univoco utilizzandoallocateAppWidgetId()
. Questo ID persiste per tutta la durata del widget fino a quando non viene eliminato dall'host. Qualsiasi stato specifico dell'host, ad esempio dimensioni e posizione del widget, deve essere mantenuto dal pacchetto di hosting e associato all'ID del widget dell'app.Vista host del widget dell'app: pensa a
AppWidgetHostView
come a un frame con cui il widget viene aggregato ogni volta che deve essere visualizzato. Un widget viene associato a unAppWidgetHostView
ogni volta che viene gonfiato dall'host.- Per impostazione predefinita, il sistema crea una classe
AppWidgetHostView
, ma l'host può creare la propria sottoclasseAppWidgetHostView
estendendola. - A partire da Android 12 (livello API 31),
AppWidgetHostView
introduce i metodisetColorResources()
eresetColorResources()
per gestire i colori sovraccaricati dinamicamente. L'organizzatore è responsabile di fornire i colori per questi metodi.
- Per impostazione predefinita, il sistema crea una classe
Pacchetto opzioni:
AppWidgetHost
utilizza il pacchetto di opzioni per comunicare aAppWidgetProvider
informazioni sulla modalità di visualizzazione del widget, ad esempio l'elenco di intervalli di dimensioni, e sull'eventuale presenza del widget in una schermata di blocco o nella schermata Home. Queste informazioni consentono aAppWidgetProvider
di personalizzare i contenuti e l'aspetto del widget in base a come e dove viene visualizzato. Puoi utilizzareupdateAppWidgetOptions()
eupdateAppWidgetSize()
per modificare il pacchetto di un widget. Entrambi i metodi attivano il callback dionAppWidgetOptionsChanged()
alAppWidgetProvider
.
Widget di associazione
Quando un utente aggiunge un widget a un host, si verifica un processo chiamato associazione. Per associazione si intende associare un particolare ID widget dell'app a un host specifico e a un elemento AppWidgetProvider
specifico.
Le API di associazione consentono inoltre a un host di fornire un'interfaccia utente personalizzata per
l'associazione. Per utilizzare questa procedura, la tua 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 all'app per consentirle di aggiungere un widget all'host. Per verificare se la tua
app ha l'autorizzazione per aggiungere il widget, usa il
metodo
bindAppWidgetIdIfAllowed()
. Se bindAppWidgetIdIfAllowed()
restituisce false
, la tua app deve mostrare una finestra di dialogo in cui viene chiesto all'utente di concedere l'autorizzazione: "consenti" per l'aggiunta attuale del widget o "consenti sempre" per coprire tutte le aggiunte future di widget.
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 deve essere configurato. Per ulteriori informazioni, consulta 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, illustrate in maggiore dettaglio 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 distribuire l'ID del widget.Quando aggiungi un widget, controlla se è necessario avviare l'attività di configurazione. In genere, l'host deve avviare l'attività di configurazione del widget, se esistente e non contrassegnato come facoltativo, specificando entrambi i flag
configuration_optional
ereconfigurable
. Per maggiori dettagli, consulta Aggiornare il widget dall'attività di configurazione. Si tratta di un passaggio necessario per la visualizzazione di molti widget.I widget specificano la larghezza e l'altezza predefinite nei metadati
AppWidgetProviderInfo
. Questi valori sono definiti nelle celle (a partire da Android 12, se sono specificatitargetCellWidth
etargetCellHeight
) o nei dps se sono specificati solominWidth
eminHeight
. Consulta Attributi relativi alle dimensioni del widget.Assicurati che il widget sia impostato con almeno questo numero di dps. 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
eminHeight
.
Oltre ai requisiti elencati nella sezione precedente, versioni specifiche della piattaforma introducono funzionalità che assegnano nuove responsabilità all'host.
Determina il tuo approccio in base alla versione di Android target
Android 12
Android 12 (livello API 31) raggruppa un elemento List<SizeF>
aggiuntivo che contiene l'elenco
delle possibili dimensioni in dps che un'istanza del widget può includere nel pacchetto delle opzioni.
Il numero di dimensioni fornite dipende dall'implementazione dell'host. In genere, gli organizzatori forniscono due dimensioni per gli smartphone (verticale e orizzontale) e quattro dimensioni per i pieghevoli.
Esiste un limite di MAX_INIT_VIEW_COUNT
(16) al numero di RemoteViews
diversi che un AppWidgetProvider
può fornire a RemoteViews
.
Poiché gli oggetti AppWidgetProvider
mappano un oggetto RemoteViews
a ogni dimensione nel List<SizeF>
, non fornire più di MAX_INIT_VIEW_COUNT
dimensioni.
Android 12 introduce anche gli attributi maxResizeWidth
e maxResizeHeight
in dps. Ti consigliamo di fare in modo che un widget che utilizza almeno uno di questi
attributi non superi la dimensione specificata dagli attributi.
Risorse aggiuntive
- Consulta la documentazione di riferimento di
Glance
.