Layout dei widget canonici

Crea layout di widget efficaci identificando innanzitutto i contenuti principali. Il layout determina la modalità di organizzazione delle informazioni e degli elementi interattivi all'interno del widget. Per semplificare questa procedura, Android offre diversi layout predefiniti per widget di tipo barra degli strumenti, testo, elenco e griglia.

Testo

I layout di testo sono ideali per visualizzare informazioni concise. Migliora l'aspetto visivo del widget includendo facoltativamente un'immagine accanto al testo.

Solo testo

Ideale per titoli, aggiornamenti di stato, descrizioni brevi o qualsiasi scenario in cui una singola riga di testo trasmette efficacemente il messaggio.

Testo e immagine

Includi un'immagine per un maggiore impatto visivo. Per ulteriori informazioni, consulta Punti di interruzione per scoprire come adattare questo layout a diverse dimensioni dello schermo.

Barre degli strumenti

Utilizza i layout della barra degli strumenti per consentire agli utenti di accedere rapidamente alle attività utilizzate di frequente nella tua app, in un layout flessibile che si adatta alle dimensioni dei widget.

Barra degli strumenti di ricerca

Un layout della barra degli strumenti di ricerca è progettato intenzionalmente per concentrare l'attenzione sulla ricerca come azione principale nella barra degli strumenti. I pulsanti aggiuntivi possono fornire accesso rapido alle funzioni utilizzate di frequente.

Barra degli strumenti

Le barre degli strumenti presentano il branding dell'app seguito da pulsanti per le attività più utilizzate che sono ideali per le impostazioni attivabili/disattivabili o i link alle attività. Quando si ridimensionano, le opzioni meno di uso comune possono essere nascoste a favore di azioni più comuni. Use Breakpoints to add a new minimum 48dp tappable button when there's room.

Elenchi

Utilizza i layout a elenco per organizzare più elementi in un formato chiaro e scansionabile. È ideale per titoli di notizie, elenchi di cose da fare o messaggi. Organizza i contenuti in un elenco strutturato e scansionabile. Scegli tra la presentazione in contenitori o senza contenitori in base alle esigenze dei contenuti.

Elenco di testo e immagini

Gli elenchi di testo e immagini scansionabili sono perfetti per mostrare più tipi di contenuti, come titoli di notizie, playlist con copertine di album o messaggi.

Elenco di controllo

Il layout dell'elenco di controllo è perfetto per visualizzare le attività, fornendo target di tocco chiari per consentire agli utenti di contrassegnare rapidamente gli elementi come completati.

Elenco di azioni

Fornisci un raggruppamento di controlli intuitivo con gli elenchi di azioni, in cui gli stati visivi di attivazione/disattivazione offrono un feedback immediato sullo stato degli elementi.

Immagine a pagina intera

Ideale per mostrare immagini immersive a pagina intera su Android 17 e versioni successive, questo layout utilizza lo scorrimento con allineamento per garantire che ogni elemento figlio sia perfettamente allineato all'altezza del contenitore del widget.

Griglia

Presenta le immagini in una griglia compatta, flessibile e visivamente ricca con etichette facoltative. Utilizza colonne e righe che si adattano a diverse dimensioni dello schermo.

Solo immagine

Crea gallerie di immagini scorrevoli e di grande impatto visivo utilizzando le griglie solo immagini. Righe e colonne si adattano automaticamente a varie dimensioni dello schermo per una presentazione ottimale.

Immagine e testo

Puoi anche incorporare etichette e descrizioni di testo, arricchendo i contenuti della griglia di immagini con contesto e informazioni aggiuntive.

Esempi di codice

La tabella seguente mappa ogni layout canonico alla relativa implementazione di Jetpack Glance nel repository GitHub degli esempi della piattaforma Android.

Layout canonico File di riferimento Consulenza
Layout a elenco azioni
  • Gestisci le azioni degli elementi dell'elenco con i callback delle azioni di Glance e assicurati che gli stati vengano aggiornati correttamente.
Layout a elenco
  • Implementa l'attivazione/disattivazione dello stato della casella di controllo utilizzando i parametri o i callback delle azioni per aggiornare gli elementi della raccolta.
  • Utilizza i callback delle azioni di Glance, come `actionRunCallback`, `ActionCallback(actionParametersOf(...))` o `actionStartActivity(...)`, per i parametri `onClick` del widget per gestire gli eventi di clic, ad esempio toccare una casella di controllo.
Layout della barra degli strumenti espressiva
  • Evita gli errori di importazione di `ColorProvider`: importa `androidx.glance.unit.ColorProvider` e utilizza `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilizza `GlanceModifier.background(Color)` direttamente per i colori di sfondo uniformi anziché `ColorProvider`.
Layout della griglia di immagini
  • Utilizza colori uniformi (`GlanceModifier.background`) o drawable locali per gli elementi immagine, a meno che non sia configurata o richiesta una libreria di caricamento delle immagini.
Layout a elenco di testo e immagini
  • Casi d'uso comuni: feed di notizie, elenchi di articoli, cronologie degli allenamenti, feed di messaggi ed elenchi di miniature verticali.
  • Bilancia l'altezza della riga dell'elenco e il ritaglio del testo quando combini immagini in miniatura con testo primario/secondario.
Layout di testo lungo
  • Se moltiplichi i valori `Dp`, ad esempio `2 * padding`, importa `androidx.compose.ui.unit.times`.
  • Segui le regole di dimensionamento: assicurati che le dimensioni di `dimens.xml` vengano utilizzate per il padding e il ridimensionamento della tipografia.
Layout della barra degli strumenti di ricerca
  • Evita gli errori di importazione di `ColorProvider`: importa `androidx.glance.unit.ColorProvider` e utilizza `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilizza `GlanceModifier.background(Color)` direttamente per i colori di sfondo uniformi anziché ColorProvider.
Layout dell'immagine a pagina intera / scorrimento con allineamento
  • Imposta `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` su LazyColumn per lo scorrimento con allineamento.
  • Se implementi lo scorrimento con allineamento, sono necessari Glance 1.3.0-alpha02 o versioni successive, la compilazione dell'SDK 37 (Baklava) o versioni successive e il plug-in Android per Gradle (AGP) 9.1.0 o versioni successive.
  • Imposta `override val sizeMode: SizeMode = SizeMode.Exact` nella classe del fornitore di widget.
Layout della barra degli strumenti standard
  • Consulta Risoluzione dei problemi per evitare gli errori di importazione di `ColorProvider`: utilizza `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilizza `GlanceModifier.background(Color)` direttamente per i colori di sfondo uniformi anziché `ColorProvider`.
Layout di testo con immagine
  • Segui le regole di dimensionamento del layout reattivo per adattare testo e immagine affiancati o impilati in base alle dimensioni del widget disponibili.