In Compose von Material 2 zu Material 3 migrieren

Material Design 3 ist die nächste Weiterentwicklung des Material Design. Sie enthält aktualisierte Designs, Komponenten und Material You-Personalisierungsfunktionen wie dynamische Farben. Es ist ein Update für Material Design 2 und passt zum neuen visuellen Stil und zur System-UI von Android 12 und höher.

In diesem Leitfaden geht es um die Migration von der Jetpack-Bibliothek von Composer (androidx.compose.material) zur Jetpack-Bibliothek von Composer 3 (androidx.compose.material3).

Ansätze

Generell sollten Sie M2 und M3 langfristig nicht zusammen in einer einzelnen App verwenden. Das liegt daran, dass sich die beiden Designsysteme und die jeweiligen Bibliotheken in Bezug auf ihre UX/UI-Designs und Compose-Implementierungen erheblich unterscheiden.

Ihre App verwendet möglicherweise ein Designsystem, z. B. eines, das mit Figma erstellt wurde. In solchen Fällen empfehlen wir Ihnen oder Ihrem Designteam, die Anwendung von M2 zu M3 zu migrieren, bevor Sie mit der Compose-Migration beginnen. Es ist nicht sinnvoll, eine App zu M3 zu migrieren, wenn ihr UX-/UI-Design auf M2 basiert.

Darüber hinaus sollte sich Ihr Migrationsansatz je nach Größe, Komplexität und UX-/UI-Design Ihrer Anwendung unterscheiden. Dadurch können Sie die Auswirkungen auf Ihre Codebasis minimieren. Die Migration sollte phasenweise erfolgen.

Zeitpunkt der Migration

Sie sollten die Migration so schnell wie möglich starten. Sie sollten jedoch überlegen, ob Ihre App realistisch für eine vollständige Migration von M2 zu M3 ist. Bevor Sie beginnen, sollten Sie einige Blockierszenarien untersuchen:

Szenario Empfohlene Vorgehensweise
Keine „Blocker“ Phasenweise Migration starten
Eine Komponente aus M2 ist in M3 noch nicht verfügbar. Weitere Informationen finden Sie unten im Abschnitt Komponenten und Layouts. Phasenweise Migration starten
Sie oder Ihr Designteam haben das Designsystem der App nicht von M2 zu M3 migriert. Migrieren Sie das Designsystem von M2 zu M3 und beginnen Sie dann mit der schrittweisen Migration.

Auch wenn Sie von den oben genannten Szenarien betroffen sind, sollten Sie einen schrittweisen Ansatz für die Migration wählen, bevor Sie ein Anwendungsupdate durchführen und veröffentlichen. In diesen Fällen würden Sie M2 und M3 parallel verwenden und M2 während der Migration zu M3 schrittweise auslaufen lassen.

Gestaffelter Ansatz

Die allgemeinen Schritte für eine stufenweise Migration sind folgende:

  1. Fügen Sie die M3-Abhängigkeit neben der M2-Abhängigkeit hinzu.
  2. Füge neben M2-Versionen der Designs deiner App auch M3-Versionen hinzu.
  3. Migrieren Sie einzelne Module, Bildschirme oder zusammensetzbare Funktionen je nach Größe und Komplexität Ihrer Anwendung zu M3. Weitere Informationen finden Sie in den folgenden Abschnitten.
  4. Entfernen Sie nach der vollständigen Migration die M2-Version(en) der Designs Ihrer App.
  5. M2-Abhängigkeit entfernen.

Abhängigkeiten

M3 hat ein separates Paket und eine separate Version als M2:

M2

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

M3

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

Die aktuellen M3-Versionen finden Sie auf der Seite Compose Material 3-Releases.

Andere Materialabhängigkeiten außerhalb der M2- und M3-Hauptbibliotheken haben sich nicht geändert. Sie verwenden eine Mischung aus M2- und M3-Paketen und -Versionen, was jedoch keine Auswirkungen auf die Migration hat. Sie können in der vorliegenden Form mit M3 verwendet werden:

