Миграция с Материала 2 на Материал 3 в Compose

Material Design 3 — это следующая эволюция Material Design. Он включает обновленные темы, компоненты и функции персонализации Material You, такие как динамический цвет. Это обновление Material Design 2 , которое согласуется с новым визуальным стилем и системным пользовательским интерфейсом на Android 12 и выше.

В этом руководстве основное внимание уделяется переходу с библиотеки Compose Material (androidx.compose.material) Jetpack на библиотеку Compose Material 3 (androidx.compose.material3) Jetpack .

Примечание: В этом руководстве используется аббревиатура «M3» для обозначения взаимозаменяемых терминов: «Material 3», «Material Design 3», «Material You» и библиотеки Compose Material 3 (androidx.compose.material3) Jetpack. Аббревиатура «M2» используется для обозначения взаимозаменяемых терминов: «Material 2», «Material Design 2» и библиотеки Compose Material ( androidx.compose.material ) Jetpack.

Подходы

В общем случае не следует использовать M2 и M3 в одном приложении в долгосрочной перспективе . Это связано с тем, что две системы проектирования и соответствующие библиотеки существенно различаются с точки зрения их UX/UI-дизайна и реализаций Compose.

Ваше приложение может использовать систему дизайна, например, созданную с помощью Figma. В таких случаях мы также настоятельно рекомендуем вам или вашей команде дизайнеров перенести его с M2 на M3 перед началом миграции Compose. Не имеет смысла переносить приложение на M3, если его UX/UI-дизайн основан на M2.

Более того, ваш подход к миграции должен различаться в зависимости от размера, сложности и дизайна UX/UI вашего приложения. Это поможет вам минимизировать влияние на вашу кодовую базу. Вам следует использовать поэтапный подход к миграции.

Примечание: если вы запускаете новое приложение вместо того, чтобы переносить существующее приложение из M2 в M3, мы рекомендуем использовать M3 с самого начала.

Когда мигрировать

Вам следует начать миграцию как можно скорее. Однако важно учесть, находится ли ваше приложение в реалистичном положении для полной миграции с M2 на M3. Есть несколько сценариев блокировки , которые следует рассмотреть, прежде чем начать:

Сценарий	Рекомендуемый подход
Никаких блокировщиков	Начать поэтапную миграцию
Компонент из M2 пока недоступен в M3. См. раздел Компоненты и макеты ниже.	Начать поэтапную миграцию
Вы или ваша команда дизайнеров не перенесли систему дизайна приложения с M2 на M3.	Перенести систему проектирования с M2 на M3, затем начать поэтапную миграцию

Даже если вас затронули вышеперечисленные сценарии, вам следует использовать поэтапный подход к миграции, прежде чем фиксировать и выпускать обновление приложения. В этих случаях вы будете использовать M2 и M3 параллельно и постепенно отказываться от M2 при миграции на M3.

Поэтапный подход

Общие шаги поэтапной миграции следующие:

1. Добавьте зависимость M3 к зависимости M2.
2. Добавьте версию(и) M3 темы(ей) вашего приложения вместе с версией(ями) M2 темы(ей) вашего приложения.
3. Перенесите отдельные модули, экраны или компонуемые элементы в M3 в зависимости от размера и сложности вашего приложения (подробности см. в разделах ниже).
4. После полной миграции удалите версию(и) M2 темы(тем) вашего приложения.
5. Удалить зависимость от M2.

Зависимости

M3 имеет отдельный пакет и версию от M2:

М2

implementation "androidx.compose.material:material:$m2-version"

М3

implementation "androidx.compose.material3:material3:$m3-version"

Последние версии M3 смотрите на странице релизов Compose Material 3 .

Другие зависимости Material вне основных библиотек M2 и M3 не изменились. Они используют смесь пакетов и версий M2 и M3, но это не влияет на миграцию. Их можно использовать как есть с M3:

Библиотека	Упаковка и версия
Составьте иконки материалов	androidx.compose.material:material-icons-*:$m2-version
Составьте Материальную Пульсацию	androidx.compose.material:material-ripple:$m2-version

Экспериментальные API

