In Compose für Wear OS von Material 2.5 zu Material 3 migrieren

Material 3 Expressive ist die nächste Generation von Material Design. Es umfasst aktualisierte Funktionen für Themen, Komponenten und Personalisierung wie dynamische Farben.

In diesem Leitfaden geht es um die Migration von der Jetpack-Bibliothek Wear Compose Material 2.5 (androidx.wear.compose) zur Jetpack-Bibliothek Wear Compose Material 3 (androidx.wear.compose.material3) für Apps.

Ansätze

Wenn Sie Ihren App-Code von M2.5 zu M3 migrieren möchten, folgen Sie dem gleichen Ansatz, der in der Anleitung zur Migration von Compose Material für Smartphones beschrieben wird, insbesondere:

• M2.5 und M3 sollten nicht langfristig in derselben App verwendet werden.
• Sie sollten die Horologist Composables-, Compose Layout- oder Compose Material-Bibliotheken nicht mehr verwenden. Verwenden Sie stattdessen die Komponenten in M3.
• Schrittweisen Ansatz nutzen

Abhängigkeiten

M3 hat ein separates Paket und eine separate Version im Vergleich zu M2.5:

implementation("androidx.wear.compose:compose-material:1.4.0")

implementation("androidx.wear.compose:compose-material3:1.6.0")

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

Mit der Wear Compose Foundation-Bibliothek Version 1.6.0 wurden einige neue Komponenten eingeführt, die für die Verwendung mit Material 3-Komponenten entwickelt wurden. Ebenso hat SwipeDismissableNavHost aus der Wear Compose Navigation-Bibliothek eine aktualisierte Animation, wenn sie unter Wear OS 6 (API‑Level 36) oder höher ausgeführt wird. Wenn Sie auf die Wear Compose Material 3-Version aktualisieren, empfehlen wir, auch die Wear Compose Foundation- und Navigation-Bibliotheken zu aktualisieren:

implementation("androidx.wear.compose:compose-foundation:1.6.0")
implementation("androidx.wear.compose:compose-navigation:1.6.0")

Design

Sowohl in M2.5 als auch in M3 heißt die Theme-Composable-Funktion MaterialTheme, aber die Importpakete und Parameter unterscheiden sich. In M3 wurde der Parameter Colors in ColorScheme umbenannt und MotionScheme wurde für die Implementierung von Übergängen eingeführt.

import androidx.wear.compose.material.MaterialTheme

MaterialTheme(
    colors = AppColors,
    typography = AppTypography,
    shapes = AppShapes,
    content = content
)

import androidx.wear.compose.material3.MaterialTheme
// ...
    MaterialTheme(
        colorScheme = ColorScheme(),
        typography = Typography(),
        shapes = Shapes(),
        motionScheme = MotionScheme.standard(),
        content = { /*content here*/ }
    )
Theme.kt

Farbe

Das Farbsystem in M3 unterscheidet sich erheblich von M2.5. Die Anzahl der Farbparameter hat zugenommen, sie haben andere Namen und werden anders auf M3-Komponenten abgebildet. In Compose gilt dies für die Klasse M2.5 Colors, die Klasse M3 ColorScheme und die zugehörigen Funktionen:

import androidx.wear.compose.material.Colors

val appColorScheme: Colors = Colors(
   // M2.5 Color parameters
)

import androidx.wear.compose.material3.ColorScheme
// ...
    val appColorScheme: ColorScheme = ColorScheme(
        // M3 ColorScheme parameters
    )
Color.kt

In der folgenden Tabelle werden die wichtigsten Unterschiede zwischen M2.5 und M3 beschrieben:

Dynamisches Farbdesign

Eine neue Funktion in M3 ist das dynamische Farbdesign. Wenn Nutzer die Farben des Zifferblatts ändern, werden die Farben auf der Benutzeroberfläche entsprechend angepasst.

Verwenden Sie die Funktion dynamicColorScheme, um ein dynamisches Farbschema zu implementieren und ein defaultColorScheme als Fallback bereitzustellen, falls das dynamische Farbschema nicht verfügbar ist.

@Composable
fun myApp() {
    val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
    MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {}
}

internal val myBrandColors: ColorScheme = ColorScheme( /* Specify colors here */)
Color.kt

Typografie

Das Typografiesystem in M3 unterscheidet sich von M2.5 und umfasst die folgenden Funktionen:

• Neun neue Textstile
• Flexible Schriftarten, mit denen sich die Typografie für verschiedene Strichstärken, Breiten und Rundungen anpassen lässt

• AnimatedText, in der flexible Schriftarten verwendet werden

import androidx.wear.compose.material.Typography

val Typography = Typography(
   // M2.5 TextStyle parameters
)

import androidx.wear.compose.material3.Typography

val Typography = Typography(
    // M3 TextStyle parameters
)
Typography.kt

Flexible Schriftarten

Mit Flex-Schriftarten können Designer die Schriftbreite und ‑stärke für bestimmte Größen festlegen.

Textstile

Die folgenden TextStyles sind in M3 verfügbar. Sie werden standardmäßig von verschiedenen M3-Komponenten verwendet.

