Eseguire la migrazione da Material 2.5 a Material 3 in Compose per Wear OS

Material 3 Expressive è la nuova evoluzione di Material Design. Include temi, componenti e funzionalità di personalizzazione aggiornati, come il colore dinamico.

Questa guida si concentra sulla migrazione dalla libreria Jetpack Wear Compose Material 2.5 (androidx.wear.compose) alla libreria Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) per le app.

Approcci

Per eseguire la migrazione del codice dell'app da M2.5 a M3, segui lo stesso approccio descritto nella guida alla migrazione di Compose Material per smartphone, in particolare:

• Non utilizzare sia M2.5 che M3 in una singola app a lungo termine
• Adotta un approccio graduale

Dipendenze

M3 ha un pacchetto e una versione diversi rispetto a M2.5:

implementation("androidx.wear.compose:compose-material:1.4.0")

implementation("androidx.wear.compose:compose-material3:1.6.0-alpha04")

Consulta le versioni più recenti di M3 nella pagina delle release di Wear Compose Material 3.

La libreria Wear Compose Foundation versione 1.6.0-alpha04 introduce alcuni nuovi componenti progettati per funzionare con i componenti di Material 3. Allo stesso modo, SwipeDismissableNavHost della libreria Wear Compose Navigation ha un'animazione aggiornata quando viene eseguito su Wear OS 6 (livello API 36) o versioni successive. Quando esegui l'aggiornamento alla versione 3 di Wear Compose Material, ti consigliamo di aggiornare anche le librerie Wear Compose Foundation e Navigation:

implementation("androidx.wear.compose:compose-foundation:1.6.0-alpha04")
implementation("androidx.wear.compose:compose-navigation:1.6.0-alpha04")

Tema

Sia in M2.5 che in M3, il componibile del tema si chiama MaterialTheme, ma i pacchetti di importazione e i parametri sono diversi. In M3, il parametro Colors è stato rinominato in ColorScheme ed è stato introdotto MotionScheme per implementare le transizioni.

import androidx.wear.compose.material.MaterialTheme

MaterialTheme(
        colors = AppColors,
        typography = AppTypography,
        shapes = AppShapes,
        content = content
)

import androidx.wear.compose.material3.MaterialTheme

MaterialTheme(
        colorScheme = AppColorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        motionScheme = AppMotionScheme,
        content = content
)

Colore

Il sistema di colori in M3 è notevolmente diverso rispetto a M2.5. Il numero di parametri di colore è aumentato, hanno nomi diversi e vengono mappati ai componenti di M3 in modo differente. In Compose, questo vale per la classe Colors di M2.5, la classe ColorScheme di M3 e le funzioni correlate:

import androidx.wear.compose.material.Colors

val appColorScheme: Colors = Colors(
   // M2.5 Color parameters
)

import androidx.wear.compose.material3.ColorScheme

val appColorScheme: ColorScheme = ColorScheme(
   // M3 ColorScheme parameters
)

La seguente tabella descrive le principali differenze tra M2.5 e M3:

Temi cromatici dinamici

Una nuova funzionalità di M3 sono i temi cromatici dinamici. Se gli utenti cambiano i colori del quadrante, i colori della UI cambiano di conseguenza.

Utilizza la funzione dynamicColorScheme per implementare la combinazione di colori dinamica e fornisci defaultColorScheme come funzione di riserva nel caso in cui la combinazione di colori dinamica non sia disponibile.

@Composable
fun myApp() {
  val myColorScheme = myBrandColors()
  val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
  MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {...}
}

Tipografia

Il sistema tipografico in M3 è diverso rispetto a M2 e include le seguenti funzionalità:

• Nove nuovi stili di testo
• Caratteri flessibili, che consentono di personalizzare le scale tipografiche in base a diversi spessori, larghezze e rotondità

• AnimatedText, che utilizza caratteri flessibili

import androidx.wear.compose.material.Typography

val Typography = Typography(
   // M2.5 TextStyle parameters
)

import androidx.wear.compose.material3.Typography

val Typography = Typography(
   // M3 TextStyle parameters
)

Caratteri flessibili

I caratteri flessibili consentono ai designer di specificare la larghezza e lo spessore del carattere per dimensioni specifiche.

Stili di testo

In M3 sono disponibili i seguenti stili di testo, che vengono utilizzati per impostazione predefinita dai vari componenti di M3.

Forma

Il sistema di forme in M3 è diverso rispetto a M2. Il numero di parametri di forma è aumentato, hanno un nome diverso e vengono mappati ai componenti di M3 in modo differente. Sono disponibili le seguenti dimensioni per le forme:

