Eseguire la migrazione dalle tessere ai widget

Sebbene sia i riquadri sia i widget mostrino i contenuti sulla superficie di un sistema remoto, la loro creazione richiede approcci distinti. La migrazione del riquadro esistente a un widget comporta la transizione dalla generazione di layout rigidi a un'UI dinamica e dichiarativa, sbloccando nuove funzionalità e un modello di sviluppo semplificato.

Scegli la tua strategia di implementazione

Se stai eseguendo la migrazione di un'app che gestisce un riquadro legacy, devi decidere in che modo l'app fornisce contenuti al sistema. Mentre i nuovi widget devono utilizzare un singolo servizio widget, le app con riquadri esistenti devono scegliere se mantenere entrambi i servizi o consolidarli in un unico servizio widget.

Consigliato: doppio servizio (riquadro + widget)

Il mantenimento sia di un riquadro sia di un widget è il percorso consigliato per tutte le app che hanno un riquadro esistente. La fornitura di due servizi distinti offre la migliore esperienza utente possibile su diversi dispositivi.

Comportamento del sistema per la configurazione a doppio servizio:

Sistema operativo / funzionalità del dispositivo Esperienza risultante
Wear OS 3 Viene utilizzato il riquadro
Wear OS 4, 5, 6 Viene utilizzato il riquadro
Wear OS 7 (nessun supporto per l'altezza parziale, ad es. Pixel Watch) Viene utilizzato il riquadro
Wear OS 7 (supporto per l'altezza parziale, ad es. Galaxy Watch) Viene utilizzato il widget

Alternativa: singolo servizio (solo widget)

Un singolo servizio gestisce entrambi i protocolli. Sebbene questo approccio sia più rapido da implementare, si basa su una modalità di compatibilità per "adattare" il widget a un riquadro sui dispositivi che eseguono versioni precedenti di Wear OS.

Se scegli questo approccio:

  1. Specifica entrambi i filtri per intent: il servizio deve includere filtri per intent sia per androidx.wear.tiles.action.BIND_TILE_PROVIDER sia per androidx.glance.wear.action.BIND_WIDGET_PROVIDER. In questo modo, il widget viene visualizzato sulle superfici dei riquadri in Wear 4, 5, 6 e 7 (ove richiesto).
  2. Mantieni il nome del servizio esistente (per upgrade senza interruzioni): se stai sostituendo un riquadro attivo, mantenere lo stesso nome della classe di servizio garantisce che gli utenti che hanno il tuo riquadro nel carosello vedranno l'aggiornamento automatico al nuovo widget. Mentre Wear OS 7 utilizza l'attributo group nel codice XML di configurazione del widget per collegare logicamente componenti diversi, le versioni di Wear OS precedenti alla 7 si basano sul nome del servizio per identificarli come lo "stesso" componente. Se preferisci utilizzare un nuovo nome del servizio, l'app continuerà a funzionare perfettamente. Tuttavia, gli utenti sui dispositivi che eseguono Wear OS versione 6 o precedenti dovranno aggiungere manualmente di nuovo il widget al carosello.

Comportamento del sistema per la configurazione a servizio singolo:

Sistema operativo / funzionalità del dispositivo Esperienza risultante
Wear OS 3 Non supportato
Wear OS 4, 5, 6 Il widget viene visualizzato come un riquadro a schermo intero
Wear OS 7 (nessun supporto per l'altezza parziale) Il widget viene convertito in un riquadro
Wear OS 7 (supporto per l'altezza parziale) Viene utilizzato il widget

*Richiede il renderer 1.6 o versioni successive.

Suggerimenti per la traduzione dell'UI

Quando traduci l'UI da ProtoLayout (riquadri) a Remote Compose (widget), il modello mentale passa da builder di layout imperativi a un'architettura basata su Compose e guidata dallo stato in cui gli aggiornamenti dell'UI vengono gestiti tramite la ricomposizione. Tieni presente i seguenti principi:

  • Adotta l'UI dichiarativa: sostituisci i builder ProtoLayout imperativi (LayoutElementBuilders) con gli equivalenti Remote Compose dichiarativi, come RemoteText, RemoteColumn e RemoteBox.
  • Concentrati sui contenuti principali (mainSlot): i widget ad altezza parziale (ad es. i tipi di contenitore SMALL e LARGE) forniscono una superficie mirata e visibile a colpo d'occhio. Anziché eseguire la conversione uno a uno di un layout di riquadro a schermo intero denso, semplifica il design per enfatizzare le informazioni principali nell'area dei contenuti principali.
  • Riprogetta le azioni allineate ai bordi: nell'architettura dei riquadri, i componenti che si adattano allo schermo come EdgeButton erano ancorati a uno bottomSlot dedicato. Poiché i widget ad altezza parziale si integrano direttamente in una superficie a scorrimento verticale, questo paradigma bottomSlot fisso non esiste più. Poiché i pulsanti allineati ai bordi spesso fungevano da azioni principali molto visibili, la migrazione richiede una riprogettazione deliberata dell'UI anziché una sostituzione diretta dei componenti. Valuta strategie UX alternative per le azioni principali:
    • Azioni in linea: integra un RemoteButton in linea direttamente nel layout mainSlot.
    • Tocchi del contenitore: consolida l'interazione rendendo l'intero contenitore del widget toccabile utilizzando un PendingIntentAction.
    • Pivot dei contenuti: rivaluta l'attenzione del widget. Senza uno slot di azione dedicato, valuta la possibilità di mostrare dati più ricchi e visibili a colpo d'occhio e di fare affidamento su un singolo tocco per aprire l'applicazione completa anziché isolare azioni specifiche sulla superficie del widget.
  • Esegui la migrazione della gestione degli eventi (azioni vs. lambda): i riquadri si basano su interazioni (come LoadAction) che attivano callback di servizio completi per aggiornare l'UI. I widget Wear sono basati sul lato client. Le lambda Compose standard non possono essere eseguite da remoto. In alternativa, fornisci azioni dichiarative serializzabili (come ValueChange o PendingIntentAction). Combinale con lo stato dichiarativo (ad es. rememberMutableRemoteInt) per supportare gli aggiornamenti immediati dell'UI senza round trip dell'app.
  • Adatta dimensioni e tipi: quando esegui la migrazione delle dimensioni del layout, preferisci la risoluzione del layout differita utilizzando RemoteDp (ad es. 10.rdp) rispetto a Dp standard. In questo modo, il renderer di sistema calcola correttamente i valori dei pixel al momento della visualizzazione. Allo stesso modo, utilizza le funzioni di estensione Remote Compose (.rc per Color, .rs per String, .rdp per Dp) per convertire senza problemi i tipi Kotlin e Remote Compose standard.
  • Esamina il codice campione: per visualizzare esempi completi di come creare layout, applicare la tipografia semantica e gestire lo stato in Remote Compose, esplora il codice campione ufficiale disponibile nel repository degli esempi di Wear OS.