Migrowanie motywów XML do Material 3 w Compose

Gdy wprowadzasz Compose w istniejącej aplikacji, musisz przenieść motywy Material XML, aby używać MaterialTheme w przypadku komponentów Compose. Oznacza to, że motyw aplikacji będzie miał 2 źródła informacji: motyw oparty na widoku i motyw Compose. Wszelkie zmiany w stylu trzeba wprowadzać w wielu miejscach. Po pełnym przeniesieniu aplikacji do Compose usuń motywy XML.

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

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

Słowniczek

Okres obowiązywania Definicja
MaterialTheme Funkcja typu „composable”, która zapewnia motywy (kolory, typografię, kształty) komponentom interfejsu Compose.
Shapes Obiekt Compose używany do definiowania niestandardowych kształtów komponentów dla elementu MaterialTheme.
Typography Obiekt Compose używany do definiowania niestandardowych stylów tekstu (rodzin czcionek, rozmiarów, grubości) dla elementu MaterialTheme.
ColorScheme Obiekt Compose używany do definiowania niestandardowych schematów kolorów dla aplikacji 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 dotyczy tylko migracji do Material 3. Informacje o migracji z alternatywnych systemów projektowania znajdziesz w artykułach Material 2 i Niestandardowe systemy projektowania w Compose.
  • Ostatecznym celem jest pełna migracja do Compose, która umożliwia usunięcie motywów XML. W tym przewodniku wyjaśniono, jak przeprowadzić migrację, ale nie wyjaśniono, 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. Zidentyfikuj pliki źródłowe motywu

W języku XML zapisuje się to jako ?attr/colorPrimary. W Compose wartości motywu są dostępne za pomocą MaterialTheme.*:

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

Zasoby takie jak ciągi znaków mogą być używane ponownie w niezmienionej postaci i nie trzeba ich przenosić.

Krok 3. Przenieś kolory

Podstawowa zasada: XML używa nazwanych szesnastkowych kodów kolorów. Material 3 używa ról semantycznych (np. primary, onPrimary, surface). Przestań nazywać kolory według ich kodu szesnastkowego – nazywaj je według ich roli.

Przykłady:

Nazwa koloru w pliku 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ś ciemne i jasne schematy kolorów z XML do ich odpowiedników w Material 3 Compose.

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

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

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

    2. Przekaż ten obiekt Shapes do MaterialTheme.

      Więcej informacji znajdziesz w sekcji Kształty.

  • Jeśli aplikacja używa niestandardowej typografii:

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

    2. Przekaż ten obiekt Typography do MaterialTheme.

      Więcej informacji znajdziesz w sekcji Typografia.

Rola tworzenia wiadomości 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)

Style XML (styles.xml) definiują style i wygląd:

  1. widżety, komponenty, motywy okien i okien dialogowych;
  2. Typografia
  3. Motywy i nakładki
  4. Kształty

Widoki i komponenty XML łączą wiele atrybutów, aby utworzyć styl. Style są ustawiane w pliku styles.xml na 2 różne sposoby:

  1. Ustawienie „style="@style/..." bezpośrednio i jawnie w widoku XML.
  2. ustawianie stylu pośrednio i niejawnie dla komponentu w ramach większego motywu (theme.xml);

Style nie mają bezpośredniego odpowiednika w Compose. Zamiast tego są przekazywane jako parametry lub modyfikatory do funkcji kompozycyjnych przy użyciu nowego, eksperymentalnego interfejsu Styles API zdefiniowanego w AppTheme lub przez utworzenie warstwowych, wielokrotnego użytku wariantów funkcji kompozycyjnych ze zdefiniowanym stylem.

Podaj osobne funkcje typu „composable” nazwane zgodnie ze stylem i komponentem podstawowym, aby wskazać różnice 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ć tego stylu w tekście. Zamiast tego zasugeruj utworzenie konkretnego elementu kompozycyjnego.
  • Przykład:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Utwórz: MyPrimaryButton(onClick = { ... })
  • Typowe grupy atrybutów: jeśli styl ustawia typowe modyfikatory (np. dopełnienie i wysokość), wyodrębnij je do czytelnej właściwości rozszerzenia lub udostępnionej zmiennej modyfikatora.

Typowe przykłady

XML Utwórz
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) zdefiniowane w: 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 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 dotychczasowych wartości motywu z oryginalnego motywu XML jako źródła informacji o nowym motywie Material Theme w Compose. Podczas migracji nigdy nie twórz nowych wartości motywu, aby zachować spójność marki i uniknąć regresji wizualnej.

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.