Mediathek Paket und Version
Symbole aus Material Design erstellen androidx.compose.material:material-icons-*:$m2-version
Verbreitung von Material komponieren androidx.compose.material:material-ripple:$m2-version
Fenstergrößenklasse aus Material 3 erstellen androidx.compose.material3:material3-window-size-class:$m3-version

Experimentelle APIs

Einige M3 APIs gelten als experimentell. In solchen Fällen müssen Sie die Funktion auf Funktions- oder Dateiebene mit der Annotation ExperimentalMaterial3Api aktivieren:

import androidx.compose.material3.ExperimentalMaterial3Api

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

Designs

Sowohl in M2 als auch in M3 heißt das zusammensetzbare Design MaterialTheme, aber die Importpakete und Parameter unterscheiden sich:

M2

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
}

Farbe

Vergleich der Farbsysteme M2 und M3
Abbildung 1. M2-Farbsystem (links) gegenüber M3-Farbsystem (rechts)

Das Farbsystem in M3 unterscheidet sich deutlich von M2. Die Anzahl der Farbparameter wurde erhöht, sie haben unterschiedliche Namen und unterscheiden sich von M3-Komponenten. In Compose gilt dies für die M2-Klasse Colors, die M3-Klasse ColorScheme und zugehörige Funktionen:

M2

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
}

Angesichts der erheblichen Unterschiede zwischen den M2- und M3-Farbsystemen gibt es keine sinnvolle Zuordnung für Color-Parameter. Verwenden Sie stattdessen das Tool Material Theme Builder, um ein M3-Farbschema zu generieren. Verwenden Sie im Tool die M2-Farben als Hauptfarben. Diese werden vom Tool in Tonpaletten erweitert, die vom M3-Farbschema verwendet werden. Die folgenden Zuordnungen werden als Ausgangspunkt empfohlen:

M2 Tool zur Erstellung von Material-Designs
primary Primäre Zielgruppe
primaryVariant Sekundär
secondary Dritter Track
surface oder background Neutral
M2-Farben, die in Material Theme Builder zum Generieren eines M3-Farbschemas verwendet werden
Abbildung 2: Die M2-Farben von Jetchat werden im Material Theme Builder verwendet, um ein M3-Farbschema zu generieren.

Sie können die Hexadezimalcodewerte der Farbe für helle und dunkle Designs aus dem Tool kopieren und zum Implementieren einer M3-ColorScheme-Instanz verwenden. Alternativ kann Material Theme Builder die Funktion „Compose-Code“ exportieren.

isLight

Im Gegensatz zur M2-Klasse Colors enthält die M3-Klasse ColorScheme keinen isLight-Parameter. Generell sollten Sie versuchen, das zu modellieren, was diese Informationen benötigt, auf Themenebene. Beispiel:

M2

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

Weitere Informationen finden Sie im Leitfaden zur Erstellung von benutzerdefinierten Designs.

Dynamische Farben

Eine neue Funktion in M3 sind die dynamischen Farben. Anstelle von benutzerdefinierten Farben kann ein M3-ColorScheme unter Android 12 und höher die Farben des Gerätehintergrunds mithilfe der folgenden Funktionen nutzen:

Typografie

Vergleich der Typografiesysteme M2 und M3
Abbildung 3: M3-Typografiesystem (links) im Vergleich zum M2-Typografiesystem (rechts)

Das Typografiesystem in M3 unterscheidet sich von M2. Die Anzahl der Typografieparameter ist ungefähr gleich, aber sie haben unterschiedliche Namen und unterscheiden sich von M3-Komponenten. In Compose gilt dies für die M2-Klasse Typography und die M3-Klasse Typography:

M2

import androidx.compose.material.Typography

val AppTypography = Typography(
    // M2 TextStyle parameters
)

M3

import androidx.compose.material3.Typography

val AppTypography = Typography(
    // M3 TextStyle parameters
)

Die folgenden TextStyle-Parameterzuordnungen werden als Ausgangspunkt empfohlen:

M2 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

Form

Vergleich der M2- und M3-Formsysteme
Abbildung 4: M2-Formsystem (links) vs. M3-Formsystem (rechts)

