Migracja z wersji Material 2.5 na Material 3 w Compose na Wear OS

Material 3 Expressive to kolejna ewolucja Material Design. Obejmuje zaktualizowane motywy, komponenty i funkcje personalizacji, takie jak dynamiczny kolor.

Ten przewodnik zawiera informacje o migracji aplikacji z biblioteki Jetpack Wear Compose Material 2.5 (androidx.wear.compose) do biblioteki Jetpack Wear Compose Material 3 (androidx.wear.compose.material3).

Podejścia

Aby przenieść kod aplikacji z M2.5 do M3, postępuj zgodnie z instrukcjami podanymi w przewodniku po migracji do biblioteki Compose Material na telefonie, a w szczególności:

• Nie należy długoterminowo używać w jednej aplikacji zarówno M2.5, jak i M3.
• Nie należy już używać bibliotek Horologist Composables, Compose Layout ani Compose Material. Zamiast tego używaj komponentów w M3.
• Zastosuj podejście etapowe.

Zależności

M3 ma osobny pakiet i wersję niż M2.5:

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

implementation("androidx.wear.compose:compose-material3:1.8.0-alpha01")

Najnowsze wersje M3 znajdziesz na stronie wersji Wear Compose.

Wersja 1.8.0-alpha01 biblioteki Wear Compose Foundation wprowadziła nowe komponenty, które są przeznaczone do współpracy z komponentami Material 3. Podobnie SwipeDismissableNavHost z biblioteki Wear Compose Navigation ma zaktualizowaną animację, gdy jest uruchamiana na Wear OS 6 (API na poziomie 36) lub nowszym. Podczas aktualizacji do wersji Wear Compose Material 3 zalecamy też zaktualizowanie bibliotek Wear Compose Foundation i Navigation:

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

Motyw

W przypadku M2.5 i M3 funkcja kompozycyjna motywu ma nazwę MaterialTheme, ale pakiety importu i parametry różnią się. W M3 parametr Colors został zmieniony na ColorScheme, a do implementowania przejść wprowadzono parametr MotionScheme.

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

Kolor

System kolorów w M3 różni się znacznie od systemu w M2.5. Zwiększyła się liczba parametrów koloru, mają one inne nazwy i inaczej są mapowane na komponenty M3. W Compose dotyczy to klasy M2.5 Colors, klasy M3 ColorScheme i powiązanych funkcji:

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

W tabeli poniżej opisano najważniejsze różnice między M2.5 a M3:

Motywy kolorów dynamicznych

Nową funkcją w M3 jest dynamiczne kolorowanie. Jeśli użytkownicy zmienią kolory tarczy zegarka, kolory w interfejsie użytkownika dopasują się do nich.

Użyj funkcji dynamicColorScheme, aby wdrożyć dynamiczny schemat kolorów, i podaj defaultColorScheme jako rezerwę na wypadek, gdyby dynamiczny schemat kolorów był niedostępny.

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

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

Typografia

System typografii w M3 różni się od tego w M2.5 i obejmuje te funkcje:

• 9 nowych stylów tekstu
• czcionki elastyczne, które umożliwiają dostosowywanie skal typów do różnych grubości, szerokości i zaokrągleń;

• AnimatedText, który używa elastycznych czcionek;

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

Czcionki elastyczne

Czcionki elastyczne umożliwiają projektantom określanie szerokości i wagi znaków dla konkretnych rozmiarów.

Style tekstu

W M3 dostępne są te TextStyles: Są one domyślnie używane przez różne komponenty M3.

Kształt

System kształtów w M3 różni się od tego w M2.5. Liczba parametrów kształtu wzrosła, mają one inne nazwy i inaczej mapują się na komponenty M3. Dostępne są te rozmiary kształtów:

• Bardzo mały
• Mały
• średni,
• Duży
• Bardzo duży

W Compose dotyczy to klas M2.5 Shapes i M3Shapes:

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

Jako punkt początkowy użyj mapowania parametrów kształtów z artykułu Migracja z Material 2 do Material 3 w Compose.

Przekształcanie kształtów

Wersja M3 wprowadza zmianę kształtu: kształty zmieniają się teraz w odpowiedzi na interakcje.

