Migrowanie motywów XML do Material 3 w Compose

Gdy wprowadzisz Compose w istniejącej aplikacji, musisz przenieść motywy Material XML, aby używać MaterialTheme w komponentach Compose. Oznacza to, że motywy aplikacji będą miały 2 źródła informacji: motyw oparty na widokach i motyw Compose. Wszelkie zmiany w stylach trzeba będzie wprowadzać w kilku miejscach. Gdy aplikacja zostanie w pełni przeniesiona do Compose, usuń motywy XML.

Do przenoszenia kolorów możesz użyć narzędzia Material Theme Builder.

Gdy rozpoczniesz migrację z XML do Compose, przenieś motywy do motywów Material 3 Compose.

Słowniczek

Termin Definicja
MaterialTheme Funkcja typu „composable”, która zapewnia motywy (kolory, typografia, kształty) komponentom interfejsu Compose.
Shape Obiekt Compose używany do definiowania niestandardowych kształtów komponentów dla MaterialTheme.
Typography Obiekt Compose używany do definiowania niestandardowych stylów tekstu (rodzin czcionek, rozmiarów, grubości) dla MaterialTheme.
Color Obiekt Compose używany do definiowania niestandardowych schematów kolorów dla MaterialTheme.
Motyw XML System motywów Androida zdefiniowany w plikach XML, używany przez system widoków.

Ograniczenia

Zanim rozpoczniesz migrację, zapoznaj się z tymi ograniczeniami:

  • Ten przewodnik koncentruje się tylko na migracji do Material 3. Informacje o migracji z alternatywnych systemów projektowania znajdziesz w sekcji Material 2 lub niestandardowe systemy projektowania w Compose.
  • Ostatecznym celem jest pełna migracja do Compose, która umożliwia usunięcie motywów XML. Ten przewodnik wyjaśnia, jak przeprowadzić migrację, ale nie wyjaśnia, jak ostatecznie usunąć motywy XML.

Krok 1. Oceń system projektowania

Określ, który system projektowania jest używany w projekcie widoku XML. Przeanalizuj ścieżkę migracji i niezbędne kroki, aby przenieść istniejący system projektowania do Material 3 w Compose.

Krok 2. Określ źródłowe pliki motywów

W XML wpisujesz ?attr/colorPrimary. W Compose uzyskujesz dostęp do wartości motywu za pomocą MaterialTheme.*:

Zidentyfikuj i znajdź wszystkie zasoby i pliki XML niezbędne do motywów: jasne i ciemne schematy kolorów oraz kwalifikatory, motywy, kształty, wymiary, typografia, style i inne odpowiednie pliki.

Zasoby takie jak ciągi znaków można ponownie wykorzystać w niezmienionej postaci i nie trzeba ich przenosić.

Krok 3. Przenieś kolory

Główna zasada: XML używa nazwanych kolorów szesnastkowych. Material 3 używa ról semantycznych (np.primary, onPrimary, surface). Przestań nazywać kolory według ich wartości szesnastkowych. Nadaj im nazwy według ich roli.

Przykłady:

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

Przenieś jasne i ciemne schematy kolorów z XML do ich odpowiedników w Material 3 Compose.

Krok 4. Przenieś niestandardowe kształty i typografię

  • Jeśli Twoja aplikacja używa niestandardowych kształtów:

    1. W kodzie Compose zdefiniuj obiekt Shape, aby odtworzyć definicje kształtów XML.

    2. Podaj ten obiekt Shape w MaterialTheme.

      Więcej informacji znajdziesz w sekcji Kształty.

  • Jeśli Twoja aplikacja używa niestandardowej typografii:

    1. W kodzie Compose zdefiniuj obiekt Typography, aby odtworzyć style tekstu i definicje czcionek XML.

    2. Podaj ten obiekt Typography w MaterialTheme.

      Więcej informacji znajdziesz w sekcji Typografia.

Rola Compose Nazwa 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

Krok 5. Przenieś style (styles.xml)

System stylów XML (styles.xml) definiuje style i wygląd: widżetów, komponentów, motywów okien i okien dialogowych; typografii; motywów i nakładek; kształtów.

Widoki i komponenty XML łączą wiele atrybutów, aby utworzyć styl. Ustawiają swoje style z pliku styles.xml na 2 sposoby: Ustawienie „style="@style/..." bezpośrednio i jawnie w widoku XML. Ustawienie stylu pośrednio i niejawnie dla komponentu jako części większego motywu (theme.xml).

Style nie mają bezpośredniego odpowiednika w Compose. Zamiast tego style są przekazywane jako parametry do funkcji kompozycyjnych, zdefiniowane w AppTheme lub przez utworzenie warstwowych, wielokrotnego użytku wariantów kompozycyjnych ze zdefiniowanym stylem.

Podaj oddzielne funkcje @Composable nazwane zgodnie ze stylem i komponentem podstawowym, aby wskazać różnicę w stylach i przypadkach użycia tych komponentów.

  • Wzorzec: jeśli element XML używa stylu niestandardowego (np. style="@style/MyPrimaryButton"), nie próbuj odtworzyć stylu w tekście. Zamiast tego zaproponuj utworzenie konkretnej funkcji kompozycyjnej.
  • Przykład:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Typowe grupy atrybutów: jeśli styl ustawia typowe modyfikatory (np. padding + height), wyodrębnij je do czytelnej właściwości rozszerzenia lub współdzielonej zmiennej Modifier.

Typowe przykłady

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

Krok 6. Sprawdź migrację motywu

Zawsze używaj istniejących wartości motywu z oryginalnego motywu XML jako źródła informacji o nowym motywie Material w Compose. Podczas migracji nigdy nie wymyślaj nowych wartości motywu, aby zachować spójność marki i uniknąć regresji wizualnych.

Sprawdź, czy wszystkie nowe wartości motywu Compose są zgodne z istniejącymi wartościami XML. Nie koduj na stałe żadnych przeniesionych wartości.