Некоторые API M3 считаются экспериментальными. В таких случаях вам необходимо включить их на уровне функции или файла, используя аннотацию ExperimentalMaterial3Api :

import androidx.compose.material3.ExperimentalMaterial3Api

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppComposable() {
    // M3 composables
}

Тематика

В M2 и M3 компонуемая тема называется MaterialTheme , но пакеты импорта и параметры различаются:

М2

import androidx.compose.material.MaterialTheme

MaterialTheme(
    colors = AppColors,
    typography = AppTypography,
    shapes = AppShapes
) {
    // M2 content
}

М3

import androidx.compose.material3.MaterialTheme

MaterialTheme(
    colorScheme = AppColorScheme,
    typography = AppTypography,
    shapes = AppShapes
) {
    // M3 content
}

Примечание: параметры различаются для двух типов MaterialTheme . Это приводит к ошибкам после изменения. См. разделы Цвет , Типографика и Форма, чтобы узнать, как решить эту проблему.

Цвет

Рисунок 1. Цветовая система M2 (слева) и цветовая система M3 (справа).

Цветовая система в M3 существенно отличается от M2. Количество цветовых параметров увеличилось, они имеют другие названия и по-разному сопоставляются с компонентами M3. В Compose это относится к классу M2 Colors , классу M3 ColorScheme и связанным функциям:

М2

import androidx.compose.material.lightColors
import androidx.compose.material.darkColors

val AppLightColors = lightColors(
    // M2 light Color parameters
)
val AppDarkColors = darkColors(
    // M2 dark Color parameters
)
val AppColors = if (darkTheme) {
    AppDarkColors
} else {
    AppLightColors
}

М3

import androidx.compose.material3.lightColorScheme
import androidx.compose.material3.darkColorScheme

val AppLightColorScheme = lightColorScheme(
    // M3 light Color parameters
)
val AppDarkColorScheme = darkColorScheme(
    // M3 dark Color parameters
)
val AppColorScheme = if (darkTheme) {
    AppDarkColorScheme
} else {
    AppLightColorScheme
}

Учитывая существенные различия между цветовыми системами M2 и M3, нет разумного сопоставления для параметров Color . Вместо этого используйте инструмент Material Theme Builder для создания цветовой схемы M3. Используйте цвета M2 в качестве основных исходных цветов в инструменте, который инструмент расширяет в тональные палитры, используемые цветовой схемой M3. В качестве отправной точки рекомендуются следующие сопоставления:

М2	Конструктор тем Material
primary	Начальный
primaryVariant	Вторичный
secondary	Третичный
surface или background	Нейтральный

Примечание: Некоторые цвета M2 и M3 называются одинаково, например, первичный и вторичный. Однако их шестнадцатеричные коды могут не совпадать. Это связано с тем, что Material Theme Builder использует алгоритм для генерации тональных палитр из цветов M2, которые инструменты используют в цветовой схеме M3.

Рисунок 2. Цвета Jetchat M2, используемые в Material Theme Builder для создания цветовой схемы M3.

Вы можете скопировать значения шестнадцатеричного кода цвета для светлых и темных тем из инструмента и использовать их для реализации экземпляра M3 ColorScheme. В качестве альтернативы Material Theme Builder может экспортировать код Compose.

isLight

В отличие от класса M2 Colors , класс M3 ColorScheme не включает параметр isLight . В общем, вы должны попытаться смоделировать все, что нуждается в этой информации на уровне темы. Например:

М2

import androidx.compose.material.lightColors
import androidx.compose.material.darkColors
import androidx.compose.material.MaterialTheme

@Composable
private fun AppTheme(
  darkTheme: Boolean = isSystemInDarkTheme(),
  content: @Composable () -> Unit
) {
  val colors = if (darkTheme) darkColors(…) else lightColors(…)
  MaterialTheme(
      colors = colors,
      content = content
  )
}

@Composable
fun AppComposable() {
    AppTheme {
        val cardElevation = if (MaterialTheme.colors.isLight) 0.dp else 4.dp
        …
    }
}

М3

import androidx.compose.material3.lightColorScheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.MaterialTheme

