Inizia a utilizzare i riquadri

Riquadri per la versione di Wear OS 2.5 3

---

Per iniziare a fornire riquadri dalla tua app, includi le seguenti dipendenze nel file build.gradle dell'app.

Alla moda

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.6.2"

    // Use to utilize standard components and layouts in your tiles
    implementation "androidx.wear.protolayout:protolayout:1.4.2"

    // Use to utilize components and layouts with Material Design in your tiles
    implementation "androidx.wear.protolayout:protolayout-material:1.4.2"

    // Use to include dynamic expressions in your tiles
    implementation "androidx.wear.protolayout:protolayout-expression:1.4.2"

    // Use to preview wear tiles in your own app
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"

    // Use to fetch tiles from a tile provider in your tests
    testImplementation "androidx.wear.tiles:tiles-testing:1.6.2"
}

Kotlin

dependencies {
    // Use to implement support for wear tiles
    implementation("androidx.wear.tiles:tiles:1.6.2")

    // Use to utilize standard components and layouts in your tiles
    implementation("androidx.wear.protolayout:protolayout:1.4.2")

    // Use to utilize components and layouts with Material Design in your tiles
    implementation("androidx.wear.protolayout:protolayout-material:1.4.2")

    // Use to include dynamic expressions in your tiles
    implementation("androidx.wear.protolayout:protolayout-expression:1.4.2")

    // Use to preview wear tiles in your own app
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")

    // Use to fetch tiles from a tile provider in your tests
    testImplementation("androidx.wear.tiles:tiles-testing:1.6.2")
}

Importante: quando crei i riquadri Material 3, estendi sempre Material3TileService anziché la classe base TileService o SuspendingTileService di Horologist. Material3TileService fornisce un'API prescrittiva incentrata su Kotlin con supporto integrato delle coroutine, applicazione automatica dei temi MaterialScope e gestione delle risorse con una singola chiamata.

Concetti fondamentali

I riquadri non vengono creati nello stesso modo delle app per Android e utilizzano concetti diversi:

• Modelli di layout: definiscono la disposizione generale degli elementi visivi sul display. Questo viene fatto dalla funzione primaryLayout().
• Elementi di layout: rappresentano un singolo elemento grafico, ad esempio un pulsante o una scheda, oppure più elementi di questo tipo raggruppati utilizzando una colonna, un buttonGroup o un elemento simile. Questi sono incorporati in un modello di layout.

• Risorse: gli oggetti ResourceBuilders.Resources sono costituiti da una mappa di coppie chiave-valore delle risorse Android (immagini) necessarie per eseguire il rendering di un layout e da una versione.
• Timeline: un oggetto TimelineBuilders.Timeline è un elenco di una o più istanze di un oggetto layout. Puoi fornire vari meccanismi ed espressioni per indicare quando il renderer deve passare da un oggetto di layout a un altro, ad esempio per interrompere la visualizzazione di un layout in un momento specifico.
• Stato: una struttura di dati di tipo StateBuilders.State che viene passata tra il riquadro e l'app per consentire ai due componenti di comunicare tra loro. Ad esempio, se viene toccato un pulsante sul riquadro, lo stato contiene l'ID del pulsante. Puoi anche scambiare i tipi di dati utilizzando una mappa.
• Riquadro: un oggetto TileBuilders.Tile che rappresenta un riquadro, costituito da una cronologia, un ID versione delle risorse, un intervallo di aggiornamento e uno stato.
• Protolayout: questo termine appare nel nome di varie classi relative ai riquadri e si riferisce alla libreria Wear OS Protolayout, una libreria grafica utilizzata in varie piattaforme Wear OS.

Crea un riquadro

Utilizza Material3TileService (consigliato)

Quando crei i riquadri di Material 3 (androidx.wear.tiles:tiles:1.6.0 e versioni successive), estendi sempre Material3TileService anziché la classe TileService di livello inferiore. Material3TileService fornisce un'architettura predefinita, incentrata su Kotlin, che semplifica lo sviluppo dei riquadri:

• Coroutine Kotlin integrate: implementa una singola funzione di sospensione MaterialScope.tileResponse(requestParams: TileRequest): Tile anziché utilizzare ListenableFuture ed eseguire l'override di onTileRequest().
• Preconfigurato MaterialScope: tileResponse() viene eseguito con MaterialScope come ricevitore (configurato tramite parametri del costruttore come allowDynamicTheme e defaultColorScheme), quindi non è necessario aggregare il layout in una chiamata materialScope() ridondante.
• Registrazione delle risorse con una singola chiamata: include ProtoLayoutScope per registrare automaticamente le risorse immagine incorporate e restituire sia il layout del riquadro sia le risorse in una singola chiamata del binder di sistema. Poiché Material3TileService gestisce le risorse automaticamente (final onTileResourcesRequest()), non eseguire l'override di onTileResourcesRequest().

class MyTileService : Material3TileService() {

    override suspend fun MaterialScope.tileResponse(requestParams: TileRequest): Tile =
        tile(
            timeline =
            Timeline.fromLayoutElement(
                primaryLayout(
                    mainSlot = {
                        text("Hello, World!".layoutString, typography = BODY_LARGE)
                    }
                )
            )
        )
}
Tile.kt

Architettura TileService sottostante

Material3TileService si basa sulla classe base TileService, che gli altri esempi di questa guida utilizzano per illustrare i concetti di basso livello.

Per fornire un riquadro dalla tua app, implementa un servizio di tipo TileService e registralo nel manifest. In questo modo, il sistema richiede i riquadri necessari durante le chiamate a onTileRequest() e le risorse durante le chiamate a onTileResourcesRequest().

class MyTileService : TileService() {

    override fun onTileRequest(requestParams: RequestBuilders.TileRequest) =
        Futures.immediateFuture(
            Tile.Builder()
                .setResourcesVersion(RESOURCES_VERSION)
                .setTileTimeline(
                    Timeline.fromLayoutElement(
                        materialScope(this, requestParams.deviceConfiguration) {
                            primaryLayout(
                                mainSlot = {
                                    text("Hello, World!".layoutString, typography = BODY_LARGE)
                                }
                            )
                        }
                    )
                )
                .build()
        )

    override fun onTileResourcesRequest(requestParams: ResourcesRequest) =
        Futures.immediateFuture(Resources.Builder().setVersion(RESOURCES_VERSION).build())
}
Tile.kt

Importante: TileService è un servizio associato. Se esegui l'override di uno dei metodi del ciclo di vita del servizio associato, fai attenzione a evitare interazioni indesiderate con i metodi del ciclo di vita specifici di TileService, che vengono chiamati in un thread asincrono separato.

Successivamente, aggiungi un servizio all'interno del tag <application> del file AndroidManifest.xml.

<service
    android:name=".snippets.m3.tile.MyTileService"
    android:label="@string/tile_label"
    android:description="@string/tile_description"
    android:icon="@mipmap/ic_launcher"
    android:exported="true"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">
    <intent-filter>
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

L'autorizzazione e il filtro per intent registrano questo servizio come fornitore di riquadri.

L'icona, l'etichetta, la descrizione e la risorsa di anteprima vengono mostrate all'utente quando configura i riquadri sullo smartphone o sullo smartwatch. Tieni presente che la risorsa di anteprima supporta tutti i qualificatori delle risorse standard di Android, pertanto è possibile variare l'anteprima in base a fattori quali le dimensioni dello schermo e la lingua del dispositivo. Consulta l'elenco di controllo per l'anteprima per ulteriori consigli.

Esegui il deployment dell'app e aggiungi il riquadro al carosello dei riquadri (esiste anche un modo più semplice per gli sviluppatori di visualizzare l'anteprima di un riquadro, ma per ora fallo manualmente).

Figura 1. Riquadro "Hello World".

Per un esempio completo, consulta l'esempio di codice su GitHub o il codelab.

Crea la UI per i riquadri

Gli elementi UI espressivi di Material 3 vengono creati utilizzando un approccio strutturato basato sul pattern di creazione con sicurezza dei tipi di Kotlin.

Nota: questa guida utilizza l'abbreviazione "M3" per fare riferimento ai termini intercambiabili "Material 3", "Material Design 3" e "Material You". L'abbreviazione "M2.5" viene utilizzata per fare riferimento ai termini intercambiabili "Material 2.5" e "Material Design 2.5".

Layout

Per indicazioni sui principi di progettazione alla base della creazione di layout dei riquadri efficaci e adattabili, consulta Layout comuni per i riquadri.

