Migracja z Material 2 do Material 3 w sekcji Utwórz

Material Design 3 to kolejny etap w ewolucji Material Design. it obejmuje zaktualizowane motywy, komponenty i funkcje personalizacji Material You np. dynamiczne kolory. Aktualizacja Material Design 2. spójne z nowym stylem wizualnym i interfejsem systemu na Androidzie 12 i nowszych.

Ten przewodnik dotyczy migracji z materiału do tworzenia wiadomości (androidx.compose.material) biblioteka Jetpack do interfejsu Compose Material 3 (androidx.compose.material3) Biblioteka Jetpack.

Podejścia

Ogólnie nie należy używać M2 i M3 w jednej aplikacji długoterminowej. Ten wynika z faktu, że oba systemy projektowania i odpowiadające im biblioteki różnią się w projektach UX/UI i wdrożeniach Compose.

Aplikacja może korzystać z systemu projektowania, np. utworzonego w aplikacji Figma. W takim także zalecamy przeprowadzenie migracji z wersji M2 – przez Ciebie lub zespół projektowy. do M3 przed rozpoczęciem migracji tworzenia wiadomości. Migracja nie ma sensu aplikacji do wersji M3, jeśli jej interfejs/UI jest oparty na M2.

Twoje podejście do migracji powinno być różne w zależności od rozmiar, złożoność oraz projekt UX/UI. Pomaga to zminimalizować wpływ w bazie kodu. Migracja powinna przebiegać stopniowo.

Kiedy przenosić

Rozpocznij migrację jak najszybciej. Ważne jest jednak, aby zastanów się, czy można w pełni przeprowadzić migrację Twojej aplikacji; z M2 do M3. Istnieją scenariusze „blokujące”, które warto rozważyć przed rozpoczęciem:

Nawet w przypadku opisanych powyżej scenariuszy należy stosować podejście stopniowe przed opublikowaniem i opublikowaniem aktualizacji aplikacji. W takich przypadkach korzystaliby równocześnie z M2 i M3 i stopniowo wycofywali M2 z migracji do M3.

Metoda stopniowa

Ogólne kroki migracji stopniowej:

1. Dodaj zależność M3 do zależności M2.
2. Dodaj motywy aplikacji w wersji M3 razem z wersjami M2 motywy aplikacji.
3. Przenieś poszczególne moduły, ekrany lub elementy kompozycyjne do wersji M3, w zależności od rozmiar i złożoność aplikacji (szczegóły znajdziesz w sekcjach poniżej).
4. Po zakończeniu migracji usuń wersje M2 motywów aplikacji.
5. Usuń zależność M2.

Zależności

M3 ma oddzielny pakiet i wersję do M2:

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

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

Najnowsze wersje M3 znajdziesz na stronie wersji Compose Material 3.

Inne zależności Materiałów poza głównymi bibliotekami M2 i M3 nie były została zmieniona. Wykorzystują one połączenie pakietów i wersji M2 i M3, ale nie ma to wpływ na migrację. Można ich używać w niezmienionej formie w M3:

Eksperymentalne interfejsy API

Niektóre interfejsy API M3 są uznawane za eksperymentalne. W takich przypadkach należy wyrazić zgodę na poziom funkcji lub pliku za pomocą adnotacji ExperimentalMaterial3Api:

import androidx.compose.material3.ExperimentalMaterial3Api

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

Motywy

Zarówno w M2, jak i M3 funkcja kompozycyjna motywu nazywa się MaterialTheme, ale funkcja importowania pakiety i parametry różnią się:

import androidx.compose.material.MaterialTheme

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

import androidx.compose.material3.MaterialTheme

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

Kolor

System kolorów w M3 znacznie różni się od systemu M2. zwiększyła się liczba parametrów kolorów, mają różne nazwy i mapują się inaczej niż komponenty M3. W przypadku tworzenia wiadomości dotyczy to wersji M2 klasa Colors, klasa M3 ColorScheme i powiązane funkcje:

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
}

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
}

Ze względu na istotne różnice między systemami kolorów M2 i M3 brak odpowiedniego mapowania parametrów Color. Zamiast tego używaj szablonu Material Narzędzie do tworzenia motywów, które pozwala wygenerować schemat kolorów M3. Korzystanie z M2 jako „podstawowe” kolory źródłowe w narzędziu, które narzędzie rozwija do tonalnego palety używane w schemacie kolorów M3. Zalecane są poniższe mapowania punkt początkowy:

Z narzędzia możesz skopiować wartości kodów szesnastkowych kolorów dla jasnego i ciemnego motywu i wykorzystać je do wdrożenia instancji M3 ColorScheme. Z kolei Material Kreator motywów może eksportować kod tworzenia wiadomości.

isLight

W przeciwieństwie do klasy M2 Colors klasa M3 ColorScheme nie zawiera komponentu isLight. Ogólnie rzecz biorąc, należy wypróbować modelowanie na poziomie motywu. Na przykład:

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
        …
    }
}

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
        …
    }
}

Więcej informacji znajdziesz w przewodniku na temat niestandardowego projektowania systemów w tworzeniu wiadomości.

Kolory dynamiczne

Nową funkcją w wersji M3 jest dynamiczny kolor. Zamiast używać niestandardowego kolorów, ColorScheme M3 może używać kolorów tapety na urządzeniu z Androidem 12 i nowszych, korzystając z tych funkcji:

• dynamicLightColorScheme
• dynamicDarkColorScheme

Typografia

System typograficzny w M3 jest inny niż M2. Liczba parametry typograficzne są mniej więcej takie same, ale mają różne nazwy mapują się inaczej na komponenty M3. W przypadku tworzenia wiadomości dotyczy to wersji M2 Zajęcia Typography i M3 Typography:

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

Na początek najlepiej zacząć korzystać z tych mapowań parametrów TextStyle punkt:

Kształt

System kształtów w M3 jest inny niż w M2. Liczba kształtów wzrosła, ma odmienne nazwy i mapuje się Komponenty M3. W przypadku tworzenia wiadomości dotyczy to klasy M2 Shapes oraz klasy Zajęcia M3 Shapes:

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

Na początek najlepiej zacząć korzystać z tych mapowań parametrów Shape punkt:

Komponenty i układy

Większość komponentów i układów z M2 jest dostępna w M3. Istnieją jednak niektórych brakujących i nowych, których nie było w M2. Ponadto niektóre platformy M3 mają więcej odmian niż ich odpowiedniki w wersji M2. Ogólnie M3 platformy interfejsów API dążą do tego, aby były jak najbardziej zbliżone do ich najbliższych odpowiedników. w wersji M2.

Ze względu na zaktualizowane systemy kolorów, typografii i kształtów komponenty M3 zwykle mapują do nowych wartości tematycznych. Dobrze jest sprawdzić tokeny w kodzie źródłowym Compose Material 3 jako źródła dla tych mapowań.

Niektóre komponenty wymagają szczególnych uwagi, ale poniższa funkcja zalecamy stosowanie mapowań jako punktu wyjścia:

Brakujące interfejsy API:

Zastąpione interfejsy API:

Interfejsy API ze zmienionymi nazwami:

Wszystkie pozostałe interfejsy API:

Poznaj najnowsze komponenty i układy M3 w interfejsie Compose Material 3 API omówienie referencyjne i zaglądaj na stronę wersji, gdzie znajdziesz nowe i zaktualizowanych interfejsów API.

Scaffold, paski powiadomień i szuflada nawigacji

Scaffold w M3 różni się od M2. Zarówno w M2, jak i M3 główny układ kompozycyjny nazywa się Scaffold, ale pakiety importu i parametry są inne:

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

Element M2 Scaffold zawiera teraz parametr backgroundColor containerColor w M3 Scaffold:

import androidx.compose.material.Scaffold

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

import androidx.compose.material3.Scaffold

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

Klasa M2 ScaffoldState nie istnieje już w wersji M3, ponieważ zawiera drawerState, który nie jest już potrzebny. Aby wyświetlić paski powiadomień z: M3 Scaffold, użyj SnackbarHostState:

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

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

Wszystkie parametry drawer* z narzędzia M2 Scaffold zostały usunięte z: Scaffold M3. Obejmują one takie parametry jak drawerShape oraz drawerContent Aby wyświetlić panel z narzędziem Scaffold w wersji M3, użyj panelu nawigacji kompozycyjne, na przykład ModalNavigationDrawer, zamiast tego:

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

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

Górny pasek aplikacji

Najlepsze paski aplikacji w M3 są inne niż w M2. W obu wersjach M2 M3, główny element kompozycyjny głównego paska aplikacji nazywa się TopAppBar, ale importowany plik pakiety i parametry różnią się:

import androidx.compose.material.TopAppBar

TopAppBar(…)

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Jeśli korzystałeś wcześniej z wersji M3 CenterAlignedTopAppBar, rozważ użycie i wyśrodkowuję treści w komponencie TopAppBar M2. Dobrze jest wiedzieć, MediumTopAppBar i LargeTopAppBar.