val LocalCardElevation = staticCompositionLocalOf { Dp.Unspecified }
@Composable
private fun AppTheme(
   darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
   val cardElevation = if (darkTheme) 4.dp else 0.dp
    CompositionLocalProvider(LocalCardElevation provides cardElevation) {
        val colorScheme = if (darkTheme) darkColorScheme(…) else lightColorScheme(…)
        MaterialTheme(
            colorScheme = colorScheme,
            content = content
        )
    }
}

@Composable
fun AppComposable() {
    AppTheme {
        val cardElevation = LocalCardElevation.current
        …
    }
}

Более подробную информацию см. в руководстве «Системы пользовательского дизайна в Compose» .

Динамичный цвет

Новая функция в M3 — динамический цвет . Вместо использования пользовательских цветов, M3 ColorScheme может использовать цвета обоев устройства на Android 12 и выше, используя следующие функции:

• dynamicLightColorScheme
• dynamicDarkColorScheme

Примечание: даже если вы решите использовать динамическую цветовую схему, вам почти всегда понадобится резервная пользовательская цветовая схема, учитывая ограничение Android 12 и выше. См. Jetchat в качестве примера.

Типографика

Рисунок 3. Система типографики M3 (слева) и система типографики M2 (справа)

Система типографики в M3 отличается от M2. Количество параметров типографики примерно одинаково, но у них разные названия и они по-разному отображаются в компонентах M3. В Compose это относится к классу M2 Typography и классу M3 Typography :

М2

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

М3

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

В качестве отправной точки рекомендуются следующие сопоставления параметров TextStyle :

М2	М3
h1	displayLarge
h2	displayMedium
h3	displaySmall
Н/Д	headlineLarge
h4	headlineMedium
h5	headlineSmall
h6	titleLarge
subtitle1	titleMedium
subtitle2	titleSmall
body1	bodyLarge
body2	bodyMedium
caption	bodySmall
button	labelLarge
Н/Д	labelMedium
overline	labelSmall

Примечание: В отличие от класса M2 Typography , класс M3 Typography в настоящее время не включает параметр defaultFontFamily . Вместо этого вам нужно будет использовать параметр fontFamily в каждом из отдельных TextStyles .

Форма

Рисунок 4. Система формы М2 (слева) против системы формы М3 (справа)

Система фигур в M3 отличается от M2. Количество параметров фигур увеличилось, они называются по-другому и по-другому отображаются в компонентах M3. В Compose это относится к классу M2 Shapes и классу M3 Shapes :

М2

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

М3

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

В качестве отправной точки рекомендуются следующие сопоставления параметров Shape :

М2	М3
Н/Д	extraSmall
small	small
medium	medium
large	large
Н/Д	extraLarge

Примечание: Система фигур M3 также определяет стили none и full , которые являются константами и не являются частью класса Shapes . Для них используйте RectangleShape и CircleShape соответственно.

Компоненты и макеты

Большинство компонентов и макетов из M2 доступны в M3. Однако есть некоторые отсутствующие, а также новые, которых не было в M2. Кроме того, некоторые компоненты M3 имеют больше вариаций, чем их эквиваленты в M2. В целом поверхности API M3 пытаются быть максимально похожими на свои ближайшие эквиваленты в M2.

Учитывая обновленные системы цвета, типографики и формы, компоненты M3 имеют тенденцию по-разному сопоставляться с новыми значениями тем. Хорошей идеей будет проверить каталог токенов в исходном коде Compose Material 3 как источник истины для этих сопоставлений.

Хотя некоторые компоненты требуют особого внимания, в качестве отправной точки рекомендуются следующие сопоставления функций:

Отсутствующие API :

М2	М3
androidx.compose.material.swipeable	Пока недоступно

Замененные API :

М2	М3
androidx.compose.material.BackdropScaffold	Нет эквивалента M3, вместо этого перейдите на Scaffold или BottomSheetScaffold
androidx.compose.material.BottomDrawer	Нет эквивалента M3, вместо этого перейдите на ModalBottomSheet

Переименованные API :