Per creare il layout:

1. Avvia un ambito di Material Design: chiama la funzione materialScope(), fornendo i valori context e deviceConfiguration richiesti. Puoi includere parametri facoltativi, come allowDynamicTheme e defaultColorScheme. allowDynamicTheme è true per impostazione predefinita e defaultColorScheme rappresenta il ColorScheme utilizzato quando i colori dinamici non sono disponibili, ad esempio quando l'utente ha disattivato la funzionalità, quando non è supportata dal dispositivo o quando allowDynamicTheme è false). Quando utilizzi le API ImageResource come backgroundImage() in un TileService personalizzato, chiama materialScopeWithResources().

2. Crea la UI nell'ambito: tutti i componenti della UI per un determinato layout di Tile devono essere definiti all'interno della funzione lambda di una singola chiamata materialScope() di primo livello. Queste funzioni dei componenti, come primaryLayout() e textEdgeButton(), sono funzioni di estensione su MaterialScope e sono disponibili solo se chiamate in questo ambito del ricevitore.

   materialScope(
       context = context,
       deviceConfiguration =
       requestParams.deviceConfiguration, // requestParams is passed to onTileRequest
       defaultColorScheme = myFallbackColorScheme
   ) {
       // inside the MaterialScope, you can call functions like primaryLayout()
       primaryLayout(
           titleSlot = { text(text = "Title".layoutString) },
           mainSlot = { text(text = "Main Content".layoutString) },
           bottomSlot = {
               textEdgeButton(
                   labelContent = { text("Action".layoutString) },
                   onClick = clickable()
               )
           }
       )
   }
   GetStarted.kt

Slot

In M3, il layout dei riquadri utilizza un approccio ispirato a Compose che utilizza tre slot distinti. Dall'alto verso il basso, sono:

1. titleSlot, in genere per un titolo o un'intestazione principale.
2. mainSlot, per i contenuti principali.
3. bottomSlot, spesso utilizzato per azioni o informazioni supplementari. Qui viene visualizzato anche un pulsante perimetrale.

Figura 2. titleSlot, mainSlot e bottomSlot.

I contenuti di ogni slot sono i seguenti:

• titleSlot (facoltativo): in genere alcune parole generate da text().
• mainSlot (obbligatorio): componenti organizzati in strutture come righe, colonne e gruppi di pulsanti. Questi componenti possono anche essere incorporati in modo ricorsivo l'uno nell'altro; ad esempio, una colonna può contenere righe.
• bottomSlot (facoltativo): in genere contiene un pulsante adiacente al bordo o un'etichetta di testo.

Poiché non è possibile scorrere i riquadri, non esistono componenti per l'impaginazione, lo scorrimento o la gestione di elenchi lunghi di contenuti. Assicurati che i contenuti rimangano visibili quando le dimensioni del carattere aumentano o il testo si allunga a causa della traduzione.

Componenti UI

La libreria protolayout-material3 fornisce un numero elevato di componenti progettati in base alle specifiche di Material 3 Expressive e ai suggerimenti per l'interfaccia utente.

Pulsanti

I pulsanti sono principalmente orientati all'azione. Servono ad attivare azioni specifiche. Il contenuto di ogni pulsante, ad esempio un'icona o un breve testo, identifica l'azione.

• textButton(): pulsante con un singolo slot per contenuti di testo (brevi)
• iconButton(): pulsante con un singolo slot per rappresentare un'icona
• avatarButton(): pulsante avatar a forma di pillola che offre fino a tre slot per i contenuti che rappresentano l'etichetta e l'etichetta secondaria impilate verticalmente e un'immagine (avatar) accanto
• imageButton(): pulsante immagine cliccabile che non offre slot aggiuntivi, ma solo l'immagine (ad esempio backgroundImage come sfondo)
• compactButton(): pulsante compatto che offre fino a due slot per ospitare contenuti impilati orizzontalmente che rappresentano un'icona e il testo accanto
• button(): pulsante a forma di pillola che offre fino a tre slot per i contenuti che rappresentano l'etichetta e l'etichetta secondaria impilate verticalmente e un'icona accanto

Pulsanti laterali