• XS
• S
• Media
• L
• XL

In Compose, questo vale per la classe Shapes di M2 e per la classe Shapes di M3:

import androidx.wear.compose.material.Shapes

val Shapes = Shapes(
   // M2.5 Shapes parameters
)

import androidx.wear.compose.material3.Shapes

val Shapes = Shapes(
   // M3 Shapes parameters
)

Utilizza la mappatura dei parametri Shapes da Migrazione da Material 2 a Material 3 in Compose come punto di partenza.

Morphing di forme

M3 introduce il morphing di forme: ora le forme si trasformano in risposta alle interazioni.

Il comportamento di morphing di forme è disponibile come variante di diversi pulsanti rotondi. Consulta il seguente elenco di pulsanti che supportano il morphing di forme:

Componenti e layout

La maggior parte dei componenti e dei layout di M2.5 è disponibile in M3. Tuttavia, alcuni componenti e layout di M3 non esistono in M2.5. Inoltre, alcuni componenti di M3 hanno più varianti rispetto ai loro equivalenti in M2.5.

Sebbene alcuni componenti richiedano considerazioni speciali, le seguenti mappature delle funzioni sono consigliate come punto di partenza:

Ecco un elenco completo di tutti i componenti di Material 3:

Infine, un elenco di alcuni componenti pertinenti della libreria Wear Compose Foundation, introdotta per la prima volta nella versione 1.6.0-alpha04:

Pulsanti

I pulsanti in M3 sono diversi da quelli in M2.5. Il componente Chip di M2.5 è stato sostituito da Button. L'implementazione di Button fornisce valori predefiniti per Text maxLines e textAlign. Questi valori predefiniti possono essere sostituiti nell'elemento Text.

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

import androidx.wear.compose.material3.Button

//M3 Buttons
Button(...)
CompactButton(...)
IconButton(...)
TextButton(...)

M3 include anche nuove varianti di pulsanti. Dai un'occhiata alla panoramica del riferimento API di Compose Material 3.

M3 introduce un nuovo pulsante: EdgeButton. EdgeButton è disponibile in 4 dimensioni diverse: XS, S, M e L. L'implementazione di EdgeButton fornisce un valore predefinito per maxLines a seconda delle dimensioni, che può essere personalizzato.

Se utilizzi TransformingLazyColumn e ScalingLazyColumn, passa EdgeButton in ScreenScaffold in modo che si trasformi, cambiando forma con lo scorrimento. Vedi il seguente codice per verificare come utilizzare EdgeButton con ScreenScaffold e TransformingLazyColumn.

import androidx.wear.compose.material3.EdgeButton
import androidx.wear.compose.material3.ScreenScaffold

ScreenScaffold(
   scrollState = state,
   contentPadding = contentPadding,
   edgeButton = {
      EdgeButton(...)
   }
){ contentPadding ->
   TransformingLazyColumn(state = state, contentPadding = contentPadding,){
   // additional code here
   }
}

Scaffold

Lo scaffold in M3 è diverso rispetto a M2.5. In M3, AppScaffold e il nuovo componibile ScreenScaffold hanno sostituito Scaffold. AppScaffold e ScreenScaffold definiscono la struttura di una schermata e coordinano le transizioni dei componenti ScrollIndicator e TimeText.

AppScaffold consente agli elementi statici della schermata, come TimeText, di rimanere visibili durante le transizioni in-app, ad esempio lo scorrimento per chiudere. ​​Fornisce uno spazio per i contenuti principali dell'applicazione, che di solito vengono forniti da un componente di navigazione come SwipeDismissableNavHost.

Dichiari AppScaffold per un'attività e utilizzi ScreenScaffold per ogni schermata.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

    AppScaffold {
        val navController = rememberSwipeDismissableNavController()
        SwipeDismissableNavHost(
            navController = navController,
            startDestination = "message_list"
        ) {
            composable("message_list") {
                MessageList(onMessageClick = { id ->
                    navController.navigate("message_detail/$id")
                })
            }
            composable("message_detail/{id}") {
                MessageDetail(id = it.arguments?.getString("id")!!)
            }
        }
    }
}