Das Formsystem in M3 unterscheidet sich von M2. Die Anzahl der Formparameter hat zugenommen, sie haben einen anderen Namen und sind anders den M3-Komponenten zugeordnet. In Compose gilt dies für die M2-Klasse Shapes und die M3-Klasse Shapes:

M2

import androidx.compose.material.Shapes

val AppShapes = Shapes(
    // M2 Shape parameters
)

M3

import androidx.compose.material3.Shapes

val AppShapes = Shapes(
    // M3 Shape parameters
)

Die folgenden Shape-Parameterzuordnungen werden als Ausgangspunkt empfohlen:

M2 M3
extraSmall
small small
medium medium
large large
extraLarge

Komponenten und Layouts

Die meisten Komponenten und Layouts aus M2 sind in M3 verfügbar. Es gibt jedoch einige fehlende sowie neue, die in M2 noch nicht vorhanden waren. Außerdem haben einige M3-Komponenten mehr Variationen als ihre Entsprechungen in M2. Im Allgemeinen wird versucht, den M3-API-Oberflächen so ähnlich wie möglich zu sein, was ihnen in M2 am nächsten ist.

Angesichts der aktualisierten Farb-, Typografie- und Formsysteme neigen M3-Komponenten den neuen Designwerten anders. Es empfiehlt sich, das Token-Verzeichnis im Quellcode von Compose Material 3 als Datenquelle für diese Zuordnungen zu prüfen.

Während einige Komponenten besondere Überlegungen erfordern, werden die folgenden Funktionszuordnungen als Ausgangspunkt empfohlen:

Fehlende APIs:

M2 M3
androidx.compose.material.swipeable Noch nicht verfügbar

Ersetzte APIs:

M2 M3
androidx.compose.material.BackdropScaffold Kein M3-Äquivalent, stattdessen zu Scaffold oder BottomSheetScaffold migrieren
androidx.compose.material.BottomDrawer Kein M3-Äquivalent, stattdessen zu ModalBottomSheet migrieren

Umbenannte APIs:

M2 M3
androidx.compose.material.BottomNavigation androidx.compose.material3.NavigationBar
androidx.compose.material.BottomNavigationItem androidx.compose.material3.NavigationBarItem
androidx.compose.material.Chip androidx.compose.material3.AssistChip oder androidx.compose.material3.SuggestionChip
androidx.compose.material.ModalBottomSheetLayout androidx.compose.material3.ModalBottomSheet
androidx.compose.material.ModalDrawer androidx.compose.material3.ModalNavigationDrawer

Alle anderen APIs:

M2 M3
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

Die neuesten M3-Komponenten und -Layouts finden Sie in der Übersicht über die API-Referenz für Material 3. Neue und aktualisierte APIs finden Sie auf der Releaseseite.

Gerüst, Snackbars und Navigationsleiste

Vergleich des M2- und M3-Gerüsts mit Snackbar und Navigationsleiste
Abbildung 5: M2-Gerüst mit Snackbar und Navigationsleiste (links) im Vergleich zum M3-Gerüst mit Snackbar und Navigationsleiste (rechts).

Das Gerüst in M3 unterscheidet sich von M2. Sowohl in M2 als auch in M3 heißt die zusammensetzbare Hauptlayout-Datei Scaffold, aber die Importpakete und -parameter unterscheiden sich:

M2

import androidx.compose.material.Scaffold

Scaffold(
    // M2 scaffold parameters
)

M3

import androidx.compose.material3.Scaffold

Scaffold(
    // M3 scaffold parameters
)

Der M2-Parameter Scaffold enthält einen backgroundColor-Parameter, der jetzt in M3 Scaffold in containerColor benannt ist:

M2

import androidx.compose.material.Scaffold

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

M3

import androidx.compose.material3.Scaffold

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

Die M2-Klasse ScaffoldState ist in M3 nicht mehr vorhanden, da sie den Parameter drawerState enthält, der nicht mehr benötigt wird. Zum Anzeigen von Snackbars mit dem M3-Scaffold verwenden Sie stattdessen SnackbarHostState:

M2

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

Alle drawer*-Parameter aus M2-Scaffold wurden aus M3-Scaffold entfernt. Dazu gehören Parameter wie drawerShape und drawerContent. Wenn Sie eine Leiste mit dem M3-Scaffold einblenden möchten, verwenden Sie stattdessen eine zusammensetzbare Navigationsleiste wie ModalNavigationDrawer:

M2

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

Obere App-Leiste

Vergleich des M2- und M3-Gerüsts mit oberer App-Leiste und scrollbarer Liste
Abbildung 6: M2-Gerüst mit oberer App-Leiste und gescrollter Liste (links) im Vergleich zum M3-Gerüst mit oberer App-Leiste und gescrollter Liste (rechts)

Die oberen App-Leisten in M3 unterscheiden sich von denen in M2. Sowohl in M2 als auch in M3 heißt die obere zusammensetzbare Hauptleiste der App TopAppBar, die Importpakete und Parameter unterscheiden sich jedoch:

M2

import androidx.compose.material.TopAppBar

TopAppBar(…)

M3

import androidx.compose.material3.TopAppBar

TopAppBar(…)

Wenn du zuvor Inhalte in der M2-TopAppBar zentriert hast, solltest du die Verwendung von M3 CenterAlignedTopAppBar in Betracht ziehen. Es ist gut, auch die MediumTopAppBar und LargeTopAppBar zu kennen.

Die oberen M3-App-Leisten enthalten einen neuen scrollBehavior-Parameter, der beim Scrollen durch die Klasse TopAppBarScrollBehavior verschiedene Funktionen bietet, z. B. das Ändern der Höhe. Dies funktioniert in Verbindung mit Scrollen von Inhalten über Modifer.nestedScroll. Dies war in der M2-TopAppBar durch manuelle Änderung des elevation-Parameters möglich:

M2

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

Navigationsleiste / Navigationsleiste unten

Vergleich der unteren Navigationsleiste in M2 und der N3-Navigationsleiste
Abbildung 7. M2-Navigationsleiste unten (links) und M3-Navigationsleiste (rechts)

Die Navigation am unteren Rand in M2 wurde in M3 in Navigationsleiste umbenannt. In M2 gibt es die zusammensetzbaren Funktionen BottomNavigation und BottomNavigationItem, in M3 die zusammensetzbaren Funktionen NavigationBar und NavigationBarItem:

M2

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

Schaltflächen, Symbolschaltflächen und UAS

M2- und M3-Schaltflächen im Vergleich
Abbildung 8: M2-Tasten (links) und M3-Tasten (rechts)

Schaltflächen, Symbolschaltflächen und unverankerte Aktionsschaltflächen (UAS) in M3 unterscheiden sich von denen in M2. M3 enthält alle zusammensetzbaren Funktionen der M2-Schaltfläche:

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

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 enthält auch neue Variationen von Schaltflächen. Weitere Informationen dazu findest du in der API-Referenzübersicht für Material 3.

Wechseln

M2- und M3-Switches im Vergleich
Abbildung 9. M2-Switch (links) oder M3-Switch (rechts)

Der Wechsel in M3 unterscheidet sich von M2. Sowohl in M2 als auch in M3 heißt die zusammensetzbare Switch-Funktion Switch, aber die Importpakete unterscheiden sich:

M2

import androidx.compose.material.Switch

Switch(…)

M3

import androidx.compose.material3.Switch

Switch(…)

Oberflächen und Erhebungen

Vergleich zwischen M2-Höhen und M3-Oberflächenhöhen in hellen und dunklen Designs
Abbildung 10: Elevation über M2 im Vergleich zur Elevation über M3 im hellen Design (links) und im dunklen Design (rechts).

Die Oberflächen- und Höhensysteme in M3 unterscheiden sich von M2. In M3 gibt es zwei Arten von Höhenangaben:

  • Schattenhöhe (wirft einen Schatten, wie bei M2)
  • Höhenunterschied in Tonhöhe (überlagert eine Farbe, neu auf M3)

