XML-Designs in Compose zu Material 3 migrieren

Wenn Sie Compose in einer vorhandenen App einführen, müssen Sie Ihre Material-XML-Designs migrieren, um MaterialTheme für Compose-Komponenten zu verwenden. Das bedeutet, dass das Design Ihrer App zwei „Sources of Truth“ hat: das ansichtsbasierte Design und das Compose-Design. Änderungen am Stil müssen an mehreren Stellen vorgenommen werden. Sobald Ihre App vollständig zu Compose migriert wurde, entfernen Sie das XML-Design.

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

Wenn Sie mit der Migration von XML zu Compose beginnen, migrieren Sie das Design zum Material 3 Compose-Design.

Glossar

Begriff Definition
MaterialTheme Die zusammensetzbare Funktion, die Compose-UI-Komponenten Designs (Farben, Typografie, Formen) zur Verfügung stellt.
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 in XML-Dateien definierte Android-Theming-System, das vom View-System verwendet wird.

Einschrä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, sodass XML-Designs entfernt werden können. In diesem Leitfaden wird die Migration erläutert, aber nicht, wie XML-Theming endgültig entfernt wird.

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 zu Material 3 in Compose zu migrieren.

Schritt 2: Quelldateien für das Design identifizieren

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

Identifiziere und finde alle XML-Ressourcen und -Dateien, die für das Design erforderlich sind: helle und dunkle Farbschemata und Qualifizierer, Designs, Formen, Abmessungen, 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: In XML werden benannte Hex-Farbcodes verwendet. Material 3 verwendet semantische Rollen (z.B. primary, onPrimary, surface). Benennen Sie Farben nicht nach ihrem Hexadezimalwert, 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 Schemas 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. Stellen Sie dieses Shapes-Objekt Ihrem MaterialTheme zur Verfügung.

      Weitere Informationen finden Sie unter Formen.

  • Wenn in Ihrer App benutzerdefinierte Typografie verwendet wird:

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

    2. Stellen Sie dieses Typography-Objekt Ihrem MaterialTheme zur Verfügung.

      Weitere Informationen finden Sie unter Typografie.

Rolle „Compose“ 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 die Stile und das Erscheinungsbild von:

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

In XML-Ansichten und -Komponenten werden mehrere Attribute kombiniert, um einen Stil zu erstellen. Sie legen ihre Stile auf zwei verschiedene Arten in „styles.xml“ fest:

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

Stile haben in Compose keine direkte Entsprechung. Stattdessen werden sie als Parameter oder Modifikatoren an komponierbare Funktionen übergeben. Dazu wird die neue, experimentelle Styles API verwendet, die im AppTheme definiert ist, oder es werden mehrschichtige, wiederverwendbare Varianten komponierbarer Funktionen mit dem definierten Stil erstellt.

Stellen Sie separate @Composable-Funktionen bereit, die nach dem Stil und der Basiskomponente benannt sind, um den Unterschied im Stil 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, ein bestimmtes Composable zu erstellen.
  • Beispiel:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Schreiben: MyPrimaryButton(onClick = { ... })
  • Gemeinsame Attributgruppen: Wenn ein Stil gemeinsame Modifikatoren (z. B. Padding und Höhe) festlegt, extrahieren Sie sie in eine lesbare Erweiterungseigenschaft oder eine gemeinsame Modifier-Variable.

Typische Beispiele

XML Schreiben
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: Designmigration validieren

Verwenden Sie immer die vorhandenen Designwerte aus dem ursprünglichen XML-Design als Quelle für das neue Material Theme 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. Migrierte Werte dürfen nicht hartcodiert werden.