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 .
Подходы
Как правило , не следует использовать M2 и M3 в одном приложении в долгосрочной перспективе . Это связано с тем, что эти две системы дизайна и соответствующие им библиотеки существенно различаются с точки зрения UX/UI-дизайна и реализации Compose.
Ваше приложение может использовать дизайн-систему, например, разработанную на Figma. В таких случаях мы настоятельно рекомендуем вам или вашей команде дизайнеров перенести его из M2 в M3 перед началом миграции Compose. Не имеет смысла переносить приложение в M3, если его UX/UI-дизайн основан на M2.
Более того, ваш подход к миграции должен различаться в зависимости от размера, сложности и UX/UI-дизайна вашего приложения. Это поможет минимизировать влияние на вашу кодовую базу. Миграцию следует проводить поэтапно.
Когда мигрировать
Миграцию следует начать как можно скорее. Однако важно оценить, насколько реалистично ваше приложение для полного перехода с M2 на M3. Перед началом работы следует изучить несколько сценариев блокировки :
| Сценарий | Рекомендуемый подход |
|---|---|
| Никаких блокировщиков | Начать поэтапную миграцию |
| Компонент из M2 пока недоступен в M3. См. раздел «Компоненты и макеты» ниже. | Начать поэтапную миграцию |
| Вы или ваша команда дизайнеров не перенесли систему дизайна приложения с M2 на M3. | Перенести систему проектирования с M2 на M3, затем начать поэтапную миграцию |
Даже если вас коснулись вышеперечисленные сценарии, вам следует использовать поэтапный подход к миграции, прежде чем коммитить и выпустить обновление приложения. В таких случаях следует использовать M2 и M3 параллельно, постепенно отказываясь от M2 и переходя на M3.
Поэтапный подход
Общие шаги поэтапной миграции следующие:
- Добавьте зависимость M3 к зависимости M2.
- Добавьте версию(и) M3 темы(й) вашего приложения вместе с версией(ями) M2 темы(й) вашего приложения.
- Перенесите отдельные модули, экраны или компонуемые элементы в M3 в зависимости от размера и сложности вашего приложения (подробности см. в разделах ниже).
- После полной миграции удалите версию(и) M2 темы(тем) вашего приложения.
- Удалить зависимость от 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:
| Библиотека | Пакет и версия |
|---|---|
| Иконки Compose Material | 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
}
Цвет
Цветовая система в 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 | Нейтральный |
Вы можете скопировать шестнадцатеричные значения кодов цветов для светлой и тёмной тем из инструмента и использовать их для реализации экземпляра 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 — динамический цвет . Вместо использования пользовательских цветов, ColorScheme M3 может использовать цвета обоев устройства на Android 12 и выше, используя следующие функции:
Типографика
Система типографики в 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 |
Форма
Система фигур в 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 |
Компоненты и макеты
Большинство компонентов и макетов из 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 :
Все остальные API :
Ознакомьтесь с последними компонентами и макетами M3 в справочном обзоре API Compose Material 3 и следите за страницей релизов для получения новых и обновленных API.
Подмости, бары и навигационный ящик
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 , который теперь в M3 Scaffold называется containerColor :
М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(…)
}
}
)
Все параметры 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()
}
}
)
}
)
Верхняя панель приложений
Верхние панели приложений в M3 отличаются от панелей приложений в M2. И в M2, и в M3 основная компонуемая верхняя панель приложений называется TopAppBar , но пакеты импорта и параметры различаются:
М2
import androidx.compose.material.TopAppBar
TopAppBar(…)
М3
import androidx.compose.material3.TopAppBar
TopAppBar(…)
Если вы ранее центрировали контент в M2 TopAppBar , рассмотрите возможность использования M3 CenterAlignedTopAppBar . Также полезно знать о MediumTopAppBar и LargeTopAppBar .
Верхние панели приложений M3 содержат новый параметр scrollBehavior , который обеспечивает различные функции при прокрутке с помощью класса TopAppBarScrollBehavior , например, изменение высоты. Это работает совместно с прокруткой содержимого с помощью Modifer.nestedScroll . В TopAppBar M2 это было возможно путем ручного изменения параметра 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 { … }
}
)
Нижняя навигация / Панель навигации
Нижняя панель навигации в 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
Кнопки, кнопки-значки и плавающие кнопки действий (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 .
Выключатель
Switch в M3 отличается от M2. В M2 и M3 составной элемент switch называется Switch , но пакеты импорта различаются:
М2
import androidx.compose.material.Switch
Switch(…)
М3
import androidx.compose.material3.Switch
Switch(…)
Поверхности и высоты
Системы рельефа и поверхности в M3 отличаются от M2. В M3 существует два типа рельефа:
- Высота тени (отбрасывает тень, как и М2)
- Тональное возвышение (наложение цвета, новое в M3)
В Compose это применяется к функции M2 Surface и функции M3 Surface :
М2
import androidx.compose.material.Surface
Surface(
elevation = …
) { … }
М3
import androidx.compose.material3.Surface
Surface(
shadowElevation = …,
tonalElevation = …
) { … }
Вы можете использовать значения Dp elevation в M2 как для shadowElevation , так и для tonalElevation в M3, в зависимости от предпочтений в дизайне UX/UI. Surface — это базовый компонуемый компонент, лежащий в основе большинства компонентов, поэтому компонуемые компоненты также могут предоставлять параметры высоты, которые необходимо переносить аналогичным образом.
Тональное возвышение в M3 заменяет концепцию наложений возвышений в тёмных темах M2. В результате ElevationOverlay и LocalElevationOverlay отсутствуют в M3, а LocalAbsoluteElevation в M2 заменено на LocalAbsoluteTonalElevation в M3.
Акцент и содержание альфа
Акцент в M3 существенно отличается от M2. В M2 акцент подразумевал использование цветов с определёнными значениями альфа для дифференциации контента, например текста и значков. В M3 теперь существует несколько различных подходов:
- Использование цветов наряду с их вариантами цветов из расширенной цветовой системы M3.
- Использование шрифтов разной насыщенности для текста.
В результате ContentAlpha и LocalContentAlpha отсутствуют в M3 и должны быть заменены.
В качестве отправной точки рекомендуются следующие сопоставления:
| М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, ознакомьтесь со следующими дополнительными ресурсами.
Документы
Примеры приложений
- Ответить Пример приложения M3
- Миграция примера приложения Jetchat с M2 на M3
- Пример приложения Jetnews для миграции с M2 на M3
- Теперь в приложении Android M3 hero: модуль core-designsystem
Видео
Справочник API и исходный код
{% дословно %}Рекомендовано для вас
- Примечание: текст ссылки отображается, когда JavaScript отключен.
- Material Design 2 в Compose
- Material Design 3 в Compose
- Системы индивидуального дизайна в Compose