Перенесите XML-темы в Material 3 в Compose.

При внедрении Compose в существующее приложение необходимо перевести XML-темы Material на использование MaterialTheme для компонентов Compose. Это означает, что у оформления вашего приложения будет два источника достоверной информации: тема на основе представления и тема Compose. Любые изменения в стилях необходимо вносить в нескольких местах. После полной миграции приложения на Compose удалите XML-тему.

Для переноса цветов можно использовать инструмент Material Theme Builder .

При начале миграции с XML на Compose, перенесите темы оформления на Material 3 Compose.

Глоссарий

Срок Определение
MaterialTheme Компонуемая функция, которая обеспечивает оформление (цвета, типографику, формы) компонентов Compose UI.
Shape Объект Compose, используемый для определения пользовательских форм компонентов для MaterialTheme .
Typography Объект Compose, используемый для определения пользовательских стилей текста (семейства шрифтов, размеры, толщина) для темы MaterialTheme .
Color Объект Compose, используемый для определения пользовательских цветовых схем для MaterialTheme .
XML-тема Система оформления тем Android, определенная в XML-файлах и используемая системой View.

Ограничения

Перед миграцией учитывайте следующие ограничения:

  • Данное руководство посвящено только миграции на Material 3. Для миграции с альтернативных систем дизайна см. Material 2 или пользовательские системы дизайна в Compose .
  • Конечная цель — полная миграция на Compose, что позволит отказаться от XML-тематики. В этом руководстве объясняется, как осуществить миграцию, но не объясняется, как окончательно удалить XML-тематику.

Шаг 1: Оцените систему проектирования.

Определите, какая система проектирования используется в проекте XML View. Проанализируйте путь миграции и необходимые шаги для переноса существующей системы проектирования в Material 3 в Compose.

Шаг 2: Определите исходные файлы темы.

В XML вы пишете ?attr/colorPrimary . В Compose вы получаете доступ к значениям темы с помощью MaterialTheme.* `.

Найдите и определите все XML-ресурсы и файлы, необходимые для оформления: светлые и темные цветовые схемы и параметры, темы, формы, размеры, типографику, стили и другие соответствующие файлы.

Такие ресурсы, как строки, можно использовать повторно в неизмененном виде, и их не нужно переносить.

Шаг 3: Перенос цветов

Ключевой принцип: XML использует именованные шестнадцатеричные значения цветов. Material 3 использует семантические роли (например, primary , onPrimary , surface ). Прекратите называть цвета по их шестнадцатеричным значениям; называйте их по их роли.

Примеры:

XML-название цвета Роль материала 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer или secondary
colorAccent secondary или tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Перенесите темную и светлую цветовые схемы из XML в их эквиваленты в Material 3 Compose.

Шаг 4: Перенос пользовательских фигур и типографики.

  • Если ваше приложение использует пользовательские фигуры:

    1. В коде Compose определите объект Shape , чтобы воспроизвести ваши XML-определения фигур.

    2. Передайте этот объект Shape в вашу MaterialTheme .

      Для получения более подробной информации см. раздел «Формы» .

  • Если ваше приложение использует собственную типографику:

    1. В коде Compose определите объект Typography , чтобы воспроизвести стили текста и определения шрифтов из XML-файла.

    2. Передайте этот объект Typography в вашу MaterialTheme .

      Более подробную информацию см. в разделе «Типографика» .

Сочинить роль 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

Шаг 5: Перенос стилей (styles.xml)

Система XML-стилей (styles.xml) определяет стили и внешний вид следующих элементов: 1. Виджетов, компонентов, тем для окон и диалоговых окон; 2. Типографики; 3. Тем и наложений; 4. Фигур.

XML-представления и компоненты объединяют несколько атрибутов для создания стиля. Они задают свои стили из файла styles.xml двумя разными способами: 1. Задавая "style="@style/..." напрямую и явно в XML-представлении; 2. Задавая стиль косвенно и неявно для компонента как часть более крупной темы (theme.xml).

В Compose нет прямого аналога для стилей — вместо этого стили передаются в качестве параметров компонуемым объектам, определенным в AppTheme, или путем создания многослойных, многократно используемых вариантов компонуемых объектов с определенным стилем.

Предоставьте отдельные функции `@Composable`, названные в соответствии со стилем и базовым компонентом, чтобы обозначить разницу в стиле и сценариях использования этих компонентов.

  • Правило: если XML-элемент использует собственный стиль (например, style="@style/MyPrimaryButton" ), не пытайтесь воспроизвести этот стиль непосредственно в коде. Вместо этого предложите создать отдельный составной элемент.
  • Пример:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Общие группы атрибутов: Если стиль задает общие модификаторы (например, отступы + высота), вынесите их в читаемое свойство расширения или в общую переменную Modifier.

Распространенные примеры

XML Сочинить
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) определен в 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 в ComponentDefaults.ComponentColors()
android:textColor contentColor в ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) или Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp в TextStyle

Шаг 6: Проверка миграции темы.

В Compose всегда используйте существующие значения темы из исходного XML-файла темы в качестве источника достоверной информации для новой темы Material. Никогда не придумывайте новые значения темы во время миграции, чтобы сохранить единообразие бренда и избежать визуальных регрессий.

Убедитесь, что все новые значения темы Compose соответствуют существующим значениям XML. Не задавайте жестко заданные значения, полученные в результате миграции.