Material 3 Expressive est la nouvelle évolution de Material Design. Elle inclut des thèmes et des composants mis à jour ainsi que des fonctionnalités de personnalisation telles que les couleurs dynamiques.

Ce guide explique comment passer de la bibliothèque Jetpack Wear Compose Material 2.5 (androidx.wear.compose) à la bibliothèque Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) pour les applications.

Approches

Pour migrer le code de votre application de M2.5 vers M3, suivez la même approche décrite dans les conseils pour la migration du téléphone Compose Material, en particulier:

• Vous ne devez pas utiliser à la fois M2.5 et M3 dans une même application sur une longue période.
• Adopter une approche par étapes

Dépendances

M3 possède un package et une version distincts de M2.5:

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

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

Consultez les dernières versions de M3 sur la page des versions de Wear Compose Material 3.

La version 1.5.0-beta01 de la bibliothèque Wear Compose Foundation introduit de nouveaux composants conçus pour fonctionner avec les composants Material 3. De même, SwipeDismissableNavHost de la bibliothèque de navigation Wear Compose a une animation mise à jour lorsqu'il s'exécute sur Wear OS 6 (niveau d'API 36) ou version ultérieure. Lorsque vous passez à la version Wear Compose Material 3, nous vous suggérons également de mettre à jour les bibliothèques Wear Compose Foundation et Navigation:

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

Personnalisation des thèmes

Dans M2.5 et M3, le composable de thème est appelé MaterialTheme, mais les packages et paramètres d'importation diffèrent. Dans M3, le paramètre Colors a été renommé ColorScheme et MotionScheme a été introduit pour implémenter les transitions.

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
)

Couleur

Le système de couleurs de M3 est très différent de celui de M2.5. Le nombre de paramètres colorimétriques a augmenté, leurs noms sont différents et ils sont mappés différemment aux composants M3. Dans Compose, cela s'applique à la classe M2.5 Colors, à la classe M3 ColorScheme et aux fonctions associées:

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
)

Le tableau suivant décrit les principales différences entre M2.5 et M3:

Thème de couleurs dynamiques

La thématisation des couleurs dynamique est une nouvelle fonctionnalité de M3. Si les utilisateurs modifient les couleurs du cadran, les couleurs de l'interface utilisateur changent en conséquence.

Utilisez la fonction dynamicColorScheme pour implémenter un jeu de couleurs dynamique et fournissez un defaultColorScheme en remplacement si le jeu de couleurs dynamique n'est pas disponible.

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

Typographie

Le système typographique de M3 est différent de celui de M2 et inclut les fonctionnalités suivantes:

• Neuf nouveaux styles de texte
• Polices Flex, qui permettent de personnaliser les échelles de type pour différentes épaisseurs, largeurs et rondeurs

• AnimatedText, qui utilise des polices Flex

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
)

Polices Flex

Les polices Flex permettent aux concepteurs de spécifier la largeur et l'épaisseur du type pour des tailles spécifiques.

Styles de texte

Les styles de texte suivants sont disponibles dans M3. Ils sont utilisés par défaut par divers composants M3.

Forme

Le système de formes de M3 est différent de celui de M2. Le nombre de paramètres de forme a augmenté, leurs noms sont différents et ils sont mappés différemment aux composants M3. Les tailles de forme suivantes sont disponibles:

• Très petite
• Petit
• Moyenne
• Grande
• Très grand

Dans Compose, cela s'applique à la classe M2 Shapes (Formes) et à la classe M3 Shapes (Formes) :

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
)

Utilisez le mappage des paramètres de forme de la section Passer de Material 2 à Material 3 dans Compose comme point de départ.

Morphing de forme

M3 introduit la morphing des formes: les formes se transforment désormais en fonction des interactions.

Le comportement de morphing de forme est disponible en tant que variante de plusieurs boutons ronds, comme indiqué ci-dessous:

Composants et mise en page

La plupart des composants et mises en page de M2.5 sont disponibles dans M3. Toutefois, certains composants et mises en page de M3 n'existaient pas dans M2.5. De plus, certains composants M3 présentent plus de variantes que leurs équivalents dans M2.5.

Bien que certains composants nécessitent une attention particulière, les mappages de fonctions suivants sont recommandés pour commencer :

Voici la liste complète de tous les composants Material 3:

Enfin, voici une liste de certains composants pertinents de la bibliothèque Wear Compose Foundation version 1.5.0-beta01:

Boutons