In Compose gilt dies für die M2-Funktion Surface und die M3-Funktion Surface:

M2

import androidx.compose.material.Surface

Surface(
    elevation = …
) { … }

M3

import androidx.compose.material3.Surface

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

Sie können die elevation Dp-Werte in M2 je nach UX-/UI-Designpräferenz sowohl für shadowElevation als auch für tonalElevation in M3 verwenden. Surface ist die zusammensetzbare Sicherung, die den meisten Komponenten zugrunde liegt. Daher können zusammensetzbare Komponenten auch Höhenparameter enthalten, die Sie auf dieselbe Weise migrieren müssen.

Die stufenförmigen Höhen in M3 ersetzen das Konzept der Höhen-Overlays in dunklen M2-Designs . Daher sind ElevationOverlay und LocalElevationOverlay in M3 nicht vorhanden und LocalAbsoluteElevation in M2 wurde in LocalAbsoluteTonalElevation in M3 geändert.

Alpha für Betonung und Inhalt

Vergleich der Symbol- und Textbetonung von M2 und M3
Abbildung 11: M2-Symbol und -Textbetonung (links) im Vergleich zu M3-Symbol und -Textbetonung (rechts)

Die Betonung in M3 unterscheidet sich deutlich von M2. Bei M2-Betonung wurden „An“-Farben mit bestimmten Alpha-Werten verwendet, um Inhalte wie Text und Symbole zu unterscheiden. In M3 gibt es jetzt verschiedene Ansätze:

  • Verwendung von „on“-Farben neben ihren „Variant on“-Farben aus dem erweiterten M3-Farbsystem.
  • Unterschiedliche Schriftstärken für Text verwenden

Daher sind ContentAlpha und LocalContentAlpha in M3 nicht vorhanden und müssen ersetzt werden.

Die folgenden Zuordnungen werden als Ausgangspunkt empfohlen:

M2 M3
onSurface mit ContentAlpha.high onSurface allgemein, FontWeight.MediumFontWeight.Black für Text
onSurface mit ContentAlpha.medium onSurfaceVariant allgemein, FontWeight.ThinFontWeight.Normal für Text
onSurface mit ContentAlpha.disabled onSurface.copy(alpha = 0.38f)

Hier ein Beispiel für die Betonung von Symbolen in M2 im Vergleich zu M3:

M2

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

Hier ein Beispiel für die Textbetonung in M2 im Vergleich zu M3:

M2

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

Hintergründe und Container

Hintergründe in M2 werden in M3 als „Container“ bezeichnet. Im Allgemeinen können Sie background*-Parameter in M2 mit denselben Werten in M3 durch container* ersetzen. Beispiel:

M2

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

M3

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

Interoperabilität von Ansichten ansehen

Wenn Ihre App Ansichten oder XML-Interoperabilität hat und die Bibliothek für den M3-Adapter für das Schreiben-Design verwendet, müssen Sie die Version M3 verwenden:

M2

implementation "com.google.android.material:compose-theme-adapter:$compose-theme-adapter-version"

M3

implementation "com.google.android.material:compose-theme-adapter-3:$compose-theme-adapter-3-version"

Die aktuellen Versionen finden Sie auf der Seite mit den Releases des MTC-Android Compose Theme Adapters.

Der Hauptunterschied zwischen den Versionen M2 und M3 besteht in den jeweiligen zusammensetzbaren Funktionen MdcTheme und Mdc3Theme:

M2

import com.google.android.material.composethemeadapter.MdcTheme

MdcTheme {
    // M2 content
}

M3

import com.google.android.material.composethemeadapter3.Mdc3Theme

Mdc3Theme {
    // M3 content
}

Weitere Informationen finden Sie in der README-Datei.

Weitere Informationen zur Migration von Material 2 zu Material 3 in Views finden Sie im Leitfaden zur Migration zu Material Design 3.

Weitere Informationen zur Migration von M2 zu M3 in Compose finden Sie in den folgenden zusätzlichen Ressourcen.

Docs

Beispiel-Apps

Videos

API-Referenz und Quellcode