Material 3 Expressive è la nuova versione di Material Design. Include temi, componenti e funzionalità di personalizzazione aggiornati, come i colori dinamici.

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 nelle linee guida per la migrazione del telefono di Compose Material, in particolare:

• Non dovresti utilizzare sia M2.5 che M3 in un'unica app a lungo termine
• Adotta un approccio graduale

Dipendenze

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

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

implementation("androidx.wear.compose:compose-material3:1.5.0-beta01")

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

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

implementation("androidx.wear.compose:compose-foundation:1.5.0-beta01")
implementation("androidx.wear.compose:compose-navigation:1.5.0-beta01")

Applicazione tema

Sia in M2.5 che in M3, il composable del tema si chiama MaterialTheme, ma i pacchetti di importazione e i parametri sono diversi. In M3, il parametro Colors è stato rinominato in ColorScheme e MotionScheme è stato introdotto per l'implementazione delle 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 da quello di M2.5. Il numero di parametri di colore è aumentato, hanno nomi diversi e vengono mappati in modo diverso ai componenti M3. In Compose, si applica alla classe M2.5 Colors, alla classe M3 ColorScheme e alle 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 a colori dinamici

Una nuova funzionalità di M3 è la tematiche di colori dinamiche. Se gli utenti cambiano i colori del quadrante, i colori dell'interfaccia utente cambiano di conseguenza.

Utilizza la funzione dynamicColorScheme per implementare la combinazione di colori dinamica e fornisci un valore defaultColorScheme come opzione 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 di tipografia in M3 è diverso da quello di M2 e include le seguenti funzionalità:

• Nove nuovi stili di testo
• Caratteri flessibili, che consentono di personalizzare le scale dei caratteri per 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 il peso del tipo per dimensioni specifiche.

Stili di testo

In M3 sono disponibili i seguenti TextStyles. Questi vengono impiegati per impostazione predefinita da vari componenti di M3.

Forma

Il sistema di forme in M3 è diverso da quello in M2. Il numero di parametri della forma è aumentato, hanno nomi diversi e vengono mappati in modo diverso ai componenti M3. Sono disponibili le seguenti dimensioni delle forme:

• Molto piccolo
• Piccolo
• Media
• Grande
• Molto grande

In Compose, si applica alla classe Forme di M2 e alla classe Forme 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 delle forme descritta in Eseguire la migrazione da Material 2 a Material 3 in Compose come punto di partenza.

Morphing delle forme

M3 introduce la trasformazione delle forme: ora le forme si trasformano in risposta alle interazioni.

Il comportamento di morphing delle forme è disponibile come variante per una serie di pulsanti arrotondati, come indicato di seguito:

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 esistevano in M2.5. Inoltre, alcuni componenti M3 hanno più varianti rispetto ai loro equivalenti in M2.5.

Sebbene alcuni componenti richiedano considerazioni speciali, come punto di partenza sono consigliati i seguenti mappaggi delle funzioni:

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

Infine, un elenco di alcuni componenti pertinenti della libreria Wear Compose Foundation versione 1.5.0-beta01:

Pulsanti

I pulsanti in M3 sono diversi da quelli in M2.5. Il chip M2,5 è stato sostituito dal pulsante. 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. Consulta la panoramica dei riferimenti dell'API Compose Material 3.

M3 introduce un nuovo pulsante: EdgeButton. EdgeButton è disponibile in 4 diverse taglie: XS, S, M e L. L'implementazione di EdgeButton fornisce un valore predefinito per maxLines in base alle dimensioni che possono essere personalizzate.

Se utilizzi TransformingLazyColumn e ScalingLazyColumn, trasferisci EdgeButton in ScreenScaffold in modo che si trasformi, cambiando forma con lo scorrimento. Consulta il codice di seguito per scoprire 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

La struttura in M3 è diversa da quella in M2.5. In M3, AppScaffold e il nuovo composable 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 in genere vengono forniti da un componente di navigazione come SwipeDismissableNavHost

Dichiari un AppScaffold per Attività e utilizzi un ScreenScaffold per ogni schermata.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold

AppScaffold {
   // Define the navigation hierarchy within the AppScaffold,
   // such as using SwipeDismissableNavHost.
   SwipeDismissableNavHost(...) {
      composable("home") {
         HomeScreen()
      }
      //other screens
   }
}
fun HomeScreen() {
    val scrollState = rememberScrollState()
    ScreenScaffold(scrollState = scrollState) {
    //rest of the screen code
    }
}

Se utilizzi un HorizontalPager con HorizontalPagerIndicator, puoi eseguire la migrazione a HorizontalPagerScaffold. HorizontalPagerScaffold viene inserito in un AppScaffold. AppScaffold e HorizontalPagerScaffold definiscono la struttura di un pager e coordinano le transizioni dei componenti HorizontalPageIndicator e vTimeText.

Per impostazione predefinita, HorizontalPagerScaffold mostra il HorizontalPageIndicator al centro dello schermo e coordina la visualizzazione/nascondimento di TimeText e HorizontalPageIndicator a seconda che la pagina Pager sia paginata. Questo viene determinato dal PagerState.

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

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

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

    HorizontalPagerScaffold(pagerState = pagerState) {
       HorizontalPager(
          state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold {
…
   }
}

Infine, M3 introduce VerticalPagerScaffold, che segue lo stesso schema 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

Esistono alcune modifiche all'API tra M2.5 e M3. Placeholder.PlaceholderDefaults ora fornisce due modificatori:

• Modifier.placeholder, che viene visualizzato al posto dei contenuti non ancora caricati
• Un effetto di sfarfallio segnaposto Modifier.placeholderShimmer che fornisce un effetto di sfarfallio segnaposto che viene eseguito in un loop di animazione in attesa del caricamento dei dati.

Di seguito sono riportate ulteriori modifiche 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 dell'elenco durante lo scorrimento, migliorando l'esperienza utente.

Analogamente a ScalingLazyColumn, fornisce rememberTransformingLazyColumnState() per creare un TransformingLazyColumnState che viene ricordato nelle varie composizioni.

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

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

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.material3.SurfaceTransformation
import androidx.wear.compose.material3.lazy.rememberTransformationSpec
import androidx.wear.compose.material3.lazy.transformedHeight
import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
import androidx.wear.compose.foundation.lazy.TransformingLazyColumn

val state = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
AppScaffold {
   ScreenScaffold(state) { contentPadding ->
      TransformingLazyColumn(state = state, contentPadding = contentPadding) {
         items(count = 50) {
            Button(
               onClick = {},
               modifier =
                        Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                        transformation = SurfaceTransformation(transformationSpec),
                    ) {
                        Text("Item $it")
                    }
                }
            }
        }
    }

Link utili

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

Campioni

Esempi per Wear OS nel ramo Material3 su GitHub

Codelab di Compose per Wear OS

Riferimento API e codice sorgente

• Riferimento all'API Compose Material 3
• Comporre esempi di Material 3 nel codice sorgente

Design

• Indicazioni per il design