XML-Designs in Compose zu Material 3 migrieren

Wenn Sie Compose in einer bestehenden App einführen, müssen Sie Ihre Material-XML-Themes migrieren, damit MaterialTheme für Compose-Komponenten verwendet wird. Das bedeutet, dass das Theming Ihrer App zwei „Sources of Truth“ hat: das View-basierte Theme und das Compose-Theme. Änderungen am Styling müssen an mehreren Stellen vorgenommen werden. Sobald Ihre App vollständig zu Compose migriert wurde, entfernen Sie das XML-Theming.

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

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

Glossar

Begriff Definition
MaterialTheme Die zusammensetzbare Funktion, die Compose-UI-Komponenten mit Theming-Informationen (Farben, Typografie, Formen) versieht.
Shape 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.
Color 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.

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, die das Entfernen von XML-Theming ermöglicht. In diesem Leitfaden wird beschrieben, wie Sie migrieren, aber nicht, wie Sie das XML-Theming 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: Quelldateien des Themes ermitteln

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

Identifizieren und lokalisieren 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:In XML werden benannte Hexadezimalfarben verwendet. In Material 3 werden semantische Rollen verwendet (z.B. primary, onPrimary, surface). Benennen Sie Farben nicht mehr nach ihrem Hexadezimalcode, 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 ihren Entsprechungen 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 Shape-Objekt, um Ihre XML-Formdefinitionen zu replizieren.

    2. Stellen Sie dieses Shape-Objekt für Ihre MaterialTheme bereit.

      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 Schriftartdefinitionen zu replizieren.

    2. Stellen Sie dieses Typography-Objekt für Ihre MaterialTheme bereit.

      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 System für XML-Stile (styles.xml) definiert Stile und die Darstellung von: 1. Widgets, Komponenten und Designs für Fenster und Dialogfelder 2. Typografie 3. Designs und Overlays 4. Formen

In XML-Ansichten und -Komponenten werden mehrere Attribute kombiniert, um ein Design zu erstellen. Sie legen ihre Stile in styles.xml auf zwei verschiedene Arten fest: 1. „style="@style/..." direkt und explizit in der XML-Ansicht festlegen 2. Stil für eine Komponente indirekt und implizit als Teil eines größeren Designs (theme.xml) festlegen

Stile haben in Compose kein direktes Äquivalent. Stattdessen werden sie als Parameter an Composables übergeben, in AppTheme definiert oder durch Erstellen von mehrschichtigen, wiederverwendbaren Composable-Variationen mit dem definierten Stil.

Stellen Sie separate @Composable-Funktionen bereit, die nach dem Stil und der Basiskomponente benannt sind, um den Unterschied in der Gestaltung und 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" ... />
    • Schreiben: MyPrimaryButton(onClick = { ... })
  • Häufig verwendete Attributgruppen:Wenn in einem Stil häufig verwendete Modifizierer (z. B. „padding“ und „height“) festgelegt werden, extrahieren Sie sie in eine lesbare Erweiterungseigenschaft oder eine gemeinsam verwendete Modifizierervariable.

Häufige Beispiele

XML Schreiben
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) in Typography(bodyMedium = ...) definiert
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 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: Themenmigration validieren

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

Prüfen Sie, ob alle neuen Compose-Themenwerte mit den vorhandenen XML-Werten übereinstimmen. Migrierte Werte dürfen nicht fest codiert werden.