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

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

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

Подходы

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

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

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

Когда следует мигрировать

В идеале миграцию следует начать как можно скорее. Однако важно оценить, насколько реально ваше приложение сможет полностью перейти с 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
}

Цвет

Сравнение цветовых систем M2 и M3
Рисунок 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 Design
primary Начальный
primaryVariant Вторичный
secondary Третичный
surface или background Нейтральный
Цвета M2 используются в Material Theme Builder для генерации цветовой схемы M3.
Рисунок 2. Цвета M2 от Jetchat, использованные в Material Theme Builder для создания цветовой схемы M3.

Вы можете скопировать шестнадцатеричные коды цветов для светлой и темной тем из инструмента и использовать их для реализации экземпляра цветовой схемы M3. Кроме того, 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 и выше, используя следующие функции:

Типография

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

Система типографики в 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

Форма

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

Система форм в 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. В целом, интерфейсы 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 :

М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.

Строительные леса, буфеты и выдвижная панель навигации.

Сравнение каркасов M2 и M3 с панелью быстрого доступа и выдвижной навигационной панелью.
Рисунок 5. Каркас M2 с панелью быстрого доступа и выдвижным навигационным меню (слева) по сравнению с каркасом M3 с панелью быстрого доступа и выдвижным навигационным меню (справа).

В M3 структура Scaffold отличается от 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 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* из 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()
        }
    }
)

М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()
                }
            }
        )
    }
)

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

Сравнение шаблонов M2 и M3 с верхней панелью приложения и прокручиваемым списком.
Рисунок 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 появился новый параметр scrollBehavior , позволяющий изменять функциональность при прокрутке через класс TopAppBarScrollBehavior , например, изменять высоту прокрутки. Это работает в сочетании с прокруткой контента с помощью Modifier.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.
Рисунок 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-функции.

Сравнение кнопок M2 и M3
Рисунок 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 .

Выключатель

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

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

М2

import androidx.compose.material.Switch

Switch()

М3

import androidx.compose.material3.Switch

Switch()

Поверхности и фасады

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

Системы рельефа и высот в М3 отличаются от М2. В М3 существует два типа высот:

  • Высота тени (отбрасывает тень, как и 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 является базовым компонентом, лежащим в основе большинства компонентов, поэтому компоненты также могут предоставлять параметры elevation, которые необходимо перенести аналогичным образом.

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

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

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

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

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

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

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

М2 М3
onSurface with ContentAlpha.high onSurface в целом, FontWeight.Medium - FontWeight.Black для текста
onSurface with ContentAlpha.medium onSurfaceVariant в целом, FontWeight.Thin - FontWeight.Normal для текста
onSurface with 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, обратитесь к следующим дополнительным ресурсам.

Документы

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

Видео

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

{% verbatim %} {% endverbatim %} {% verbatim %} {% endverbatim %}