Zachowanie Zmiana kształtu jest dostępne jako odmiana kilku okrągłych przycisków. Poniżej znajdziesz listę przycisków, które obsługują zmianę kształtu:

Komponenty i układ

Większość komponentów i układów z M2.5 jest dostępna w M3. Niektóre komponenty i układy M3 nie istniały jednak w M2.5. Poza tym niektóre komponenty M3 mają więcej wariantów niż ich odpowiedniki w M2.5.

Niektóre komponenty wymagają szczególnej uwagi, ale jako punkt początkowy zalecamy te mapowania funkcji:

Oto lista najczęściej używanych komponentów Material 3 i ich odpowiedników w Material 2.5:

Na koniec lista niektórych komponentów z biblioteki Wear Compose Foundation:

Przyciski

Przyciski w M3 różnią się od tych w M2.5. Chip M2.5 został zastąpiony przyciskiem. Implementacja Button zapewnia domyślne wartości atrybutów Text maxLines i textAlign. Wartości domyślne można zastąpić w elemencie Text.

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 zawiera też nowe warianty przycisków. Znajdziesz je w omówieniu dokumentacji interfejsu Compose Material 3 API.

M3 wprowadza nowy przycisk: EdgeButton. EdgeButton jest dostępny w 4 rozmiarach: bardzo małym, małym, średnim i dużym. EdgeButton implementacja podaje wartość domyślną dla maxLines w zależności od rozmiaru którą można dostosować.

Jeśli używasz TransformingLazyColumn lub ScalingLazyColumn, przekaż EdgeButton do ScreenScaffold, aby zmieniał kształt podczas przewijania, zamiast dodawać EdgeButton jako ostatni element listy. Zapoznaj się z poniższym kodem, aby sprawdzić, jak używać EdgeButton z ScreenScaffold i TransformingLazyColumn.

val state = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = state,
    edgeButton = {
        EdgeButton(
            onClick = { },
            modifier = Modifier.scrollable(
                state,
                orientation = Orientation.Vertical,
                reverseDirection = true,
                // Apply overscroll to the EdgeButton for proper scrolling behavior.
                overscrollEffect = rememberOverscrollEffect(),
            ),
        ) {
            Text(stringResource(R.string.show))
        }
    },
) { contentPadding ->
    TransformingLazyColumn(state = state, contentPadding = contentPadding) {
        // additional code here
        // ...
    }
}
Button.kt

rusztowanie,

Platforma w M3 różni się od platformy w M2.5. W M3 komponenty AppScaffold i nowy komponent ScreenScaffold zastąpiły komponent Scaffold. AppScaffold i ScreenScaffold określają strukturę ekranu i koordynują przejścia komponentów ScrollIndicator i TimeText.

AppScaffold umożliwia pozostawienie widocznych statycznych elementów ekranu, takich jak TimeText, podczas przejść w aplikacji, np. podczas przesuwania w celu zamknięcia. Zawiera miejsce na główną treść aplikacji, która zwykle jest dostarczana przez komponent nawigacyjny, taki jak SwipeDismissableNavHost

W przypadku aktywności deklarujesz 1 AppScaffold, a w przypadku każdego ekranu używasz ScreenScaffold. AppScaffold dodaje do ekranów domyślny TimeTextkomponent. Możesz ją zastąpić, jeśli chcesz ją dostosować, używając parametru timeText.

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 transformationSpec = rememberTransformationSpec()

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

Jeśli używasz HorizontalPager z HorizontalPageIndicator, możesz przejść na HorizontalPagerScaffold. HorizontalPagerScaffold jest umieszczony w AppScaffold. AppScaffold i HorizontalPagerScaffold określają strukturę komponentu Pager i koordynują przejścia komponentów HorizontalPageIndicator i TimeText.

HorizontalPagerScaffold domyślnie wyświetla HorizontalPageIndicator na środku ekranu i koordynuje wyświetlanie oraz ukrywanie TimeText i HorizontalPageIndicator w zależności od tego, czy Pager jest stronicowany. Określa to parametr PagerState.

