La schermata Home di Android, disponibile sulla maggior parte dei dispositivi Android, consente
widget di app (o widget) incorporati dall'utente per
rapido accesso ai contenuti. Se vuoi sostituire la schermata Home o
app simile, puoi anche consentire all'utente di incorporare widget implementando
AppWidgetHost
Non è
per la maggior parte delle app, ma se crei il tuo host,
è importante comprendere gli obblighi contrattuali implicitamente accettati da un host.
Questa pagina si concentra sulle responsabilità derivanti dall'implementazione di una
AppWidgetHost
. Per un esempio specifico di come implementare un'AppWidgetHost
,
guarda il codice sorgente della schermata Home di Android
LauncherAppWidgetHost
Di seguito è riportata una panoramica delle classi e dei concetti principali coinvolti nell'implementazione di un
AppWidgetHost
personalizzato:
Host del widget dell'app: il
AppWidgetHost
fornisce l'interazione con il Servizio AppWidget per app che incorporano widget nell'interfaccia utente.AppWidgetHost
deve avere un ID univoco all'interno del pacchetto dell'host. Questo ID persiste in tutti gli utilizzi dell'host. Di solito, l'ID è un valore hardcoded che puoi assegnare 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 di widget che segue. La ottiene l'ID univoco utilizzandoallocateAppWidgetId()
Questo ID persiste per tutta la durata del widget finché non viene eliminato dal widget. . Qualsiasi stato specifico dell'host, ad esempio le dimensioni e la posizione deve essere mantenuto dal pacchetto di hosting e associato al dell'ID widget dell'app.Host view widget dell'app: pensa a
AppWidgetHostView
come frame che il widget è aggregato ogni volta che deve essere visualizzato. Un widget è associata a un valoreAppWidgetHostView
ogni volta che il widget viene aumentato in modo artificioso .- Per impostazione predefinita, il sistema crea un
AppWidgetHostView
, ma l'host può crea la propria sottoclasse diAppWidgetHostView
estendendola. - A partire da Android 12 (livello API 31),
AppWidgetHostView
introduce la ilsetColorResources()
eresetColorResources()
per la gestione dinamica dei colori con sovraccarico. L'host è responsabile di fornire i colori a questi metodi.
- Per impostazione predefinita, il sistema crea un
Gruppo di opzioni:
AppWidgetHost
utilizza il pacchetto di opzioni per comunicare informazioniAppWidgetProvider
su come viene visualizzato il widget, ad esempio elenco di intervalli di dimensioni e indica se il si trovi in una schermata di blocco o nella schermata Home. Queste informazioni consentonoAppWidgetProvider
personalizza i contenuti e l'aspetto del widget in base a come e in cui viene visualizzata. Puoi utilizzareupdateAppWidgetOptions()
eupdateAppWidgetSize()
per modificare il bundle di un widget. Entrambi i metodi attivanoonAppWidgetOptionsChanged()
il callback alAppWidgetProvider
.
Widget di associazione
Quando un utente aggiunge un widget a un host, si verifica un processo chiamato associazione. Associazione
si riferisce all'associazione di un particolare ID widget dell'app a un host specifico e a un
specifico per AppWidgetProvider
.
L'associazione delle API consente inoltre a un host di fornire una UI personalizzata
associazione. Per poter utilizzare questa procedura, la tua app deve dichiarare
BIND_APPWIDGET
autorizzazione 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
autorizzazione alla tua app per consentirle di aggiungere un widget all'host. Per verificare se le tue
app dispone dell'autorizzazione per aggiungere il widget, usa
bindAppWidgetIdIfAllowed()
. Se bindAppWidgetIdIfAllowed()
restituisce false
, la tua app deve visualizzare un
Finestra di dialogo che chiede all'utente di concedere l'autorizzazione: "consenti" per il widget corrente
addizioni o "consenti sempre" per coprire tutte le future aggiunte 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 è necessario configurare il widget aggiunto da un utente. Per Per ulteriori informazioni, vedi Consentire agli utenti di configurare le app widget.
Responsabilità dell'organizzatore
È possibile specificare una serie di impostazioni di configurazione per i widget utilizzando
AppWidgetProviderInfo
metadati.
Puoi recuperare queste opzioni di configurazione, trattate più dettagliatamente nel
sezioni seguenti, dal
AppWidgetProviderInfo
associato a un fornitore di widget.
Indipendentemente dalla versione di Android scelta come target, tutti gli host hanno le seguenti responsabilità:
Quando aggiungi un widget, alloca il relativo ID come descritto in precedenza. Quando il widget viene rimosso dall'organizzatore, la chiamata
deleteAppWidgetId()
per deallocare l'ID widget.Quando aggiungi un widget, controlla se l'attività di configurazione deve essere è stato avviato. In genere, l'host deve avviare la configurazione del widget l'attività se esiste e non è contrassegnata come facoltativa specificando sia il Flag
configuration_optional
ereconfigurable
. Consulta Aggiornare il widget dall'attività di configurazione per maggiori dettagli. Si tratta di un passaggio necessario per molti widget prima che possano essere visualizzati.I widget specificano una larghezza e un'altezza predefinite nell'
AppWidgetProviderInfo
metadati. Questi valori sono definiti nelle celle, a partire da Android 12, setargetCellWidth
etargetCellHeight
sono o dps se sono specificati solominWidth
eminHeight
. Consulta Attributi di dimensionamento del widget.Assicurati che il widget abbia almeno questo numero di dps. Per ad esempio, molti host allineano icone e widget in una griglia. In questo scenario, per per impostazione predefinita l'host aggiunge il widget utilizzando il numero minimo di celle che soddisfino i vincoli
minWidth
eminHeight
.
Oltre ai requisiti elencati nella sezione precedente, le versioni della piattaforma introducono funzionalità che pongono nuove responsabilità .
Stabilisci il tuo approccio in base alla versione di Android target
Android 12
Android 12 (livello API 31) raggruppa un elemento List<SizeF>
aggiuntivo contenente l'elenco
delle possibili dimensioni in dps che un'istanza di widget può assumere nel pacchetto di opzioni.
Il numero di dimensioni fornite dipende dall'implementazione dell'host. Host generalmente
che offrono due formati per gli smartphone: verticale e orizzontale,
per i pieghevoli.
Esiste un limite di MAX_INIT_VIEW_COUNT
(16) al numero di
RemoteViews
che un AppWidgetProvider
può fornire a
RemoteViews
.
Poiché gli oggetti AppWidgetProvider
mappano un oggetto RemoteViews
a ogni dimensione nel
List<SizeF>
, non specificare più di MAX_INIT_VIEW_COUNT
dimensioni.
Android 12 introduce anche
maxResizeWidth
e
maxResizeHeight
in dps. Consigliamo di usare un widget che utilizza almeno uno di questi
attributi non superano le dimensioni specificate dagli attributi.
Risorse aggiuntive
- Consulta la documentazione di riferimento di
Glance
.