Un pulsante laterale è un pulsante specializzato a larghezza intera ancorato alla parte inferiore dello schermo rotondo di uno smartwatch, che rappresenta l'azione più importante da intraprendere dalla schermata del riquadro corrente.

• iconEdgeButton(): pulsante laterale che offre un singolo slot per un'icona o contenuti piccoli e rotondi simili
• textEdgeButton(): pulsante laterale che offre un singolo slot per inserire un testo o contenuti simili lunghi e ampi

Schede

Le schede sono principalmente orientate alle informazioni. Mostrano raccolte di dati correlati e strutturati. Sebbene sia possibile creare schede interattive, di solito mostrano un riepilogo delle informazioni, che l'utente può toccare per visualizzare ulteriori dettagli o eseguire un'azione correlata.

• titleCard(): intertitolo che offre da uno a tre slot, solitamente basati su testo
• appCard(): scheda dell'app che offre fino a cinque slot, solitamente basati su testo
• textDataCard(): scheda dati che offre fino a tre slot impilati verticalmente, solitamente basati su testo o numeri
• iconDataCard(): scheda dati che offre fino a tre slot impilati verticalmente, in genere basati su testo o numeri, con un'icona
• graphicDataCard(): scheda di dati grafici che offre uno slot per i dati grafici, ad esempio l'indicatore di avanzamento, e fino a due slot impilati verticalmente, solitamente per le descrizioni di testo

Indicatori di avanzamento

• circularProgressIndicator(): indica l'avanzamento verso un obiettivo utilizzando un elemento radiale
• segmentedCircularProgressIndicator(): indica l'avanzamento verso un obiettivo utilizzando un elemento radiale con fasi distinte

Raggruppa gli elementi del layout

• buttonGroup(): layout dei componenti che posiziona i relativi elementi secondari in una sequenza orizzontale
• primaryLayout(): layout a schermo intero che rappresenta uno stile di layout M3 suggerito, adattabile e che si occupa del posizionamento degli elementi, insieme ai margini e al padding consigliati applicati

Applica un tema

In Material 3 Expressive, il sistema di colori è definito da 29 ruoli di colore standard, organizzati in sei gruppi: primario, secondario, terziario, errore, superficie e contorno.

Figura 3. Il sistema di colori Material 3 Expressive.

Un ColorScheme mappa ciascuno di questi 29 ruoli a un colore corrispondente e, poiché fa parte di MaterialScope e i componenti devono essere creati al suo interno, questi ultimi assumono automaticamente i colori dello schema. Questo approccio consente a tutti gli elementi UI di rispettare automaticamente gli standard di Material Design.

Per consentire agli utenti di scegliere tra una combinazione di colori definita da te, ad esempio una che riflette i colori del tuo brand, e una fornita dal sistema, derivata dal quadrante corrente dell'utente o scelta dall'utente, inizializza MaterialScope come segue:

val myColorScheme =
    ColorScheme(
        primary = Color.rgb(0, 0, 255).argb, // Blue
        onPrimary = Color.rgb(255, 255, 255).argb, // White
        // 27 more
    )

materialScope(
    context = context,
    deviceConfiguration = requestParams.deviceConfiguration,
    defaultColorScheme = myColorScheme
) {
    // If the user selects "no theme" in settings, myColorScheme is used.
    // Otherwise, the system-provided theme is used.
}
GetStarted.kt

Se scegli questa opzione, fornisci un'icona della scheda monocromatica in modo che possa essere colorata correttamente per una visibilità ottimale con qualsiasi tema.

Per forzare la visualizzazione dei riquadri nella combinazione di colori che fornisci, disattiva il supporto per i temi dinamici impostando allowDynamicTheme su false:

materialScope(
    context = context,
    deviceConfiguration = requestParams.deviceConfiguration,
    allowDynamicTheme = false,
    defaultColorScheme = myColorScheme
) {
    // myColorScheme is *always* used.
}
GetStarted.kt

Colore

Ogni singolo componente utilizza un sottoinsieme dei 29 ruoli dei colori definiti da uno ColorScheme. Ad esempio, i pulsanti utilizzano fino a quattro colori, che per impostazione predefinita vengono presi dal gruppo "principale" della ColorScheme attiva:

Token del componente ButtonColors	Ruolo ColorScheme
containerColor	principale
iconColor	onPrimary
labelColor	onPrimary
secondaryLabelColor	onPrimary (opacità 0,8)

