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. Прежде чем приступить к работе, следует изучить некоторые сценарии блокирования :
| Сценарий | Рекомендуемый подход |
|---|---|
| Нет блокировщиков | Начать поэтапную миграцию |
| Компонент из М2 пока недоступен в М3. См. раздел «Компоненты и макеты» ниже. | Начать поэтапную миграцию |
| Вы или ваша команда дизайнеров не перенесли систему дизайна приложения с 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 .
Другие зависимости материалов за пределами основных библиотек 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
}
Цвет
Цветовая система в М3 существенно отличается от М2. Количество цветовых параметров увеличилось, они имеют другие названия и по-разному сопоставляются с компонентами 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 | Конструктор тем материалов |
|---|---|
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 является динамический цвет . Вместо использования пользовательских цветов M3 ColorScheme может использовать цвета обоев устройства на Android 12 и более поздних версиях, используя следующие функции:
Типография
Система типографики в M3 отличается от M2. Количество параметров оформления примерно одинаковое, но они имеют разные имена и по-разному сопоставляются с компонентами M3. В Compose это относится к классу Typography M2 и классу Typography M3:
М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 это относится к классу « Shapes M2» и классу « Shapes M3»:
М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 имеют тенденцию по-разному отображаться в соответствии с новыми значениями тем. Рекомендуется проверить каталог tokens в исходном коде 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 на странице выпусков .
Подмости, закусочные и навигационный ящик
Леса в 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
)
Scaffold M2 содержит параметр backgroundColor , который теперь containerColor в Scaffold M3:
М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* из Scaffold M2 были удалены из Scaffold M3. К ним относятся такие параметры, как drawerShape и drawerContent . Чтобы отобразить ящик с помощью M3 Scaffold , используйте вместо этого составной ящик навигации, например 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(…)
Рассмотрите возможность использования M3 CenterAlignedTopAppBar если вы ранее центрировали контент внутри M2 TopAppBar . Также полезно знать о 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 .
Выключатель
Переключатель в М3 отличается от М2. И в M2, и в M3 компонуемый переключатель называется Switch , но пакеты импорта различаются:
М2
import androidx.compose.material.Switch
Switch(…)
М3
import androidx.compose.material3.Switch
Switch(…)
Поверхности и высота
Системы поверхности и высот в 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 = …
) { … }
Вы можете использовать значения Dp elevation в M2 как shadowElevation , так и для tonalElevation в M3, в зависимости от предпочтений дизайна UX/UI. Surface — это составляющая основа большинства компонентов, поэтому компонуемые компоненты могут также предоставлять параметры высоты, которые необходимо перенести таким же образом.
Тональное возвышение в M3 заменяет концепцию наложения возвышений в темных темах M2. В результате ElevationOverlay и LocalElevationOverlay не существуют в M3, а LocalAbsoluteElevation в M2 изменилась на LocalAbsoluteTonalElevation в M3.
Акцент и содержание альфа
Акцент в М3 существенно отличается от М2. В 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(…)
}
Вот примеры выделения текста в M2 и M3:
М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
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. Прежде чем приступить к работе, следует изучить некоторые сценарии блокирования :
| Сценарий | Рекомендуемый подход |
|---|---|
| Нет блокировщиков | Начать поэтапную миграцию |
| Компонент из М2 пока недоступен в М3. См. раздел «Компоненты и макеты» ниже. | Начать поэтапную миграцию |
| Вы или ваша команда дизайнеров не перенесли систему дизайна приложения с 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 .
Другие зависимости материалов за пределами основных библиотек 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
}
Цвет
Цветовая система в М3 существенно отличается от М2. Количество цветовых параметров увеличилось, они имеют другие названия и по-разному сопоставляются с компонентами 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 | Конструктор тем материалов |
|---|---|
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 это относится к классу Typography M2 и классу Typography M3:
М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 это относится к классу « Shapes M2» и классу « Shapes M3»:
М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 имеют тенденцию по-разному отображаться в соответствии с новыми значениями тем. Рекомендуется проверить каталог tokens в исходном коде 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 на странице выпусков .
Подмости, закусочные и навигационный ящик
Леса в 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
)
Scaffold M2 содержит параметр backgroundColor , который теперь containerColor в Scaffold M3:
М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* из Scaffold M2 были удалены из Scaffold M3. К ним относятся такие параметры, как drawerShape и drawerContent . Чтобы отобразить ящик с помощью M3 Scaffold , используйте вместо этого составной ящик навигации, например 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(…)
Рассмотрите возможность использования M3 CenterAlignedTopAppBar если вы ранее центрировали контент внутри M2 TopAppBar . Также полезно знать о 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 .
Выключатель
Переключатель в М3 отличается от М2. И в M2, и в M3 компонуемый переключатель называется Switch , но пакеты импорта различаются:
М2
import androidx.compose.material.Switch
Switch(…)
М3
import androidx.compose.material3.Switch
Switch(…)
Поверхности и высота
Системы поверхности и высот в 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 = …
) { … }
Вы можете использовать значения Dp elevation в M2 как shadowElevation , так и для tonalElevation в M3, в зависимости от предпочтений дизайна UX/UI. Surface является составной основой большинства компонентов, поэтому составные компоненты могут также предоставлять параметры высоты, которые необходимо перенести таким же образом.
Тональное возвышение в M3 заменяет концепцию наложения возвышений в темных темах M2. В результате ElevationOverlay и LocalElevationOverlay не существуют в M3, а LocalAbsoluteElevation в M2 изменилась на LocalAbsoluteTonalElevation в M3.
Акцент и содержание альфа
Акцент в М3 существенно отличается от М2. В 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(…)
}
Вот примеры выделения текста в M2 и M3:
М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
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. Прежде чем приступить к работе, следует изучить некоторые сценарии блокирования :
| Сценарий | Рекомендуемый подход |
|---|---|
| Нет блокировщиков | Начать поэтапную миграцию |
| Компонент из М2 пока недоступен в М3. См. раздел «Компоненты и макеты» ниже. | Начать поэтапную миграцию |
| Вы или ваша команда дизайнеров не перенесли систему дизайна приложения с 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"
M3
implementation "androidx.compose.material3:material3:$m3-version"
См. Последние версии M3 на странице Compose Material 3 .
Другие материальные зависимости за пределами основных библиотек 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
}
M3
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
}
M3
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 . Вместо этого используйте инструмент «Строитель темы» для создания цветовой схемы M3. Используйте цвета M2 в качестве основных цветов источника в инструменте, которые инструмент расширяется в тональные палитры, используемые цветной схемой M3. В качестве отправной точки рекомендуется следующие сопоставления:
| М2 | Материальная тема Строитель |
|---|---|
primary | Начальный |
primaryVariant | Второстепенный |
secondary | Третичный |
surface или background | Нейтральный |
Вы можете скопировать значения цветного шестигранного кода для световых и темных тем инструмента и использовать их для реализации экземпляра M3 Colorscheme. В качестве альтернативы, строитель материалов может экспортировать код композиции.
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
…
}
}
M3
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
…
}
}
См. Руководство по индивидуальному проектированию в руководстве для получения дополнительной информации.
Динамичный цвет
Новая функция в M3 - динамический цвет . Вместо использования пользовательских цветов M3 ColorScheme может использовать цвета обоев на Android 12 и выше, используя следующие функции:
Типография
Система типографии в M3 отличается от M2. Количество параметров типографии примерно одинаково, но у них разные имена, и они по -разному отображаются с компонентами M3. В Compose это относится к классу Typography M2 и классу Typography M3:
М2
import androidx.compose.material.Typography
val AppTypography = Typography(
// M2 TextStyle parameters
)
M3
import androidx.compose.material3.Typography
val AppTypography = Typography(
// M3 TextStyle parameters
)
Следующие отображения параметров TextStyle рекомендуются в качестве отправной точки:
| М2 | M3 |
|---|---|
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 это относится к классу Shapes M2 и классе M3 Shapes :
М2
import androidx.compose.material.Shapes
val AppShapes = Shapes(
// M2 Shape parameters
)
M3
import androidx.compose.material3.Shapes
val AppShapes = Shapes(
// M3 Shape parameters
)
Следующие отображения параметров Shape рекомендуются в качестве отправной точки:
| М2 | M3 |
|---|---|
| Н/Д | extraSmall |
small | small |
medium | medium |
large | large |
| Н/Д | extraLarge |
Компоненты и макеты
Большинство компонентов и макетов от M2 доступны в M3. Однако в M2 не хватает того, что не хватает, а также новые, которых не было. Кроме того, некоторые компоненты M3 имеют больше вариаций, чем их эквиваленты в M2. В целом поверхности API M3 пытаются быть как можно более похожими с их самыми близкими эквивалентами в M2.
Учитывая обновленные системы цвета, типографии и формы, компоненты M3 имеют тенденцию по -разному отображать новые тематические значения. Это хорошая идея, чтобы проверить каталог Tokens в исходном коде Compose Material 3 как источник истины для этих отображений.
В то время как некоторые компоненты требуют особых соображений, в качестве отправной точки рекомендуются следующие отображения функций:
Отсутствует API :
| М2 | M3 |
|---|---|
androidx.compose.material.swipeable | Еще недоступен |
Заменил API :
| М2 | M3 |
|---|---|
androidx.compose.material.BackdropScaffold | Нет M3, эквивалентный, не переноситесь на Scaffold или BottomSheetScaffold |
androidx.compose.material.BottomDrawer | Нет M3 эквивалент, вместо этого перейдите в ModalBottomSheet |
Переименованные в API :
Все остальные API :
См. Последние компоненты M3 и макеты на компоновке Material 3 API -ссылка , и следите за страницей выпусков для новых и обновленных API.
Скафолд, закуски и навигационное ящик
Скафолд в M3 отличается от M2. Как в M2, так и в M3 основная композиция макета называется Scaffold , но пакеты импорта и параметры различаются:
М2
import androidx.compose.material.Scaffold
Scaffold(
// M2 scaffold parameters
)
M3
import androidx.compose.material3.Scaffold
Scaffold(
// M3 scaffold parameters
)
Scaffold M2 содержит параметр backgroundColor , теперь назван для containerColor в Scaffold M3:
М2
import androidx.compose.material.Scaffold
Scaffold(
backgroundColor = …,
content = { … }
)
M3
import androidx.compose.material3.Scaffold
Scaffold(
containerColor = …,
content = { … }
)
Класс M2 ScaffoldState больше не существует в M3, поскольку он содержит параметр drawerState , который больше не нужен. Чтобы показать закуски с Scaffold M3, вместо этого используйте 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(…)
}
}
)
M3
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* из Scaffold M2 были удалены из Scaffold M3. Они включают в себя такие параметры, как drawerShape и drawerContent . Чтобы показать ящик с Scaffold M3, используйте навигационный ящик для композиции, такой как 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()
}
}
)
M3
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()
}
}
)
}
)
Top App Bar
Лучшие приложения в M3 отличаются от таковых в M2. Как в M2, так и в M3 основная топ -стержня приложения называется TopAppBar , но пакеты импорта и параметры различаются:
М2
import androidx.compose.material.TopAppBar
TopAppBar(…)
M3
import androidx.compose.material3.TopAppBar
TopAppBar(…)
Подумайте о использовании M3 CenterAlignedTopAppBar если вы ранее сосредоточили содержание в M2 TopAppBar . Приятно также знать о MediumTopAppBar и LargeTopAppBar .
Top Bars M3 Top App содержат новый параметр 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) { … }
}
)
M3
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(…)
}
M3
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
NavigationBar {
NavigationBarItem(…)
NavigationBarItem(…)
NavigationBarItem(…)
}
Кнопки, кнопки значков и ткани
Кнопки, кнопки значков и кнопки с плавающим действием (FABS) в 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(…)
M3
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 также включает в себя новые вариации кнопок. Проверьте их в обзоре справочного материала Compose Material 3 .
Выключатель
Переключатель в M3 отличается от M2. Как в M2, так и в M3 композитный коммутатор называется Switch , но пакеты импорта различаются:
М2
import androidx.compose.material.Switch
Switch(…)
M3
import androidx.compose.material3.Switch
Switch(…)
Поверхности и возвышение
Системы поверхности и высоты в M3 отличаются от M2. В M3 есть два типа возвышения:
- Высота тени (бросает тень, такой же, как M2)
- Тональная высота (накладывает цвет, новичок в M3)
При составлении это относится к функции Surface M2 и функции Surface M3:
М2
import androidx.compose.material.Surface
Surface(
elevation = …
) { … }
M3
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 | M3 |
|---|---|
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(…)
}
M3
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(…)
}
Вот примеры текстового акцента в M2 и M3:
М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(…)
}
M3
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
) { … }
M3
Badge(
containerColor = MaterialTheme.colorScheme.primary
) { … }
Полезные ссылки
Чтобы узнать больше о миграции с M2 на M3 в Compose, обратитесь к следующим дополнительным ресурсам.
Док
Образцы приложений
- Ответ M3 Пример приложения
- Jetchat sample app m2 до m3 миграция
- JetNews Sample App M2 на M3 миграция
- Теперь в приложении Android M3 Hero: модуль Core-DesignSystem
Видео
Ссылка на API и исходный код
{% дословно %}Рекомендуется для вас
- Примечание. Текст ссылки отображается, когда JavaScript отключен.
- Material Design 2 в Compose
- Material Design 3 в Compose
- Системы индивидуального дизайна в Compose