М2	М3
androidx.compose.material.BottomNavigation	androidx.compose.material3.NavigationBar
androidx.compose.material.BottomNavigationItem	androidx.compose.material3.NavigationBarItem
androidx.compose.material.Chip	androidx.compose.material3.AssistChip или androidx.compose.material3.SuggestionChip
androidx.compose.material.ModalBottomSheetLayout	androidx.compose.material3.ModalBottomSheet
androidx.compose.material.ModalDrawer	androidx.compose.material3.ModalNavigationDrawer

Все остальные API :

М2	М3
androidx.compose.material.AlertDialog	androidx.compose.material3.AlertDialog
androidx.compose.material.Badge	androidx.compose.material3.Badge
androidx.compose.material.BadgedBox	androidx.compose.material3.BadgedBox
androidx.compose.material.BottomAppBar	androidx.compose.material3.BottomAppBar
androidx.compose.material.BottomSheetScaffold	androidx.compose.material3.BottomSheetScaffold
androidx.compose.material.Button	androidx.compose.material3.Button
androidx.compose.material.Card	androidx.compose.material3.Card
androidx.compose.material.Checkbox	androidx.compose.material3.Checkbox
androidx.compose.material.CircularProgressIndicator	androidx.compose.material3.CircularProgressIndicator
androidx.compose.material.Divider	androidx.compose.material3.Divider
androidx.compose.material.DropdownMenu	androidx.compose.material3.DropdownMenu
androidx.compose.material.DropdownMenuItem	androidx.compose.material3.DropdownMenuItem
androidx.compose.material.ExposedDropdownMenuBox	androidx.compose.material3.ExposedDropdownMenuBox
androidx.compose.material.ExtendedFloatingActionButton	androidx.compose.material3.ExtendedFloatingActionButton
androidx.compose.material.FilterChip	androidx.compose.material3.FilterChip
androidx.compose.material.FloatingActionButton	androidx.compose.material3.FloatingActionButton
androidx.compose.material.Icon	androidx.compose.material3.Icon
androidx.compose.material.IconButton	androidx.compose.material3.IconButton
androidx.compose.material.IconToggleButton	androidx.compose.material3.IconToggleButton
androidx.compose.material.LeadingIconTab	androidx.compose.material3.LeadingIconTab
androidx.compose.material.LinearProgressIndicator	androidx.compose.material3.LinearProgressIndicator
androidx.compose.material.ListItem	androidx.compose.material3.ListItem
androidx.compose.material.NavigationRail	androidx.compose.material3.NavigationRail
androidx.compose.material.NavigationRailItem	androidx.compose.material3.NavigationRailItem
androidx.compose.material.OutlinedButton	androidx.compose.material3.OutlinedButton
androidx.compose.material.OutlinedTextField	androidx.compose.material3.OutlinedTextField
androidx.compose.material.RadioButton	androidx.compose.material3.RadioButton
androidx.compose.material.RangeSlider	androidx.compose.material3.RangeSlider
androidx.compose.material.Scaffold	androidx.compose.material3.Scaffold
androidx.compose.material.ScrollableTabRow	androidx.compose.material3.ScrollableTabRow
androidx.compose.material.Slider	androidx.compose.material3.Slider
androidx.compose.material.Snackbar	androidx.compose.material3.Snackbar
androidx.compose.material.Switch	androidx.compose.material3.Switch
androidx.compose.material.Tab	androidx.compose.material3.Tab
androidx.compose.material.TabRow	androidx.compose.material3.TabRow
androidx.compose.material.Text	androidx.compose.material3.Text
androidx.compose.material.TextButton	androidx.compose.material3.TextButton
androidx.compose.material.TextField	androidx.compose.material3.TextField
androidx.compose.material.TopAppBar	androidx.compose.material3.TopAppBar
androidx.compose.material.TriStateCheckbox	androidx.compose.material3.TriStateCheckbox

Ознакомьтесь с новейшими компонентами и макетами M3 в справочном обзоре API Compose Material 3 и следите за страницей релизов для получения информации о новых и обновленных API.

Подмости, бары и навигационный ящик

Рисунок 5. Леса M2 с барной стойкой и навигационным ящиком (слева) по сравнению с лесами M3 с барной стойкой и навигационным ящиком (справа).