Per indicazioni dettagliate sull'applicazione del colore ai design di Wear OS, consulta la guida alla progettazione dei colori.

Potresti dover deviare dai token di colore predefiniti per elementi UI specifici. Ad esempio, potresti voler utilizzare per un textEdgeButton i colori del gruppo "secondario" o "terziario", anziché "principale", per farlo risaltare e dare un contrasto migliore.

Puoi personalizzare i colori dei componenti in diversi modi:

1. Utilizza una funzione helper per i colori predefiniti. Utilizza funzioni helper come filledTonalButtonColors() per applicare gli stili dei pulsanti standard per Material 3 Expressive. Queste funzioni creano istanze ButtonColors preconfigurate che mappano stili comuni come pieno, tonale o con contorno ai ruoli appropriati della ColorScheme attiva all'interno di MaterialScope. In questo modo, puoi applicare stili coerenti senza definire manualmente ogni colore per i tipi di pulsanti comuni.

   textEdgeButton(
       colors = filledButtonColors(), // default
       /* OR colors = filledTonalButtonColors() */
       /* OR colors = filledVariantButtonColors() */
       // ... other parameters
   )
   GetStarted.kt

   Per le schede, utilizza la famiglia di funzioni filledCardColors() equivalente.

   Puoi anche modificare l'oggetto ButtonColors restituito dalle funzioni helper utilizzando il metodo copy() se devi modificare solo uno o due token:

   textEdgeButton(
       colors =
       filledButtonColors()
           .copy(
               containerColor = colorScheme.tertiary,
               labelColor = colorScheme.onTertiary
           ),
       // ... other parameters
   )
   GetStarted.kt

2. Fornisci esplicitamente i ruoli dei colori sostitutivi. Crea il tuo oggetto ButtonColors e passalo al componente. Per le schede, utilizza l'oggetto CardColors equivalente.

   textEdgeButton(
       colors =
       ButtonColors(
           // the materialScope makes colorScheme available
           containerColor = colorScheme.secondary,
           iconColor = colorScheme.secondaryDim,
           labelColor = colorScheme.onSecondary,
           secondaryLabelColor = colorScheme.onSecondary
       ),
       // ... other parameters
   )
   GetStarted.kt

3. Specifica colori fissi (da utilizzare con cautela). Sebbene in genere sia consigliabile specificare i colori in base al loro ruolo semantico (ad es. colorScheme.primary), puoi anche fornire valori di colore diretti. Questo approccio deve essere utilizzato con parsimonia, in quanto può causare incoerenze con il tema generale, soprattutto se il tema cambia in modo dinamico.

   textEdgeButton(
       colors = filledButtonColors().copy(
           containerColor = android.graphics.Color.RED.argb, // Using named colors
           labelColor = 0xFFFFFF00.toInt().argb // Using a hex code for yellow
       ),
       // ... other parameters
   )
   GetStarted.kt

Tipografia

Per ulteriori informazioni sull'utilizzo efficace della tipografia nei tuoi design, consulta la guida alla progettazione tipografica.

Per creare coerenza visiva sulla piattaforma Wear OS e ottimizzare le prestazioni, tutto il testo dei riquadri viene visualizzato utilizzando un carattere fornito dal sistema. In altre parole, i riquadri non supportano i caratteri tipografici personalizzati. Su Wear OS 6 e versioni successive, si tratta di un carattere specifico dell'OEM. Nella maggior parte dei casi si tratta di un carattere variabile, che offre un'esperienza più espressiva e un controllo più granulare.

Per creare uno stile di testo, in genere utilizzi il metodo text() combinato con costanti tipografiche. Questo componente ti consente di utilizzare i ruoli di tipografia predefiniti in Material 3 Expressive, il che aiuta la tua scheda ad aderire alle best practice tipografiche stabilite per la leggibilità e la gerarchia. La libreria offre un insieme di 18 costanti di tipografia semantica, come BODY_MEDIUM. Queste costanti influiscono anche sugli assi dei caratteri diversi dalle dimensioni.

text(
    text = "Hello, World!".layoutString,
    typography = BODY_MEDIUM,
)
GetStarted.kt

