XML-Designs in Compose zu Material 3 migrieren

Wenn Sie Compose in eine vorhandene App einführen, müssen Sie Ihre Material-XML-Designs migrieren, damit MaterialTheme für Compose-Komponenten verwendet wird. Das bedeutet, dass das Design Ihrer App zwei Quellen der Wahrheit hat: das auf Ansichten basierende Design und das Compose-Design. Alle Änderungen an Ihrem Styling müssen an mehreren Stellen vorgenommen werden. Sobald Ihre App vollständig zu Compose migriert wurde, entfernen Sie Ihr XML-Design.

Sie können das Material Theme Builder Tool verwenden, um Farben zu migrieren.

Wenn Sie die Migration von XML zu Compose starten, migrieren Sie das Design zu Material 3 Compose-Design.

Glossar

Begriff Definition
MaterialTheme Die zusammensetzbare Funktion, die Compose-UI-Komponenten ein Design (Farben, Typografie, Formen) bietet.
Shapes Ein Compose-Objekt, mit dem benutzerdefinierte Komponentenformen für ein MaterialTheme definiert werden.
Typography Ein Compose-Objekt, mit dem benutzerdefinierte Textstile (Schriftfamilien, Größen, Stärken) für ein MaterialTheme definiert werden.
ColorScheme Ein Compose-Objekt, mit dem benutzerdefinierte Farbschemas für MaterialTheme definiert werden.
XML-Design Das Android-Designsystem, das in XML-Dateien definiert ist und vom Ansichtssystem verwendet wird.

Beschränkungen

Beachten Sie vor der Migration die folgenden Einschränkungen:

  • In diesem Leitfaden geht es nur um die Migration zu Material 3. Informationen zur Migration von alternativen Designsystemen finden Sie unter Material 2 oder benutzerdefinierte Designsysteme in Compose.
  • Das ultimative Ziel ist eine vollständige Migration zu Compose, wodurch das XML-Design entfernt werden kann. In diesem Leitfaden wird erläutert, wie Sie migrieren, aber nicht, wie Sie das XML-Design endgültig entfernen.

Schritt 1: Designsystem bewerten

Ermitteln Sie, welches Designsystem im XML-Ansichtsprojekt verwendet wird. Analysieren Sie den Migrationspfad und die erforderlichen Schritte, um das vorhandene Designsystem in Compose zu Material 3 zu migrieren.

Schritt 2: Designdateien ermitteln

In XML schreiben Sie ?attr/colorPrimary. In Compose greifen Sie mit MaterialTheme.* auf Designwerte zu:

Ermitteln und suchen Sie alle XML-Ressourcen und -Dateien, die für das Design erforderlich sind: helle und dunkle Farbschemas und Qualifizierer, Designs, Formen, Dimensionen, Typografie, Stile und andere relevante Dateien.

Ressourcen wie Strings können unverändert wiederverwendet werden und müssen nicht migriert werden.

Schritt 3: Farben migrieren

Grundprinzip:XML verwendet benannte Hex-Farben. Material 3 verwendet semantische Rollen (z.B. primary, onPrimary, surface). Benennen Sie Farben nicht mehr nach ihrem Hex-Wert, sondern nach ihrer Rolle.

Beispiele:

XML-Farbname Material 3-Rolle
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer oder secondary
colorAccent secondary oder tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Migrieren Sie die dunklen und hellen Farbschemas von XML zu den entsprechenden Farbschemas in Material 3 Compose.

Schritt 4: Benutzerdefinierte Formen und Typografie migrieren

  • Wenn Ihre App benutzerdefinierte Formen verwendet:

    1. Definieren Sie in Ihrem Compose-Code ein Shapes-Objekt, um Ihre XML-Formdefinitionen zu replizieren.

    2. Geben Sie dieses Shapes-Objekt an Ihr MaterialTheme weiter.

      Weitere Informationen finden Sie unter Formen.

  • Wenn Ihre App benutzerdefinierte Typografie verwendet:

    1. Definieren Sie in Ihrem Compose-Code ein Typography-Objekt, um Ihre XML-Textstile und Schriftdefinitionen zu replizieren.

    2. Geben Sie dieses Typography-Objekt an Ihr MaterialTheme weiter.

      Weitere Informationen finden Sie unter Typografie.

Compose-Rolle XML-Name
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

Schritt 5: Stile migrieren (styles.xml)

Das XML-Stilsystem (styles.xml) definiert Stile und Darstellung von:

  1. Widgets, Komponenten, Designs für Fenster und Dialogfelder
  2. Typografie
  3. Designs und Overlays
  4. Formen

XML-Ansichten und -Komponenten kombinieren mehrere Attribute, um einen Stil zu erstellen. Sie legen ihre Stile aus styles.xml auf zwei verschiedene Arten fest:

  1. Direktes und explizites Festlegen von „style="@style/..."“ in der XML-Ansicht
  2. Indirektes und implizites Festlegen des Stils für eine Komponente als Teil eines größeren Designs (theme.xml)

Stile haben in Compose kein direktes Äquivalent. Stattdessen werden Stile als: Parameter oder Modifikatoren an zusammensetzbare Funktionen übergeben, indem die neue experimentelle Styles API verwendet wird, die in AppTheme definiert ist, oder indem mehrschichtige, wiederverwendbare zusammensetzbare Varianten mit dem definierten Stil erstellt werden.

Geben Sie separate @Composable-Funktionen an, die nach dem Stil und der Basiskomponente benannt sind, um den Unterschied im Styling und in den Anwendungsfällen für diese Komponenten zu verdeutlichen.

  • Muster: Wenn ein XML-Element einen benutzerdefinierten Stil verwendet (z.B. style="@style/MyPrimaryButton"), versuchen Sie nicht, den Stil inline zu replizieren. Schlagen Sie stattdessen vor, eine bestimmte zusammensetzbare Funktion zu erstellen.
  • Beispiel:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose:MyPrimaryButton(onClick = { ... })
  • Allgemeine Attributgruppen:Wenn ein Stil allgemeine Modifikatoren (z. B. Padding + Höhe) festlegt, extrahieren Sie sie in eine lesbare Erweiterungseigenschaft oder eine gemeinsame Modifikatorvariable.

Typische Beispiele

XML Compose
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definiert in 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 in ComponentDefaults.ComponentColors()
android:textColor contentColor in ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) oder Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp in TextStyle

Schritt 6: Migration des Designs validieren

Verwenden Sie immer die vorhandenen Designwerte aus dem ursprünglichen XML-Design als Quelle der Wahrheit für das neue Material-Design in Compose. Erfinden Sie während der Migration keine neuen Designwerte, um die Markenkonsistenz zu wahren und visuelle Regressionen zu vermeiden.

Prüfen Sie, ob alle neuen Compose-Designwerte mit den vorhandenen XML-Werten übereinstimmen. Codieren Sie keine migrierten Werte fest.