Layout dei widget canonici

Crea layout efficaci per i widget identificando innanzitutto i contenuti principali. Il layout determina il modo in cui le informazioni e gli elementi interattivi sono organizzati all'interno del widget. Android offre diversi layout predefiniti per widget di tipo barra degli strumenti, testo, elenco e griglia per semplificare questo processo.

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, vedi Punti di interruzione per scoprire come adattare questo layout a schermi di dimensioni diverse.

Barre degli strumenti

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

Barra degli strumenti di ricerca

Il layout di una barra degli strumenti di ricerca è progettato intenzionalmente per attirare l'attenzione sulla ricerca come azione principale nella barra degli strumenti. Altri pratici pulsanti possono fornire un rapido accesso alle funzioni utilizzate di frequente.

Barra degli strumenti

Le barre degli strumenti mostrano il brand dell'app seguito dai pulsanti per le attività più utilizzate, ideali per le impostazioni attivabili/disattivabili o i link alle attività. Quando ridimensioni, le opzioni utilizzate meno di frequente possono essere nascoste a favore di azioni più comuni. Utilizza Punti di interruzione per aggiungere un nuovo pulsante toccabile di almeno 48 dp quando c'è spazio.

Elenchi

Utilizza i layout a elenco per organizzare più elementi in un formato chiaro e scansionabile. Questa opzione è ideale per titoli di notizie, liste di cose da fare o messaggi. Organizzare i contenuti in un elenco strutturato e scansionabile. Scegli tra presentazione in contenitori o senza contenitori in base alle tue esigenze di 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 delle azioni

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

Immagine al vivo

Ideale per mostrare immagini immersive a pagina intera su Android 17 e versioni successive, questo layout utilizza lo scorrimento rapido per garantire che ogni elemento secondario 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 griglie solo con 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 aggiuntivi.

Esempi di codice

La tabella seguente mappa ogni layout canonico alla relativa implementazione di Jetpack Glance nel repository GitHub di Android Platform Samples.

Layout canonico File di riferimento Consulenza
Layout dell'elenco delle azioni
  • Gestisci le azioni degli elementi di elenco con i callback delle azioni di Glance e assicurati che gli aggiornamenti dello stato siano corretti.
Layout dell'elenco di controllo
  • Implementa l'attivazione/disattivazione dello stato della casella di controllo utilizzando parametri di azione o callback per aggiornare gli elementi della raccolta.
  • Utilizza i callback delle azioni Glance, ad esempio `actionRunCallback`, `ActionCallback(actionParametersOf(…))`, o `actionStartActivity(…)`, per i parametri `onClick` del widget per gestire gli eventi di clic come il tocco di una casella di controllo.
Layout espressivo della barra degli strumenti
  • 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 a tinta unita anziché `ColorProvider`.
Layout griglia immagini
  • Utilizza colori pieni (`GlanceModifier.background`) o risorse disegnabili locali per gli elementi immagine, a meno che non sia configurata o richiesta una libreria di caricamento delle immagini.
Layout elenco di testo con 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 troncamento del testo quando combini le immagini in miniatura con il testo principale/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 la scalabilità della tipografia.
Layout della barra 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 a tinta unita anziché ColorProvider.
Layout immagine a pagina intera / Scorrimento rapido
  • Imposta `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` su LazyColumn per lo scorrimento rapido.
  • Se implementi lo scorrimento rapido, sono richiesti Glance 1.3.0-alpha02 o versioni successive, SDK di compilazione 37 (Baklava) o versioni successive e Android Gradle Plugin (AGP) 9.1.0 o versioni successive.
  • Imposta `override val sizeMode: SizeMode = SizeMode.Exact` nella classe del fornitore di widget.
Layout standard della barra degli strumenti
  • Consulta la sezione Risoluzione dei problemi per evitare errori di importazione di `ColorProvider`: utilizza `androidx.glance.color.ColorProvider(dayColor, nightColor)`.
  • Utilizza `GlanceModifier.background(Color)` direttamente per i colori di sfondo a tinta unita anziché `ColorProvider`.
Layout con testo e immagine
  • Segui le regole di dimensionamento del layout adattabile per disporre testo e immagini uno accanto all'altro o impilati in base alle dimensioni disponibili del widget.