Per un maggiore controllo, puoi fornire impostazioni aggiuntive. Su Wear OS 6 e versioni successive, è probabile che venga utilizzato un carattere variabile, che puoi modificare lungo gli assi corsivo, spessore, larghezza e rotondità. Puoi controllare questi assi utilizzando il parametro settings:

text(
    text = "Hello, World".layoutString,
    italic = true,

    // Use elements defined in androidx.wear.protolayout.LayoutElementBuilders.FontSetting
    settings =
    listOf(
        weight(500),
        width(100F),
        roundness(100)
    ),
)
GetStarted.kt

Infine, se devi controllare le dimensioni o la spaziatura tra le lettere (non consigliato), utilizza basicText() anziché text() e crea un valore per la proprietà fontStyle utilizzando fontStyle()).

Forma e margini

Puoi modificare il raggio degli angoli di quasi tutti i componenti utilizzando la relativa proprietàshape. I valori provengono dalla proprietà MaterialScope shapes:

textButton(
    height = expand(),
    width = expand(),
    shape = shapes.medium, // OR another value like shapes.full
    colors = filledVariantButtonColors(),
    labelContent = { text("Hello, World!".layoutString) },
)
GetStarted.kt

Dopo aver modificato la forma di un componente, se ritieni che lasci troppo o troppo poco spazio intorno al bordo del display, regola i margini utilizzando il parametro margin di primaryLayout():

primaryLayout(
    mainSlot = {
        textButton(
            shape = shapes.small,
            /* ... */
        )
    },
    // margin constants defined in androidx.wear.protolayout.material3.PrimaryLayoutMargins
    margins = MAX_PRIMARY_LAYOUT_MARGIN,
)
GetStarted.kt

Nota: i riquadri non supportano la trasformazione della forma tra le forme dei pulsanti disponibili per le app che utilizzano Compose per Wear OS. Ad esempio, non esiste un equivalente di IconToggleButtonShapes per i riquadri.

Archi

Sono supportati i seguenti elementi secondari del contenitore Arc:

• ArcLine: esegue il rendering di una linea curva attorno all'arco.
• ArcText: esegue il rendering del testo curvo nell'arco.
• ArcAdapter: esegue il rendering di un elemento di layout di base nell'arco, disegnato in modo tangente all'arco.

Nota: mentre un ArcText disegna un testo curvo attorno all'arco, l'utilizzo di un Text in un ArcAdapter disegna un testo lineare tangente all'arco.

Per saperne di più, consulta la documentazione di riferimento per ciascuno dei tipi di elementi.

Modificatori

A ogni elemento di layout disponibile è possibile applicare modificatori facoltativi. Utilizza questi modificatori per i seguenti scopi:

• Modificare l'aspetto visivo del layout. Ad esempio, aggiungi uno sfondo, un bordo o un padding all'elemento di layout.
• Aggiungi i metadati relativi al layout. Ad esempio, aggiungi un modificatore di semantica al tuo elemento di layout per l'utilizzo con gli screen reader.
• Aggiungi funzionalità. Ad esempio, aggiungi un modificatore cliccabile all'elemento di layout per rendere interattivo il riquadro. Per saperne di più, vedi Interagisci con i riquadri.

Ad esempio, possiamo personalizzare l'aspetto e i metadati predefiniti di un Image, come mostrato nel seguente esempio di codice:

private fun myImage(): LayoutElement =
    Image.Builder()
        .setWidth(dp(24f))
        .setHeight(dp(24f))
        .setResourceId("image_id")
        .setModifiers(
            Modifiers.Builder()
                .setBackground(Background.Builder().setColor(argb(0xFFFF0000.toInt())).build())
                .setPadding(ModifiersBuilders.Padding.Builder().setStart(dp(12f)).build())
                .setSemantics(Semantics.Builder().setContentDescription("Image description").build())
                .build()
        )
        .build()
Tile.kt

Spannable

Un Spannable è un tipo speciale di contenitore che dispone gli elementi in modo simile al testo. Questo è utile quando vuoi applicare uno stile diverso a una sola sottostringa in un blocco di testo più grande, cosa che non è possibile con l'elemento Text.

Un container Spannable è pieno di elementi secondari Span. Non sono consentiti altri elementi secondari o istanze Spannable nidificate.

Esistono due tipi di elementi secondari Span:

• SpanText: esegue il rendering del testo con uno stile specifico.
• SpanImage: esegue il rendering di un'immagine in linea con il testo.

Ad esempio, puoi applicare il corsivo a "mondo" in un riquadro "Hello World" e inserire un'immagine tra le parole, come mostrato nell'esempio di codice seguente:

private fun mySpannable(): LayoutElement =
    LayoutElementBuilders.Spannable.Builder()
        .addSpan(SpanText.Builder().setText("Hello ").build())
        .addSpan(SpanImage.Builder().setWidth(dp(24f)).setHeight(dp(24f)).setResourceId("image_id").build())
        .addSpan(
            SpanText.Builder()
                .setText("world")
                .setFontStyle(FontStyle.Builder().setItalic(true).build())
                .build()
        )
        .build()
Tile.kt

Utilizza le risorse

Importante: quando utilizzi Material3TileService, le risorse vengono registrate automaticamente tramite il ProtoLayoutScope integrato quando passi un ImageResource (ad esempio imageResource(androidImageResource(R.drawable.icon))) direttamente ai componenti di Material 3 come icon() o backgroundImage(). Non eseguire l'override di onTileResourcesRequest() in Material3TileService.

Le schede non hanno accesso alle risorse della tua app. Ciò significa che non puoi passare un ID immagine Android a un elemento di layout Image e aspettarti che venga risolto. Esegui invece l'override del metodo onTileResourcesRequest() e fornisci manualmente le risorse.

Esistono due modi per fornire immagini all'interno del metodo onTileResourcesRequest():

• Fornisci una risorsa drawable utilizzando setAndroidResourceByResId().
• Fornisci un'immagine dinamica come ByteArray utilizzando setInlineResource().

override fun onTileResourcesRequest(
    requestParams: ResourcesRequest
) = Futures.immediateFuture(
    Resources.Builder()
        .setVersion("1")
        .addIdToImageMapping(
            "image_from_resource",
            ResourceBuilders.ImageResource.Builder()
                .setAndroidResourceByResId(
                    ResourceBuilders.AndroidImageResourceByResId.Builder()
                        .setResourceId(R.drawable.ic_walk)
                        .build()
                ).build()
        )
        .addIdToImageMapping(
            "image_inline",
            ResourceBuilders.ImageResource.Builder()
                .setInlineResource(
                    ResourceBuilders.InlineImageResource.Builder()
                        .setData(imageAsByteArray)
                        .setWidthPx(48)
                        .setHeightPx(48)
                        .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
                        .build()
                ).build()
        ).build()
)
Tile.kt

Elenco di controllo per l'immagine di anteprima della scheda

Il sistema visualizza l'immagine di anteprima del riquadro, a cui viene fatto riferimento nel manifest dell'app per Android, nell'editor del carosello di riquadri per l'aggiunta di un nuovo riquadro. Questo editor viene visualizzato sia sui dispositivi Wear OS sia nell'app complementare per smartwatch sugli smartphone.

Per aiutare gli utenti a sfruttare al meglio questa immagine di anteprima, verifica i seguenti dettagli relativi alla tua scheda:

• Riflette il design più recente. L'anteprima deve rappresentare con precisione il design più recente della scheda.
• Utilizza le dimensioni consigliate. Per offrire la migliore qualità di visualizzazione possibile e una buona esperienza utente, l'immagine di anteprima deve avere dimensioni di 400 x 400 px.
• Utilizza un tema cromatico statico. Utilizza il tema cromatico statico del riquadro, non quello dinamico.
• Include l'icona dell'app. Verifica che l'icona della tua app venga visualizzata nella parte superiore dell'immagine di anteprima.
• Mostra lo stato di caricamento/accesso. L'anteprima deve mostrare uno stato "caricato" o "con accesso eseguito" completamente funzionante, evitando contenuti vuoti o segnaposto.
• (Facoltativo) Sfrutta le regole di risoluzione delle risorse per la personalizzazione. Valuta la possibilità di utilizzare le regole di risoluzione delle risorse di Android per fornire anteprime che corrispondano alle dimensioni del display, alla lingua o alle impostazioni internazionali del dispositivo. Questa opzione è particolarmente utile se l'aspetto della scheda varia a seconda del dispositivo.