Les boutons de M3 sont différents de ceux de M2.5. La puce M2.5 a été remplacée par Button. L'implémentation de Button fournit des valeurs par défaut pour Text, maxLines et textAlign. Ces valeurs par défaut peuvent être remplacées dans l'élément 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 inclut également de nouvelles variantes des boutons. Vous en trouverez une description dans la présentation de la documentation de référence de l'API Compose Material 3.

M3 introduit un nouveau bouton: EdgeButton. EdgeButton est disponible en quatre tailles différentes: XS, S, M et L. L'implémentation de EdgeButton fournit une valeur par défaut pour maxLines en fonction de la taille, qui peut être personnalisée.

Si vous utilisez TransformingLazyColumn et ScalingLazyColumn, transmettez EdgeButton dans ScreenScaffold pour qu'il se transforme, en modifiant sa forme avec le défilement. Consultez le code ci-dessous pour découvrir comment utiliser EdgeButton avec ScreenScaffold et 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

Les échafaudages de M3 sont différents de ceux de M2.5. Dans M3, AppScaffold et le nouveau composable ScreenScaffold ont remplacé l'échafaudage. AppScaffold et ScreenScaffold organisent la structure d'un écran et coordonnent les transitions des composants ScrollIndicator et TimeText.

AppScaffold permet aux éléments d'écran statiques tels que TimeText de rester visibles lors des transitions dans l'application, telles que le balayage pour ignorer. ​​Il fournit un emplacement pour le contenu principal de l'application, qui est généralement fourni par un composant de navigation tel que SwipeDismissableNavHost.

Vous déclarez un AppScaffold pour l'activité et utilisez un ScreenScaffold pour chaque écran.

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
    }
}

Si vous utilisez un HorizontalPager avec HorizontalPagerIndicator, vous pouvez migrer vers HorizontalPagerScaffold. HorizontalPagerScaffold est placé dans un AppScaffold. AppScaffold et HorizontalPagerScaffold organisent la structure d'un pager et coordonnent les transitions des composants HorizontalPageIndicator et TimeText.

HorizontalPagerScaffold affiche le HorizontalPageIndicator au centre de l'écran par défaut et coordonne l'affichage/le masquage de TimeText et de HorizontalPageIndicator selon que la Pager est paginée. Cette valeur est déterminée par PagerState.

Il existe également un nouveau composant AnimatedPage, qui anime une page dans un Pager avec un effet de mise à l'échelle et de scrim en fonction de sa position.

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 {
…
   }
}

Enfin, M3 introduit un VerticalPagerScaffold qui suit le même schéma que 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 {
        …
   }
}

Espace réservé

Des modifications ont été apportées aux API entre M2.5 et M3. Placeholder.PlaceholderDefaults propose désormais deux modificateurs:

• Modifier.placeholder, qui est dessiné à la place du contenu qui n'est pas encore chargé
• Effet de miroitement d'espace réservé Modifier.placeholderShimmer qui fournit un effet de miroitement d'espace réservé qui s'exécute dans une boucle d'animation en attendant que les données soient chargées.

Vous trouverez ci-dessous d'autres modifications apportées au composant Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost fait partie de wear.compose.navigation. Lorsque ce composant est utilisé avec M3, le MaterialTheme M3 met à jour les LocalSwipeToDismissBackgroundScrimColor et LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn fait partie de wear.compose.lazy.foundation et permet d'utiliser des animations de mise à l'échelle et de morphing sur les éléments de liste lors du défilement, ce qui améliore l'expérience utilisateur.

Comme ScalingLazyColumn, il fournit rememberTransformingLazyColumnState() pour créer un TransformingLazyColumnState qui est mémorisé dans toutes les compositions.

Pour ajouter des animations de scaling et de morphing, ajoutez les éléments suivants à chaque élément de liste:

• Modifier.transformedHeight, qui vous permet de calculer la hauteur transformée des éléments à l'aide d'un TransformationSpec, vous pouvez utiliser rememberTransformationSpec(), sauf si vous avez besoin d'une personnalisation supplémentaire.
• 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")
                    }
                }
            }
        }
    }

Liens utiles

Pour en savoir plus sur la migration de M2.5 vers M3 dans Compose, consultez les ressources supplémentaires suivantes.

Exemples

Exemples Wear OS dans la branche Material3 sur GitHub

Atelier de programmation sur Compose pour Wear OS

Documentation de référence de l'API et code source

• Documentation de référence de l'API Compose Material 3
• Exemples de Compose Material 3 dans le code source

Conception

• Conseils de conception