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 de 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.
- Adopter une approche par étapes
Dépendances
M3 possède un package et une version distincts de M2.5 :
M2.5
implementation("androidx.wear.compose:compose-material:1.4.0")
M3
implementation("androidx.wear.compose:compose-material3:1.5.0-beta05")
Consultez les dernières versions de M3 sur la page des versions de Wear Compose Material 3.
La bibliothèque Wear Compose Foundation version 1.5.0-beta01 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 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 de mettre à jour également les bibliothèques Wear Compose Foundation et Navigation :
implementation("androidx.wear.compose:compose-foundation:1.5.0-beta05")
implementation("androidx.wear.compose:compose-navigation:1.5.0-beta05")
Personnalisation des thèmes
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.
M2.5
import androidx.wear.compose.material.MaterialTheme
MaterialTheme(
colors = AppColors,
typography = AppTypography,
shapes = AppShapes,
content = content
)
M3
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 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 :
M2.5
import androidx.wear.compose.material.Colors
val appColorScheme: Colors = Colors(
// M2.5 Color parameters
)
M3
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 :
M2.5 |
M3 |
|---|---|
|
a été renommé |
13 couleurs |
28 couleurs |
N/A |
Nouveau thème de couleur dynamique |
N/A |
de nouvelles couleurs tertiaires pour plus d'expression ; |
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 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
- Les polices flexibles, qui permettent de personnaliser les échelles typographiques pour différentes épaisseurs, largeurs et arrondis
AnimatedText, qui utilise des polices flexibles
M2.5
import androidx.wear.compose.material.Typography
val Typography = Typography(
// M2.5 TextStyle parameters
)
M3
import androidx.wear.compose.material3.Typography
val Typography = Typography(
// M3 TextStyle parameters
)
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. Ils sont utilisés par défaut par les différents composants de M3.
Typographie |
TextStyle |
|---|---|
Écran |
displayLarge, displayMedium, displaySmall |
Titre |
titleLarge, titleMedium, titleSmall |
Label |
labelLarge, labelMedium, labelSmall |
Corps |
bodyLarge, bodyMedium, bodySmall, bodyExtraSmall |
Chiffre |
numeralExtraLarge, numeralLarge, numeralMedium, numeralSmall, numeralExtraSmall |
Arc |
arcLarge, arcMedium, arcSmall |
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 formes suivantes sont disponibles :
- Très petite
- Petit
- Moyenne
- Grande
- Très grande
Dans Compose, cela s'applique à la classe Shapes M2 et à la classe Shapes M3 :
M2.5
import androidx.wear.compose.material.Shapes
val Shapes = Shapes(
// M2.5 Shapes parameters
)
M3
import androidx.wear.compose.material3.Shapes
val Shapes = Shapes(
// M3 Shapes parameters
)
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 la morphose des formes : 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, voir ci-dessous :
Boutons |
Fonction de morphing de forme |
|---|---|
|
IconButtonDefaults.animatedShape() anime le bouton d'icône lorsque l'utilisateur appuie dessus. |
|
IconToggleButtonDefaults.animatedShape() anime le bouton bascule d'icône lorsque l'utilisateur appuie dessus et IconToggleButtonDefaults.variantAnimatedShapes() anime le bouton bascule d'icône lors de l'appui et de la sélection/désélection. |
|
TextButtonDefaults.animatedShape() anime le bouton de texte lorsque l'utilisateur appuie dessus. |
|
TextToggleButtonDefaults.animatedShapes() anime le bouton bascule de texte lors de l'appui, et TextToggleButtonDefaults.variantAnimatedShapes() anime le bouton bascule de texte lors de l'appui et de la sélection/désélection. |
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 :
Material 3 |
Composant Material 2.5 équivalent (s'il n'est pas nouveau dans M3) |
|---|---|
Nouveau |
|
Nouveau |
|
android.wear.compose.material.Scaffold (avec androidx.wear.compose.material3.ScreenScaffold) |
|
Nouveau |
|
androidx.wear.compose.material.ToggleChip avec un bouton bascule de case à cocher |
|
androidx.wear.compose.material.Chip (uniquement lorsqu'aucun arrière-plan n'est requis) |
|
Nouveau |
|
Nouveau |
|
Nouveau |
|
androidx.wear.compose.material.Chip lorsqu'un arrière-plan de bouton tonal est requis |
|
Nouveau |
|
Nouveau |
|
Nouveau |
|
Nouveau |
|
Nouveau |
|
androidx.wear.compose.material.ToggleChip avec un bouton radio |
|
android.wear.compose.material.Scaffold (avec androidx.wear.compose material3.AppScaffold) |
|
androidx.wear.compose.material3.SegmentedCircularProgressIndicator |
Nouveau |
androidx.wear.compose.material.SwipeToRevealCard et androidx.wear.compose.material.SwipeToRevealChip |
|
androidx.wear.compose.material.ToggleChip avec un bouton bascule |
|
Nouveau |
Enfin, voici une liste de certains composants pertinents de la bibliothèque Wear Compose Foundation version 1.5.0-beta01 :
Wear Compose Foundation 1.5.0-beta |
|
|---|---|
Utilisé pour annoter les composables d'une application, afin de suivre la partie active de la composition et de coordonner la mise au point. |
|
Un composant Pager à défilement horizontal, basé sur les composants Compose Foundation avec des améliorations spécifiques à Wear pour améliorer les performances et la conformité aux consignes Wear OS. |
|
Un pager à défilement vertical, basé sur les composants Compose Foundation avec des améliorations spécifiques à Wear pour améliorer les performances et la conformité aux consignes Wear OS. |
|
Peut être utilisé à la place de ScalingLazyColumn pour ajouter des effets de transformation de défilement à chaque élément. |
|
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.
M2.5
import androidx.wear.compose.material.Chip
//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)
M3
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 : 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 à ScreenScaffold pour qu'il se transforme et change de forme au 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é 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.
M2.5
import androidx.wear.compose.material.Scaffold
Scaffold {...}
M3
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 définissent 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/le masquage de TimeText et HorizontalPageIndicator selon que Pager est paginé ou non. Cela 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.
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 VerticalPagerScaffold, qui suit le même modèle 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 à 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 miroitement de l'espace réservé
Modifier.placeholderShimmerqui fournit un effet de miroitement de l'espace réservé qui s'exécute dans une boucle d'animation en attendant le chargement des données.
Vous trouverez ci-dessous d'autres modifications apportées au composant Placeholder.
M2.5 |
M3 |
|---|---|
|
a été supprimée. |
|
a été supprimée. |
|
a été renommé |
|
a été supprimée. |
|
a été supprimé |
|
a été supprimée. |
|
a été supprimée. |
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.
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'unTransformationSpec. Vous pouvez utiliserrememberTransformationSpec(), sauf si vous avez besoin d'une personnalisation plus poussée.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
- 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