Migrowanie motywów XML do Material 3 w Compose

Gdy wprowadzisz Compose w dotychczasowej 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 widokach i motyw Compose. Wszelkie zmiany w stylu muszą być wprowadzane w wielu miejscach. Gdy aplikacja zostanie w pełni przeniesiona na Jetpack Compose, usuń motyw XML.

Do przenoszenia kolorów możesz użyć narzędzia do tworzenia motywów Material.

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

Słowniczek

Termin	Definicja
`MaterialTheme`	Funkcja typu „composable”, która zapewnia motyw (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 elementu `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 View.

Ograniczenia

Przed migracją zapoznaj się z tymi ograniczeniami:

Ten przewodnik dotyczy tylko migracji do Material 3. Informacje o migracji z alternatywnych systemów projektowania znajdziesz w sekcjach Material 2 i Niestandardowe systemy projektowania w Compose.
Ostatecznym celem jest pełna migracja do Compose, która umożliwi usunięcie motywów XML. W tym przewodniku wyjaśniamy, jak przeprowadzić migrację, ale nie opisujemy, jak ostatecznie usunąć motywy XML.

Krok 1. Oceń system projektowania

Określ, którego systemu projektowania użyto w projekcie widoku XML. Analizowanie ścieżki migracji i niezbędnych kroków, aby przenieść istniejący system projektowania do Material 3 w Compose.

Krok 2. Zidentyfikuj pliki źródłowe motywu

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

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

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

Krok 3. Przenieś kolory

Kluczowa zasada: XML używa nazwanych kolorów szesnastkowych. Material 3 używa ról semantycznych (np. primary, onPrimary, surface). Nie nazywaj kolorów za pomocą kodów szesnastkowych, tylko za pomocą ich ról.

Przykłady:

Nazwa koloru w 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ś schematy kolorów jasnych i ciemnych z XML na ich odpowiedniki 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łtu XML.
2. Przekaż ten obiekt Shape do MaterialTheme.
  
  Więcej informacji znajdziesz w sekcji kształty.
Jeśli Twoja aplikacja korzysta z niestandardowej typografii:
1. W kodzie Compose zdefiniuj obiekt Typography, aby odtworzyć style tekstu XML i definicje czcionek.
2. Przekaż ten obiekt Typography do MaterialTheme.
  
  Więcej informacji znajdziesz w sekcji typografia.

Tworzenie roli	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) określa style i wygląd: 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 sposoby: 1. Ustawienie „style="@style/..." bezpośrednio i jawnie w widoku XML. 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 do funkcji kompozycyjnych, zdefiniowane w motywie aplikacji lub przez tworzenie warstwowych, wielokrotnego użytku wariantów funkcji kompozycyjnych ze zdefiniowanym stylem.

Podaj oddzielne funkcje @Composable nazwane zgodnie ze stylem i komponentem bazowym, aby wskazać różnicę w stylizacji 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 zaproponuj utworzenie konkretnego komponentu.
Przykład:
- XML: <Button style="@style/MyPrimaryButton" ... />
- Utwórz: MyPrimaryButton(onClick = { ... })
Typowe grupy atrybutów: jeśli styl ustawia typowe modyfikatory (np. dopełnienie + wysokość), wyodrębnij je do czytelnej właściwości rozszerzenia lub wspólnej zmiennej modyfikatora.

Typowe przykłady

XML	Compose
`Theme.MaterialComponents.*`	`MaterialTheme(colorScheme, typography, shapes) { }`
`TextAppearance.Material3.BodyMedium`	`TextStyle(...)` zdefiniowano 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 twórz nowych wartości motywu, aby zachować spójność marki i uniknąć regresji wizualnych.

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