Słupki najpopularniejszych aplikacji M3 zawierają nowy parametr scrollBehavior, który zapewnia różne funkcji podczas przewijania klasy TopAppBarScrollBehavior, takich jak takich jak zmiana wysokości. Działa to w połączeniu z przewijaną treścią za pomocą Modifer.nestedScroll Było to możliwe w wersji M2 TopAppBar przez ręcznie zmienisz parametr elevation:

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) { … }
    }
)

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 { … }
    }
)

Dolny pasek nawigacyjny / pasek nawigacyjny

Dolna nawigacja w M2 została zmieniona na pasek nawigacyjny w języku: M3. W M2 dostępne są BottomNavigation BottomNavigationItem kompozycji, a w M3 Kompozycje NavigationBar i NavigationBarItem:

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

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

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

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

Przyciski, przyciski ikon i przyciski typu FAB

Przyciski, ikony i pływające przyciski poleceń w M3 różnią się od tych w M2. M3 zawiera wszystkie elementy kompozycyjne przycisku M2:

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(…)

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 zawiera również nowe odmiany przycisków. Wypróbuj ją w interfejsie Compose Material 3 Omówienie dokumentacji interfejsu API.

Przełącz

Przełącznik w M3 różni się od M2. Zarówno w M2, jak i M3 przełącznik Element composable ma nazwę Switch, ale pakiety do importu są inne:

import androidx.compose.material.Switch

Switch(…)

import androidx.compose.material3.Switch

Switch(…)

Powierzchnie i wysokość

Systemy powierzchni i wysokości w M3 są inne niż w M2. Istnieją 2 typy. wzniesienia w M3:

• Wysokość cienia (rzuca cień, tak jak w M2)
• Wzniesienie zabarwienia (nakłada się na kolor, w nowej wersji M3)

W narzędziu Compose dotyczy to funkcji M2 Surface i M3 Funkcja Surface:

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

import androidx.compose.material3.Surface

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

Możesz użyć wartości elevation Dp w M2 zarówno w przypadku shadowElevation, lub tonalElevation w wersji M3, w zależności od preferencji projektu UX/UI. Surface to kompozycyjna kopia zapasowa większości komponentów, więc komponent za pomocą funkcji kompozycyjnych mogą też ujawniać parametry wysokości, które trzeba migrować w tym samym sposób.

Ustawienie tonacji w M3 zastępuje koncepcję nakładek wysokości w ciemnym kolorze M2 motywów . Z tego powodu ElevationOverlay i LocalElevationOverlay nie występują w wersji M3, a LocalAbsoluteElevation w M2 zostało zmienione na LocalAbsoluteTonalElevation w M3.

Wyróżnienie i treść alfa

Nacisk na M3 znacznie różni się od punktu M2. W M2 nacisk na użycie „włączone” kolory z określonymi wartościami alfa, aby rozróżnić treści, takie jak tekst . W wersji M3 dostępne są teraz różne podejścia:

• Użycie kolorów z włączonym ustawieniem obok ich „wariantów” z rozszerzonej wersji M3 systemu kolorów.
• używanie różnych grubości czcionki w tekście.

W związku z tym pliki ContentAlpha i LocalContentAlpha nie istnieją w M3 i trzeba je wymienić.

Na początek zalecane są te mapowania:

Oto przykład naciskania ikon w wersjach M2 i M3:

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

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

Oto przykład uwydatnienia tekstu w wersjach M2 i M3:

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

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

Tła i kontenery

Tła w M2 są nazywane „kontenerami” w M3. Ogólnie możesz zastąpić Parametry background* w M2 z parametrem container* w M3, które mają te same wartości. Na przykład:

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

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

Przydatne linki

Aby dowiedzieć się więcej o migracji z M2 do M3 w Compose, zapoznaj się z tymi artykułami z dodatkowymi zasobami.

Dokumenty

• Material Design 3 w Compose

Przykładowe aplikacje

• Przykładowa aplikacja M3 – odpowiedzi
• Migracja przykładowej aplikacji Jetchat z M2 do M3
  • Początkowa migracja alfa 01
  • Kontynuacja aktualizacji wersji alfa10
• Migracja przykładowej aplikacji Jetnews z M2 do M3
• Teraz w aplikacji hero app na Androida M3 :moduł Core-designsystem

Filmy

• Wdrażanie Material You za pomocą Jetpack Compose

Dokumentacja API i kod źródłowy

• Dokumentacja interfejsu API Compose Material 3
• Przykłady Compose Material 3 w kodzie źródłowym