Form

Das Formsystem in M3 unterscheidet sich von M2.5. Die Anzahl der Formparameter hat zugenommen, sie haben andere Namen und werden anders auf M3-Komponenten abgebildet. Die folgenden Formgrößen sind verfügbar:

• Sehr klein
• Klein
• Mittel
• Groß
• Extragroß

In Compose gilt dies für die M2-Klasse Shapes und die M3-Klasse Shapes:

import androidx.wear.compose.material.Shapes

val Shapes = Shapes(
   // M2.5 Shapes parameters
)

import androidx.wear.compose.material3.Shapes

val Shapes = Shapes(
    // M3 Shapes parameters
)
Shape.kt

Verwenden Sie die Parameterzuordnung für Formen aus Von Material 2 zu Material 3 in Compose migrieren als Ausgangspunkt.

Form-Morphing

In M3 wird das Morphing von Formen eingeführt: Formen werden jetzt in Reaktion auf Interaktionen morphiert.

Das Verhalten „Form-Morphing“ ist als Variante für eine Reihe von runden Schaltflächen verfügbar. In der folgenden Liste finden Sie die Schaltflächen, die „Form-Morphing“ unterstützen:

Komponenten und Layout

Die meisten Komponenten und Layouts aus M2.5 sind in M3 verfügbar. Einige M3-Komponenten und ‑Layouts gab es in M2.5 jedoch nicht. Außerdem haben einige M3-Komponenten mehr Varianten als ihre Entsprechungen in M2.5.

Für einige Komponenten sind besondere Überlegungen erforderlich. Die folgenden Funktionszuordnungen werden jedoch als Ausgangspunkt empfohlen:

Hier finden Sie eine vollständige Liste aller Material 3-Komponenten:

Und schließlich eine Liste einiger relevanter Komponenten aus der Wear Compose Foundation-Bibliothek:

Schaltflächen

Die Schaltflächen in M3 unterscheiden sich von denen in M2.5. Der M2.5-Chip wurde durch eine Schaltfläche ersetzt. Die Button-Implementierung bietet Standardwerte für Text, maxLines und textAlign. Diese Standardwerte können im Text-Element überschrieben werden.

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

//M3 Buttons
Button(onClick = { }){}
CompactButton(onClick = { }){}
IconButton(onClick = { }){}
TextButton(onClick = { }){}
Button.kt

M3 enthält auch neue Schaltflächenvarianten. Weitere Informationen finden Sie in der Übersicht über die API-Referenz für Compose Material 3.

In M3 gibt es eine neue Schaltfläche: EdgeButton. EdgeButton ist in vier verschiedenen Größen erhältlich: extraklein, klein, mittelgroß und groß. EdgeButton Die Implementierung bietet einen Standardwert für maxLines, der je nach Größe angepasst werden kann.

Wenn Sie TransformingLazyColumn oder ScalingLazyColumn verwenden, übergeben Sie EdgeButton an ScreenScaffold, damit es sich beim Scrollen in seiner Form ändert, anstatt EdgeButton als letztes Listenelement hinzuzufügen. Im folgenden Code sehen Sie, wie Sie EdgeButton mit ScreenScaffold und TransformingLazyColumn verwenden.

val state = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = state,
    contentPadding =
        rememberResponsiveColumnPadding(
            first = ColumnItemType.ListHeader
        ),
    edgeButton = {
        EdgeButton(
            onClick = { }
        ) {
            Text(stringResource(R.string.show))
        }
    }
){ contentPadding ->
    TransformingLazyColumn(state = state, contentPadding = contentPadding,){
        // additional code here
    }
}
Button.kt

Gerüst

Das Gerüst in M3 unterscheidet sich von M2.5. In M3 haben AppScaffold und die neue zusammensetzbare Funktion ScreenScaffold Scaffold ersetzt. Mit AppScaffold und ScreenScaffold wird die Struktur eines Bildschirms festgelegt und die Übergänge der Komponenten ScrollIndicator und TimeText werden koordiniert.

Mit AppScaffold bleiben statische Bildschirmelemente wie TimeText bei Übergängen in der App, z. B. beim Wischen zum Schließen, sichtbar. ​​Sie bietet einen Slot für den Hauptanwendungsinhalt, der in der Regel von einer Navigationskomponente wie SwipeDismissableNavHost bereitgestellt wird.

Sie deklarieren ein AppScaffold für die Aktivität und verwenden ein ScreenScaffold für jeden Bildschirm. Mit AppScaffold wird den Bildschirmen eine Standardkomponente vom Typ TimeText hinzugefügt. Sie können ihn mit dem Parameter timeText überschreiben, wenn Sie ihn anpassen möchten.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

    AppScaffold {
        val navController = rememberSwipeDismissableNavController()
        SwipeDismissableNavHost(
            navController = navController,
            startDestination = "message_list"
        ) {
            composable("message_list") {
                MessageList(onMessageClick = { id ->
                    navController.navigate("message_detail/$id")
                })
            }
            composable("message_detail/{id}") {
                MessageDetail(id = it.arguments?.getString("id")!!)
            }
        }
    }
}