Jest też nowy komponent AnimatedPage, który animuje stronę w komponencie Pager, stosując efekt skalowania i przyciemniania w zależności od jej pozycji.

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

    HorizontalPagerScaffold(pagerState = pagerState) {
        HorizontalPager(
            state = pagerState,
            flingBehavior =
                PagerScaffoldDefaults.snapWithSpringFlingBehavior(
                    state = pagerState
                ),
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                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 = "Pager sample")
                            }
                        }
                        item {
                            Card(
                                modifier = Modifier
                                    .fillMaxWidth()
                                    .transformedHeight(this, transformationSpec)
                                    .minimumVerticalContentPadding(
                                        CardDefaults.minimumVerticalListContentPadding
                                    ),
                                transformation = SurfaceTransformation(transformationSpec),
                            ) {
                                if (page == 0) {
                                    Text(text = "Page #$page. Swipe right")
                                } else {
                                    Text(text = "Page #$page. Swipe left and right")
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
Pager.kt

Wreszcie M3 wprowadza VerticalPagerScaffold, które ma taki sam wzór jak HorizontalPagerScaffold:

@Composable
fun VerticalPagerScaffoldSample() {
    AppScaffold {
        val pagerState = rememberPagerState(pageCount = { 10 })

        VerticalPagerScaffold(pagerState = pagerState) {
            VerticalPager(
                state = pagerState,
                flingBehavior =
                    PagerScaffoldDefaults.snapWithSpringFlingBehavior(
                        state = pagerState
                    ),
            ) { page ->
                AnimatedPage(pageIndex = page, pagerState = pagerState) {
                    ScreenScaffold {
                        Column(
                            modifier = Modifier.fillMaxSize(),
                            horizontalAlignment = Alignment.CenterHorizontally,
                            verticalArrangement = Arrangement.Center,
                        ) {
                            Text(text = "Page #$page")
                            Spacer(modifier = Modifier.height(8.dp))
                            Text(text = "Swipe up and down")
                        }
                    }
                }
            }
        }
    }
}
Pager.kt

Obiekt zastępczy

Między wersjami M2.5 i M3 interfejsu API występują pewne różnice. M3 udostępnia 2 modyfikatory symboli zastępczych:

• Modifier.placeholder, który jest rysowany zamiast treści, które nie zostały jeszcze wczytane.
• Efekt połyskiwania elementu zastępczego Modifier.placeholderShimmer, który zapewnia efekt połyskiwania elementu zastępczego działający w pętli animacji podczas oczekiwania na załadowanie danych.

Dodatkowe zmiany w komponencie Placeholder znajdziesz w tabeli poniżej.

SwipeDismissableNavHost

SwipeDismissableNavHost jest częścią usługi wear.compose.navigation. Gdy ten komponent jest używany z M3, M3 MaterialTheme aktualizuje LocalSwipeToDismissBackgroundScrimColor i LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn jest częścią androidx.wear.compose.foundation.lazy i dodaje obsługę skalowania i przekształcania animacji na elementach listy podczas przewijania, co zwiększa wygodę użytkownika. Zdecydowanie zalecamy, aby aplikacje przeszły z ScalingLazyColumn na TransformingLazyColumn.

Podobnie jak ScalingLazyColumn, udostępnia rememberTransformingLazyColumnState() do tworzenia TransformingLazyColumnState, który jest zapamiętywany w różnych kompozycjach.

Aby dodać animacje skalowania i przekształcania, dodaj do każdego elementu listy te informacje:

• Modifier.transformedHeight, która umożliwia obliczanie przekształconej wysokości elementów za pomocą TransformationSpec, możesz użyć rememberTransformationSpec(), chyba że potrzebujesz dalszego dostosowania.
• SurfaceTransformation

Aby sprawdzić, czy dopełnienie u góry i u dołu listy jest prawidłowe, użyj modyfikatora minimumVerticalContentPadding.

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

Przydatne linki

Więcej informacji o migracji z M2.5 do M3 w Compose znajdziesz w tych materiałach.

Przykłady

• Przykłady Wear OS na GitHubie
• Ćwiczenia z Compose na Wear OS
• Próbka Jetcaster

Dokumentacja API i kod źródłowy

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

Projektowanie

• Wskazówki dotyczące projektowania