// Implementation of one of the screens in the navigation
@Composable
fun MessageDetail(id: String) {
    // .. Screen level content goes here
    val scrollState = rememberTransformingLazyColumnState()

    val padding = rememberResponsiveColumnPadding(
        first = ColumnItemType.BodyText
    )

    ScreenScaffold(
        scrollState = scrollState,
        contentPadding = padding
    ) { scaffoldPaddingValues ->
        // Screen content goes here
        // ...
Navigation.kt

Se utilizzi un HorizontalPager con HorizontalPagerIndicator, puoi eseguire la migrazione a HorizontalPagerScaffold. HorizontalPagerScaffold si trova all'interno di un AppScaffold. AppScaffold e HorizontalPagerScaffold definiscono la struttura di un pager e coordinano le transizioni dei componenti HorizontalPageIndicator e TimeText.

HorizontalPagerScaffold mostra HorizontalPageIndicator al centro/fine della schermata per impostazione predefinita e coordina la visualizzazione e l'occultamento di TimeText e HorizontalPageIndicator a seconda che venga eseguito il paging di Pager, il che è determinato da PagerState.

È disponibile anche un nuovo componente AnimatedPage, che anima una pagina all'interno di un Pager con un effetto di ridimensionamento e velatura in base alla sua posizione.

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })
    val columnState = rememberTransformingLazyColumnState()
    val contentPadding = rememberResponsiveColumnPadding(
        first = ColumnItemType.ListHeader,
        last = ColumnItemType.BodyText,
    )
    HorizontalPagerScaffold(pagerState = pagerState) {
        HorizontalPager(
            state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold(
                    scrollState = columnState,
                    contentPadding = contentPadding
                ) { contentPadding ->
                    TransformingLazyColumn(
                        state = columnState,
                        contentPadding = contentPadding
                    ) {
                        item {
                            ListHeader(
                                modifier = Modifier.fillMaxWidth()
                            ) {
                                Text(text = "Pager sample")
                            }
                        }
                        item {
                            if (page == 0) {
                                Text(text = "Page #$page. Swipe right")
                            }
                            else{
                                Text(text = "Page #$page. Swipe left and right")
                            }
                        }
                    }
                }

            }
        }
    }
}
Pager.kt

Infine, M3 introduce VerticalPagerScaffold, che segue lo stesso pattern di HorizontalPagerScaffold:

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.VerticalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

AppScaffold {
   val pagerState = rememberPagerState(pageCount = { 10 })

   VerticalPagerScaffold(pagerState = pagerState) {
      VerticalPager(
         state = pagerState
      ) { page ->
             AnimatedPage(pageIndex = page, pagerState = pagerState){
                ScreenScaffold {
        …
   }
}

Segnaposto

Sono state apportate alcune modifiche all'API da M2.5 a M3. Placeholder.PlaceholderDefaults ora fornisce due modificatori:

• Modifier.placeholder, che viene disegnato al posto dei contenuti non ancora caricati
• Modifier.placeholderShimmer che fornisce un effetto luccichio di segnaposto eseguito in un ciclo di animazione durante l'attesa del caricamento dei dati.

Consulta la tabella seguente per ulteriori modifiche apportate al componente Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost fa parte di wear.compose.navigation. Quando questo componente viene utilizzato con M3, MaterialTheme di M3 aggiorna LocalSwipeToDismissBackgroundScrimColor e LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn fa parte di wear.compose.lazy.foundation e aggiunge il supporto per le animazioni di ridimensionamento e morphing degli elementi di elenco durante lo scorrimento, migliorando l'esperienza utente.

Analogamente a ScalingLazyColumn, fornisce rememberTransformingLazyColumnState() per creare TransformingLazyColumnState che viene ricordato in tutte le composizioni.

Per aggiungere animazioni di ridimensionamento e morphing, aggiungi quanto segue a ogni elemento di elenco:

• Modifier.transformedHeight, che ti consente di calcolare l'altezza trasformata degli elementi utilizzando TransformationSpec; puoi utilizzare rememberTransformationSpec(), a meno che tu non abbia bisogno di ulteriore personalizzazione.
• SurfaceTransformation

val columnState = rememberTransformingLazyColumnState()
val contentPadding = rememberResponsiveColumnPadding(
    first = ColumnItemType.ListHeader,
    last = ColumnItemType.Button,
)
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState,
    contentPadding = contentPadding
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                transformation = SurfaceTransformation(transformationSpec),
                onClick = { /* ... */ },
                icon = {
                    Icon(
                        imageVector = Icons.Default.Build,
                        contentDescription = "build",
                    )
                },
            ) {
                Text(
                    text = "Build",
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
        }
    }
}
List.kt

Link utili

Per scoprire di più sulla migrazione da M2.5 a M3 in Compose, consulta le seguenti risorse aggiuntive.

Campioni

• Esempi di Wear OS su GitHub
• Codelab Compose for Wear OS
• Esempio di Jetcaster

Riferimento API e codice sorgente

• Riferimento API Compose Material 3
• Esempi di Compose Material 3 nel codice sorgente

Progettazione

• Indicazioni per la progettazione