Scaffold в M3 отличается от M2. И в M2, и в M3 основной компоновочный макет называется Scaffold , но пакеты импорта и параметры различаются:

М2

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

М3

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

В M2 Scaffold содержится параметр backgroundColor , который теперь называется containerColor в M3 Scaffold :

М2

import androidx.compose.material.Scaffold

Scaffold(
    backgroundColor = …,
    content = { … }
)

М3

import androidx.compose.material3.Scaffold

Scaffold(
    containerColor = …,
    content = { … }
)

Класс M2 ScaffoldState больше не существует в M3, поскольку он содержит параметр drawerState , который больше не нужен. Чтобы показать снэкбары с помощью M3 Scaffold , используйте вместо этого SnackbarHostState :

М2

import androidx.compose.material.Scaffold
import androidx.compose.material.rememberScaffoldState

val scaffoldState = rememberScaffoldState()
val scope = rememberCoroutineScope()

Scaffold(
    scaffoldState = scaffoldState,
    content = {
        …
        scope.launch {
            scaffoldState.snackbarHostState.showSnackbar(…)
        }
    }
)

М3

import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState

val snackbarHostState = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()

Scaffold(
    snackbarHost = { SnackbarHost(snackbarHostState) },
    content = {
        …
        scope.launch {
            snackbarHostState.showSnackbar(…)
        }
    }
)

Примечание: Класс SnackbarData в M2 был разделен на SnackbarData и SnackbarVisuals в M3.

Все параметры drawer* из M2 Scaffold были удалены из M3 Scaffold . К ним относятся такие параметры, как drawerShape и drawerContent . Чтобы показать drawer с M3 Scaffold , используйте компонуемый навигационный drawer, например ModalNavigationDrawer , вместо этого:

М2

import androidx.compose.material.DrawerValue
import
import androidx.compose.material.Scaffold
import androidx.compose.material.rememberDrawerState
import androidx.compose.material.rememberScaffoldState

val scaffoldState = rememberScaffoldState(
    drawerState = rememberDrawerState(DrawerValue.Closed)
)
val scope = rememberCoroutineScope()

Scaffold(
    scaffoldState = scaffoldState,
    drawerContent = { … },
    drawerGesturesEnabled = …,
    drawerShape = …,
    drawerElevation = …,
    drawerBackgroundColor = …,
    drawerContentColor = …,
    drawerScrimColor = …,
    content = {
        …
        scope.launch {
            scaffoldState.drawerState.open()
        }
    }
)

М3

import androidx.compose.material3.DrawerValue
import androidx.compose.material3.ModalDrawerSheet
import androidx.compose.material3.ModalNavigationDrawer
import androidx.compose.material3.Scaffold
import androidx.compose.material3.rememberDrawerState

val drawerState = rememberDrawerState(DrawerValue.Closed)
val scope = rememberCoroutineScope()

ModalNavigationDrawer(
    drawerState = drawerState,
    drawerContent = {
        ModalDrawerSheet(
            drawerShape = …,
            drawerTonalElevation = …,
            drawerContainerColor = …,
            drawerContentColor = …,
            content = { … }
        )
    },
    gesturesEnabled = …,
    scrimColor = …,
    content = {
        Scaffold(
            content = {
                …
                scope.launch {
                    drawerState.open()
                }
            }
        )
    }
)

Верхняя панель приложений

Рисунок 6. Схема M2 с верхней панелью приложений и прокручиваемым списком (слева) по сравнению с схемой M3 с верхней панелью приложений и прокручиваемым списком (справа)

Верхние панели приложений в M3 отличаются от панелей в M2. И в M2, и в M3 главная верхняя панель приложений, которая может быть составлена, называется TopAppBar но пакеты импорта и параметры различаются:

М2

import androidx.compose.material.TopAppBar

TopAppBar(…)

М3

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Рассмотрите возможность использования M3 CenterAlignedTopAppBar , если ранее вы центрировали содержимое в M2 TopAppBar . Также полезно знать о MediumTopAppBar и LargeTopAppBar .

M3 top app bars содержит новый параметр scrollBehavior для предоставления различных функций при прокрутке через класс TopAppBarScrollBehavior , например, изменение высоты. Это работает в сочетании с прокруткой содержимого через Modifer.nestedScroll . Это было возможно в M2 TopAppBar путем ручного изменения параметра elevation :

