Passer de Material 2.5 à Material 3 dans Compose pour Wear OS

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 traite de la migration de la bibliothèque Jetpack Wear Compose Material 2.5 (androidx.wear.compose) vers 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 que celle décrite dans le guide de migration Compose Material pour téléphone, en particulier :

• Vous ne devez pas utiliser à la fois M2.5 et M3 dans une même application sur une longue période.
• Vous ne devez plus utiliser les bibliothèques Horologist Composables, Compose Layout ni Compose Material. Utilisez plutôt les composants de M3.
• Adoptez 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.6.0")

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

La version 1.6.0 de la bibliothèque Wear Compose Foundation a introduit de nouveaux composants conçus pour fonctionner avec les composants Material 3. De même, SwipeDismissableNavHost de la bibliothèque Wear Compose Navigation a une animation mise à jour lorsqu'elle est exécutée 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 de mettre à jour les bibliothèques Wear Compose Foundation et Navigation :

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

Thème

Dans M2.5 et M3, le composable 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 = ColorScheme(),
        typography = Typography(),
        shapes = Shapes(),
        motionScheme = MotionScheme.standard(),
        content = { /*content here*/ }
    )
Theme.kt

Couleur

Le système de couleurs de M3 est très différent de celui de M2.5. Le nombre de paramètres de couleur 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
    )
Color.kt

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

Thèmes de couleurs dynamiques

La thématisation dynamique des couleurs est une nouvelle fonctionnalité de M3. Si les utilisateurs modifient les couleurs du cadran, celles de l'UI changent pour correspondre.

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

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

internal val myBrandColors: ColorScheme = ColorScheme( /* Specify colors here */)
Color.kt

Typographie

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

• Neuf nouveaux styles de texte
• Les polices flexibles, qui permettent de personnaliser les échelles typographiques pour différentes épaisseurs, largeurs et arrondis

• AnimatedText, qui utilise des polices flexibles

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
)
Typography.kt

Polices Flex

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

Styles de texte

Les TextStyles suivants sont disponibles dans M3. Elles sont utilisées par défaut par différents composants M3.

Forme

Le système de formes de M3 est différent de celui de M2.5. 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 formes suivantes sont disponibles :

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

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

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
)
Shape.kt

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

Morphing de forme

M3 introduit le morphing de forme : les formes se transforment désormais en réponse aux interactions.

Le comportement de morphing de forme est disponible en tant que variante sur un certain nombre de boutons ronds. Consultez la liste suivante des boutons qui prennent en charge le morphing de forme :

Composants et mise en page

La plupart des composants et mises en page de M2.5 sont disponibles dans M3. Cependant, certains composants et mises en page 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 :

Boutons

Les boutons de M3 sont différents de ceux de M2.5. La puce M2.5 a été remplacée par un bouton. 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(...)

//M3 Buttons
Button(onClick = { }){}
CompactButton(onClick = { }){}
IconButton(onClick = { }){}
TextButton(onClick = { }){}
Button.kt

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 : 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 ou ScalingLazyColumn, transmettez EdgeButton à ScreenScaffold afin qu'il se transforme et change de forme au défilement, au lieu d'ajouter EdgeButton comme dernier élément de la liste. Consultez le code suivant pour savoir comment utiliser EdgeButton avec ScreenScaffold et TransformingLazyColumn.

val state = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = state,
    contentPadding =
        rememberResponsiveColumnPadding(
            first = ColumnItemType.ListHeader
        ),
    edgeButton = {
        EdgeButton(
            onClick = { }
        ) {
            Text(stringResource(R.string.show))
        }
    }
){ contentPadding ->
    TransformingLazyColumn(state = state, contentPadding = contentPadding,){
        // additional code here
    }
}
Button.kt

Scaffold

Les échafaudages de M3 sont différents de ceux de M2.5. Dans M3, AppScaffold et le nouveau composable ScreenScaffold ont remplacé Scaffold. AppScaffold et ScreenScaffold forment 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, comme pour 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. AppScaffold ajoute un composant TimeText par défaut aux écrans. Vous pouvez la remplacer si vous souhaitez la personnaliser à l'aide du paramètre timeText.

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

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

HorizontalPagerScaffold affiche HorizontalPageIndicator au centre de l'écran par défaut, et coordonne l'affichage et le masquage de TimeText et HorizontalPageIndicator selon que Pager est paginé ou non, ce qui est déterminé 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 voile en fonction de sa position.

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

Enfin, M3 introduit un VerticalPagerScaffold qui suit le même modèle que HorizontalPagerScaffold :

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

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

Espace réservé

Des modifications ont été apportées à l'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é
• Un effet de scintillement d'espace réservé Modifier.placeholderShimmer qui fournit un effet de scintillement d'espace réservé qui s'exécute dans une boucle d'animation en attendant le chargement des données.

Consultez le tableau ci-dessous pour découvrir les 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 LocalSwipeToDismissBackgroundScrimColor et LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn fait partie de wear.compose.lazy.foundation et ajoute la prise en charge 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. Nous recommandons vivement aux applications de migrer de ScalingLazyColumn vers TransformingLazyColumn.

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

Pour ajouter des animations de mise à l'échelle 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 plus poussée.
• SurfaceTransformation

Pour vérifier que la marge intérieure est correcte en haut et en bas de la liste, utilisez le modificateur minimumVerticalContentPadding.

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

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 sur GitHub
• Atelier de programmation sur Compose pour Wear OS
• Exemple Jetcaster

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