// Implementation of one of the screens in the navigation
@Composable
fun MessageDetail(id: String) {
    // .. Screen level content goes here
    val scrollState = rememberTransformingLazyColumnState()

    val padding = rememberResponsiveColumnPadding(
        first = ColumnItemType.BodyText
    )

    ScreenScaffold(
        scrollState = scrollState,
        contentPadding = padding
    ) { scaffoldPaddingValues ->
        // Screen content goes here
        // ...
Navigation.kt

Wenn Sie ein HorizontalPager mit HorizontalPagerIndicator verwenden, können Sie zu HorizontalPagerScaffold migrieren. HorizontalPagerScaffold wird in einem AppScaffold platziert. AppScaffold und HorizontalPagerScaffold legen die Struktur eines Pagers fest und koordinieren Übergänge der Komponenten HorizontalPageIndicator und TimeText.

HorizontalPagerScaffold zeigt die HorizontalPageIndicator standardmäßig in der Mitte des Bildschirms an und koordiniert das Ein- und Ausblenden von TimeText und HorizontalPageIndicator je nachdem, ob die Pager gerendert wird. Dies wird durch die PagerState bestimmt.

Außerdem gibt es eine neue AnimatedPage-Komponente, mit der eine Seite in einem Pager basierend auf ihrer Position mit einem Skalierungs- und Scrim-Effekt animiert wird.

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })
    val columnState = rememberTransformingLazyColumnState()
    val contentPadding = rememberResponsiveColumnPadding(
        first = ColumnItemType.ListHeader,
        last = ColumnItemType.BodyText,
    )
    HorizontalPagerScaffold(pagerState = pagerState) {
        HorizontalPager(
            state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold(
                    scrollState = columnState,
                    contentPadding = contentPadding
                ) { contentPadding ->
                    TransformingLazyColumn(
                        state = columnState,
                        contentPadding = contentPadding
                    ) {
                        item {
                            ListHeader(
                                modifier = Modifier.fillMaxWidth()
                            ) {
                                Text(text = "Pager sample")
                            }
                        }
                        item {
                            if (page == 0) {
                                Text(text = "Page #$page. Swipe right")
                            }
                            else{
                                Text(text = "Page #$page. Swipe left and right")
                            }
                        }
                    }
                }

            }
        }
    }
}
Pager.kt

Schließlich wird in M3 die VerticalPagerScaffold eingeführt, die dem gleichen Muster wie die HorizontalPagerScaffold folgt:

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })

    VerticalPagerScaffold(pagerState = pagerState) {
        VerticalPager(
            state = pagerState
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold {
                    ///…
                }
            }
        }
    }
}
Pager.kt

Platzhalter

Zwischen M2.5 und M3 gibt es einige API-Änderungen. Placeholder.PlaceholderDefaults bietet jetzt zwei Modifikatoren:

• Modifier.placeholder, das anstelle von Inhalten gezeichnet wird, die noch nicht geladen sind
• Ein Platzhalter-Schimmereffekt Modifier.placeholderShimmer, der in einer Animationsschleife ausgeführt wird, während auf das Laden der Daten gewartet wird.

In der folgenden Tabelle finden Sie weitere Änderungen an der Komponente Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost ist Teil von wear.compose.navigation. Wenn diese Komponente mit M3 verwendet wird, aktualisiert das M3-MaterialTheme die LocalSwipeToDismissBackgroundScrimColor und LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn ist Teil von wear.compose.lazy.foundation und bietet Unterstützung für das Skalieren und Morphen von Animationen für Listenelemente während des Scrollens, was die Nutzerfreundlichkeit verbessert. Wir empfehlen dringend, Apps von ScalingLazyColumn zu TransformingLazyColumn zu migrieren.

Ähnlich wie bei ScalingLazyColumn wird rememberTransformingLazyColumnState() bereitgestellt, um eine TransformingLazyColumnState zu erstellen, die über mehrere Kompositionen hinweg gespeichert wird.

Wenn Sie Skalierungs- und Morphing-Animationen hinzufügen möchten, fügen Sie jedem Listenelement Folgendes hinzu:

• Modifier.transformedHeight, mit der Sie die transformierte Höhe der Elemente mit einem TransformationSpec berechnen können. Sie können rememberTransformationSpec() verwenden, sofern keine weiteren Anpassungen erforderlich sind.
• A SurfaceTransformation

Mit dem Modifikator minimumVerticalContentPadding können Sie prüfen, ob das Padding oben und unten in der Liste korrekt ist.

val columnState = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                transformation = SurfaceTransformation(transformationSpec),
                onClick = { /* ... */ },
                icon = {
                    Icon(
                        imageVector = Icons.Default.Build,
                        contentDescription = "build",
                    )
                },
            ) {
                Text(
                    text = "Build",
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
        }
    }
}
List.kt

Nützliche Links

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

Produktproben

• Wear OS-Beispiele auf GitHub
• Codelab zu Compose für Wear OS
• Jetcaster-Beispiel

API-Referenz und Quellcode

• Compose Material 3 API-Referenz
• Material 3-Beispiele im Quellcode erstellen

Design

• Designanleitung