М2

import androidx.compose.material.AppBarDefaults
import androidx.compose.material.Scaffold
import androidx.compose.material.TopAppBar

val state = rememberLazyListState()
val isAtTop by remember {
    derivedStateOf {
        state.firstVisibleItemIndex == 0 && state.firstVisibleItemScrollOffset == 0
    }
}

Scaffold(
    topBar = {
        TopAppBar(
            elevation = if (isAtTop) {
                0.dp
            } else {
                AppBarDefaults.TopAppBarElevation
            },
            …
        )
    },
    content = {
        LazyColumn(state = state) { … }
    }
)

М3

import androidx.compose.material3.Scaffold
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults

val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()

Scaffold(
    modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
    topBar = {
        TopAppBar(
            scrollBehavior = scrollBehavior,
            …
        )
    },
    content = {
        LazyColumn { … }
    }
)

Нижняя навигация / Панель навигации

Рисунок 7. Нижняя панель навигации M2 (слева) и панель навигации M3 (справа).

Нижняя навигация в M2 была переименована в навигационную панель в M3. В M2 есть BottomNavigation и BottomNavigationItem , а в M3 есть NavigationBar и NavigationBarItem :

М2

import androidx.compose.material.BottomNavigation
import androidx.compose.material.BottomNavigationItem

BottomNavigation {
    BottomNavigationItem(…)
    BottomNavigationItem(…)
    BottomNavigationItem(…)
}

М3

import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem

NavigationBar {
    NavigationBarItem(…)
    NavigationBarItem(…)
    NavigationBarItem(…)
}

Кнопки, кнопки-иконки и FAB

Рисунок 8. Кнопки M2 (слева) и кнопки M3 (справа)

Кнопки, кнопки-значки и плавающие кнопки действий (FAB) в M3 отличаются от кнопок в M2. M3 включает в себя все компонуемые кнопки M2:

М2

import androidx.compose.material.Button
import androidx.compose.material.ExtendedFloatingActionButton
import androidx.compose.material.FloatingActionButton
import androidx.compose.material.IconButton
import androidx.compose.material.IconToggleButton
import androidx.compose.material.OutlinedButton
import androidx.compose.material.TextButton

// M2 buttons
Button(…)
OutlinedButton(…)
TextButton(…)
// M2 icon buttons
IconButton(…)
IconToggleButton(…)
// M2 FABs
FloatingActionButton(…)
ExtendedFloatingActionButton(…)

М3

import androidx.compose.material3.Button
import androidx.compose.material3.ExtendedFloatingActionButton
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.IconButton
import androidx.compose.material3.IconToggleButton
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.TextButton

// M3 buttons
Button(…)
OutlinedButton(…)
TextButton(…)
// M3 icon buttons
IconButton(…)
IconToggleButton(…)
// M3 FABs
FloatingActionButton(…)
ExtendedFloatingActionButton(…)

M3 также включает новые варианты кнопок. Ознакомьтесь с ними в обзоре справки API Compose Material 3 .

Выключатель

Рисунок 9. Переключатель M2 (слева) и переключатель M3 (справа).

Switch в M3 отличается от M2. В M2 и M3 составной switch называется Switch , но пакеты импорта различаются:

М2

import androidx.compose.material.Switch

Switch(…)

М3

import androidx.compose.material3.Switch

Switch(…)

Поверхности и высоты

Рисунок 10. Высота поверхности M2 по сравнению с высотой поверхности M3 в светлой теме (слева) и темной теме (справа).

Системы поверхности и высот в M3 отличаются от M2. В M3 есть два типа высот:

• Высота тени (отбрасывает тень, как и M2)
• Тональное возвышение (накладывает цвет, новое в M3)

В Compose это применяется к функции M2 Surface и функции M3 Surface :

М2

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

М3

import androidx.compose.material3.Surface

Surface(
    shadowElevation = …,
    tonalElevation = …
) { … }

