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 votre application 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 d'XML vers Compose, migrez le thème vers le thème Compose Material 3.

Glossaire

Terme Définition
MaterialTheme Fonction composable qui fournit des thèmes (couleurs, typographie, formes) aux composants de l'UI Compose.
Shape Objet Compose utilisé pour définir des formes de composants personnalisées pour un MaterialTheme.
Typography Objet Compose utilisé pour définir des styles de texte personnalisés (familles de polices, tailles, épaisseurs) pour un MaterialTheme.
Color 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 et utilisé par le système View.

Limites

Avant de migrer, 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 ultime est une migration complète vers Compose, qui permet de supprimer le thème XML. Ce guide explique comment migrer, mais pas comment supprimer définitivement le thème XML.

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

Identifiez 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 devez écrire ?attr/colorPrimary. Dans Compose, vous accédez aux valeurs de thème avec MaterialTheme.* :

Identifiez et localisez toutes les ressources et tous les fichiers XML nécessaires à la création de thèmes : schémas et qualificatifs de couleurs claires 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 et nommez-les par leur rôle.

Exemples :

Nom de 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 clairs et sombres du fichier XML vers leurs équivalents dans Material 3 Compose.

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

  • Si votre application utilise des formes personnalisées :

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

    2. Fournissez cet objet Shape à 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 et définitions de police XML.

    2. Fournissez cet objet Typography à votre MaterialTheme.

      Pour en savoir plus, consultez Typographie.

Rôle Composer 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 et 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éfinissez "style="@style/..." directement et explicitement dans la vue XML. 2. Définir le style indirectement et implicitement pour un composant dans 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 aux composables, définis 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, pour indiquer la différence de style et les 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 en ligne. À la place, suggérez de créer un composable spécifique.
  • Exemple :
    • XML : <Button style="@style/MyPrimaryButton" ... />
    • Nouveau message : 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 Compose
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) défini dans Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.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 en ComponentDefaults.ComponentColors()
android:textColor contentColor en 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 en 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 en dur aucune valeur migrée.