Migrer des thèmes XML vers Material 3 dans Compose

Lorsque vous intégrez Compose dans une application existante, vous devez migrer vos thèmes XML Material afin d'utiliser MaterialTheme pour les composants Compose. Cela signifie que le thème de votre application combine deux sources de référence, l'une basée sur les vues et l'autre sur Compose. Vous devez donc effectuer plusieurs fois les éventuelles modifications que vous apportez à votre style. Une fois que votre application a été entièrement migrée vers Compose, supprimez votre thème XML.

Vous pouvez utiliser l'outil Material Theme Builder pour migrer les couleurs.

Lorsque vous commencez la migration du XML vers Compose, migrez la thématisation vers la thématisation Material 3 Compose.

Glossaire

Terme Définition
MaterialTheme Fonction composable qui fournit la thématisation (couleurs, typographie, formes) aux composants d'UI Compose.
Shapes Objet Compose utilisé pour définir des formes de composants personnalisées pour un MaterialTheme.
Typography Objet Compose permettant de définir des styles de texte personnalisés (familles de polices, tailles, graisses) pour un MaterialTheme.
ColorScheme Objet Compose utilisé pour définir des jeux de couleurs personnalisés pour MaterialTheme.
Thème XML Système de thèmes Android défini dans des fichiers XML, utilisé par le système View.

Limites

Avant de procéder à la migration, tenez compte des limites suivantes :

  • Ce guide se concentre uniquement sur la migration vers Material 3. Pour migrer depuis d'autres systèmes de conception, consultez Material 2 ou Systèmes de conception personnalisés dans Compose.
  • L'objectif final est une migration complète vers Compose, qui permet de supprimer les thèmes XML. Ce guide explique comment effectuer la migration, mais pas comment supprimer définitivement les thèmes XML.

Étape 1 : Évaluez le système de conception

Identifier le système de conception utilisé dans le projet XML View. Analysez le chemin de migration et les étapes nécessaires pour migrer le système de conception existant vers Material 3 dans Compose.

Étape 2 : Identifier les fichiers sources du thème

En XML, vous écrivez ?attr/colorPrimary. Dans Compose, vous accédez aux valeurs du thème avec MaterialTheme.* :

Identifiez et localisez toutes les ressources et tous les fichiers XML nécessaires à la thématisation : jeux de couleurs et qualificatifs clairs et sombres, thèmes, formes, dimensions, typographie, styles et autres fichiers pertinents.

Les ressources telles que les chaînes peuvent être réutilisées telles quelles et n'ont pas besoin d'être migrées.

Étape 3 : Migrer les couleurs

Principe clé : XML utilise des couleurs hexadécimales nommées. Material 3 utilise des rôles sémantiques (par exemple, primary, onPrimary, surface). Arrêtez de nommer les couleurs par leur code hexadécimal, nommez-les par leur rôle.

Exemples :

Nom de la couleur XML Rôle Material 3
colorPrimary primary
colorPrimaryDark/colorPrimaryVariant primaryContainer ou secondary
colorAccent secondary ou tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Migrez les jeux de couleurs clair et sombre du format XML vers leurs équivalents dans Material 3 Compose.

Étape 4 : Migrer les formes et la typographie personnalisées

  • Si votre application utilise des formes personnalisées :

    1. Dans votre code Compose, définissez un objet Shapes pour répliquer vos définitions de formes XML.

    2. Fournissez cet objet Shapes à votre MaterialTheme.

      Pour en savoir plus, consultez Formes.

  • Si votre application utilise une typographie personnalisée :

    1. Dans votre code Compose, définissez un objet Typography pour répliquer vos styles de texte XML et vos définitions de polices.

    2. Fournissez cet objet Typography à votre MaterialTheme.

      Pour en savoir plus, consultez Typographie.

Rôle Compose Nom XML
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

Étape 5 : Migrez les styles (styles.xml)

Le système de styles XML (styles.xml) définit les styles et l'apparence des éléments suivants :

  1. Widgets, composants, thèmes pour les fenêtres et les boîtes de dialogue
  2. Typographie
  3. Thèmes et superpositions
  4. Formes

Les vues et les composants XML combinent plusieurs attributs pour créer un style. Ils définissent leurs styles à partir de styles.xml de deux manières différentes :

  1. Définir "style="@style/..." directement et explicitement dans la vue XML
  2. Définir le style de manière indirecte et implicite pour un composant dans le cadre d'un thème plus vaste (theme.xml)

Les styles n'ont pas d'équivalent direct dans Compose. Ils sont plutôt transmis en tant que paramètres ou modificateurs aux composables, à l'aide de la nouvelle API Styles expérimentale définie dans AppTheme, ou en créant des variantes de composables réutilisables et superposées avec le style défini.

Fournissez des fonctions @Composable distinctes nommées en fonction du style et du composant de base, afin de signaler la différence de style et de cas d'utilisation de ces composants.

  • Modèle : si un élément XML utilise un style personnalisé (par exemple, style="@style/MyPrimaryButton"), n'essayez pas de reproduire le style de manière intégrée. Suggérez plutôt de créer un composable spécifique.
  • Exemple :
    • XML : <Button style="@style/MyPrimaryButton" ... />
    • Compose : MyPrimaryButton(onClick = { ... })
  • Groupes d'attributs courants : si un style définit des modificateurs courants (comme la marge intérieure et la hauteur), extrayez-les dans une propriété d'extension lisible ou une variable Modifier partagée.

Exemples courants

XML Nouveau message
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) défini dans Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint containerColor dans ComponentDefaults.ComponentColors()
android:textColor contentColor dans ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) ou Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp dans TextStyle

Étape 6 : Valider la migration du thème

Utilisez toujours les valeurs de thème existantes du thème XML d'origine comme source de vérité pour le nouveau thème Material dans Compose. N'inventez jamais de nouvelles valeurs de thème lors de la migration, afin de maintenir la cohérence de la marque et d'éviter les régressions visuelles.

Vérifiez que toutes les nouvelles valeurs du thème Compose correspondent aux valeurs XML existantes. Ne codez pas en dur les valeurs migrées.