Вы можете использовать значения elevation Dp в M2 как для shadowElevation , так и/или tonalElevation в M3, в зависимости от предпочтений дизайна UX/UI. Surface — это подложка, компонуемая за большинством компонентов, поэтому компонуемые компоненты также могут раскрывать параметры высоты, которые вы должны переносить таким же образом.

Примечание: Цвет по умолчанию, используемый tonalElevation в M3, — primary . Вы можете переопределить его с помощью параметра surfaceTint в классе ColorScheme .

Тональное возвышение в M3 заменяет концепцию возвышенных наложений в темных темах M2. В результате ElevationOverlay и LocalElevationOverlay отсутствуют в M3, а LocalAbsoluteElevation в M2 изменилось на LocalAbsoluteTonalElevation в M3.

Акцент и содержание альфа

Рисунок 11. Значок M2 и выделение текста (слева) по сравнению со значком M3 и выделением текста (справа)

Выделение в M3 существенно отличается от M2. В M2 выделение включало использование цветов с определенными альфа-значениями для дифференциации контента, такого как текст и значки. В M3 теперь есть несколько разных подходов:

• Использование цветов наряду с их вариантами цветов из расширенной цветовой системы M3.
• Использование шрифтов разной толщины для текста.

В результате ContentAlpha и LocalContentAlpha отсутствуют в M3 и их необходимо заменить.

Примечание: для отключенных состояний в M3 все еще допустимо использование цветов с альфа-значениями, как в M2. Для получения дополнительной информации см. Роли цветов .

В качестве отправной точки рекомендуются следующие сопоставления:

М2	М3
onSurface с ContentAlpha.high	onSurface в целом, FontWeight.Medium - FontWeight.Black для текста
onSurface с ContentAlpha.medium	onSurfaceVariant в общем, FontWeight.Thin - FontWeight.Normal для текста
onSurface с ContentAlpha.disabled	onSurface.copy(alpha = 0.38f)

Вот пример акцента на иконках в M2 и M3:

М2

import androidx.compose.material.ContentAlpha
import androidx.compose.material.LocalContentAlpha

// High emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.high) {
    Icon(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.medium) {
    Icon(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.disabled) {
    Icon(…)
}

М3

import androidx.compose.material3.LocalContentColor

// High emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface) {
    Icon(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurfaceVariant) {
    Icon(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)) {
    Icon(…)
}

Вот примеры выделения текста в М2 и М3:

М2

import androidx.compose.material.ContentAlpha
import androidx.compose.material.LocalContentAlpha

// High emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.high) {
    Text(…)
}
// Medium emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.medium) {
    Text(…)
}
// Disabled emphasis
CompositionLocalProvider(LocalContentAlpha provides ContentAlpha.disabled) {
    Text(…)
}

М3

import androidx.compose.material3.LocalContentColor

// High emphasis
Text(
    …,
    fontWeight = FontWeight.Bold
)
// Medium emphasis
Text(
    …,
    fontWeight = FontWeight.Normal
)
// Disabled emphasis
CompositionLocalProvider(LocalContentColor provides MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)) {
    Text(
        …,
        fontWeight = FontWeight.Normal
    )
}

Фоны и контейнеры

Фоны в M2 называются контейнерами в M3. В общем случае вы можете заменить параметры background* в M2 на container* в M3, используя те же значения. Например:

М2

Badge(
    backgroundColor = MaterialTheme.colors.primary
) { … }

М3

Badge(
    containerColor = MaterialTheme.colorScheme.primary
) { … }

Полезные ссылки

Чтобы узнать больше о переходе с M2 на M3 в Compose, ознакомьтесь со следующими дополнительными ресурсами.

Документы

• Material Design 3 в Compose

Примеры приложений

• Ответить M3 пример приложения
• Пример приложения Jetchat для миграции с M2 на M3
  • Первоначальная миграция alpha01
  • Последующее обновление alpha10
• Пример приложения Jetnews для миграции с M2 на M3
• Теперь в приложении Android M3 hero: модуль core-designsystem

Видео

• Реализация материала, который вы используете Jetpack Compose

Справочник API и исходный код

• Ссылка на API Compose Material 3
• Образцы Compose Material 3 в исходном коде

{% дословно %} {% endverbatim %}