Bermigrasi dari Material 2.5 ke Material 3 di Compose untuk Wear OS

Material 3 Expressive adalah evolusi berikutnya dari Desain Material. Desain ini mencakup tema, komponen, dan fitur personalisasi yang diperbarui seperti warna dinamis.

Panduan ini berfokus pada migrasi dari library Jetpack Wear Compose Material 2.5 (androidx.wear.compose) ke library Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) untuk aplikasi.

Pendekatan

Untuk memigrasikan kode aplikasi dari M2.5 ke M3, ikuti pendekatan yang sama seperti yang dijelaskan dalam panduan migrasi ponsel Material Compose, khususnya:

• Anda tidak boleh menggunakan M2.5 dan M3 dalam satu aplikasi jangka panjang.
• Anda tidak boleh lagi menggunakan library Horologist Composables, Compose Layout, atau Compose Material. Sebagai gantinya, gunakan komponen di M3.
• Gunakan pendekatan bertahap.

Dependensi

M3 memiliki paket dan versi terpisah untuk M2.5:

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

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

Lihat versi M3 terbaru di halaman rilis Wear Compose Material 3.

Library Wear Compose Foundation versi 1.6.0 memperkenalkan beberapa komponen baru yang didesain untuk bekerja dengan komponen Material 3. Demikian pula, SwipeDismissableNavHost dari library Wear Compose Navigation memiliki animasi yang diperbarui saat dijalankan di Wear OS 6 (level API 36) atau yang lebih tinggi. Saat mengupdate ke Wear Compose Material 3, sebaiknya update juga library Wear Compose Foundation dan Navigation:

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

Tema

Pada M2.5 dan M3, composable tema diberi nama MaterialTheme, tetapi paket dan parameter impornya berbeda. Di M3, parameter Colors telah diganti namanya menjadi ColorScheme dan MotionScheme telah diperkenalkan untuk menerapkan transisi.

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

Warna

Sistem warna di M3 sangat berbeda dengan M2.5. Jumlah parameter warna telah meningkat, memiliki nama berbeda, dan dipetakan berbeda ke komponen M3. Di Compose, ini berlaku untuk class Colors M2.5, class ColorScheme M3, dan fungsi terkait:

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

Tabel berikut menjelaskan perbedaan utama antara M2.5 dan M3:

Tema warna dinamis

Fitur baru di M3 adalah tema warna dinamis. Jika pengguna mengubah warna tampilan jam, warna di UI akan berubah agar cocok.

Gunakan fungsi dynamicColorScheme untuk menerapkan skema warna dinamis dan menyediakan defaultColorScheme sebagai penggantian jika skema warna dinamis tidak tersedia.

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

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

Tipografi

Sistem tipografi di M3 berbeda dengan M2.5 dan mencakup fitur berikut:

• Sembilan gaya teks baru
• Font fleksibel, yang memungkinkan penyesuaian skala huruf untuk berbagai ketebalan, lebar, dan kebulatan

• AnimatedText, yang menggunakan font fleksibel

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

Font fleksibel

Dengan Font Fleksibel, desainer dapat menentukan lebar dan ketebalan huruf untuk ukuran tertentu.

Gaya teks

TextStyle berikut tersedia di M3. Warna ini digunakan secara default oleh berbagai komponen M3.

Bentuk

Sistem bentuk di M3 berbeda dengan M2.5. Jumlah parameter bentuk telah meningkat, diberi nama berbeda, dan dipetakan berbeda ke komponen M3. Ukuran bentuk berikut tersedia:

• Ekstra kecil
• Kecil
• Sedang
• Besar
• Ekstra besar

Di Compose, ini berlaku untuk class Shapes M2 dan class Shapes M3:

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

Gunakan pemetaan parameter Bentuk dari Bermigrasi dari Material 2 ke Material 3 di Compose sebagai titik awal.

Perubahan bentuk

M3 memperkenalkan Shape Morphing: bentuk kini berubah sebagai respons terhadap interaksi.

Perilaku Perubahan Bentuk tersedia sebagai variasi pada sejumlah tombol bulat, lihat daftar tombol berikut yang mendukung Perubahan Bentuk:

Komponen dan Tata Letak

Sebagian besar komponen dan tata letak dari M2.5 tersedia di M3. Namun, beberapa komponen dan tata letak M3 tidak ada di M2.5. Selain itu, beberapa komponen M3 memiliki lebih banyak variasi dibandingkan dengan yang setara di M2.5.

Meskipun beberapa komponen memerlukan pertimbangan khusus, pemetaan fungsi berikut direkomendasikan sebagai titik awal:

Berikut daftar lengkap semua komponen Material 3:

Terakhir, daftar beberapa komponen yang relevan dari library Wear Compose Foundation:

Tombol

Tombol di M3 berbeda dengan M2.5. Chip M2.5 telah digantikan oleh Button. Implementasi Button memberikan nilai default untuk Text maxLines dan textAlign. Nilai default tersebut dapat diganti dalam elemen 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 juga menyertakan variasi tombol baru. Lihat di ringkasan Referensi API Compose Material 3.

M3 memperkenalkan tombol baru: EdgeButton. EdgeButton tersedia dalam 4 ukuran berbeda: ekstra kecil, kecil, sedang, dan besar. Implementasi EdgeButton memberikan nilai default untuk maxLines bergantung pada ukuran yang dapat disesuaikan.

Jika Anda menggunakan TransformingLazyColumn atau ScalingLazyColumn, teruskan EdgeButton ke ScreenScaffold sehingga EdgeButton berubah bentuk saat men-scroll, bukan menambahkan EdgeButton sebagai item daftar terakhir. Lihat kode berikut untuk memeriksa cara menggunakan EdgeButton dengan ScreenScaffold dan TransformingLazyColumn.

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

Scaffold

Scaffold di M3 berbeda dengan M2.5. Di M3, AppScaffold dan composable ScreenScaffold baru telah menggantikan Scaffold. AppScaffold dan ScreenScaffold menata struktur layar dan mengoordinasikan transisi komponen ScrollIndicator dan TimeText.

AppScaffold memungkinkan elemen layar statis seperti TimeText tetap terlihat selama transisi dalam aplikasi seperti geser untuk menutup. ​​Komponen ini menyediakan slot untuk konten aplikasi utama, yang biasanya disediakan oleh komponen navigasi seperti SwipeDismissableNavHost

Anda mendeklarasikan satu AppScaffold untuk Aktivitas dan menggunakan ScreenScaffold untuk setiap Layar. AppScaffold menambahkan komponen TimeTextdefault ke layar. Anda dapat menggantinya jika ingin menyesuaikannya menggunakan parameter 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 padding = rememberResponsiveColumnPadding(
        first = ColumnItemType.BodyText
    )

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

Jika Anda menggunakan HorizontalPager dengan HorizontalPagerIndicator, Anda dapat bermigrasi ke HorizontalPagerScaffold. HorizontalPagerScaffold ditempatkan dalam AppScaffold. AppScaffold dan HorizontalPagerScaffold menata struktur Pager dan mengoordinasikan transisi komponen HorizontalPageIndicator dan TimeText.

HorizontalPagerScaffold menampilkan HorizontalPageIndicator di bagian akhir tengah layar secara default dan mengoordinasikan tampilan dan penyembunyian TimeText dan HorizontalPageIndicator sesuai dengan apakah Pager sedang dipaginasi, yang ditentukan oleh PagerState.

Ada juga komponen AnimatedPage baru, yang menganimasikan halaman dalam Pager dengan efek penskalaan dan scrim berdasarkan posisinya.

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

Terakhir, M3 memperkenalkan VerticalPagerScaffold yang mengikuti pola yang sama dengan HorizontalPagerScaffold:

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

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

Placeholder

Ada beberapa perubahan API antara M2.5 dan M3. Placeholder.PlaceholderDefaults kini menyediakan dua pengubah:

• Modifier.placeholder, yang digambar sebagai pengganti konten yang belum dimuat
• Efek berkilau placeholder Modifier.placeholderShimmer yang memberikan efek berkilau placeholder yang berjalan dalam loop animasi saat menunggu data dimuat.

Lihat tabel berikut untuk mengetahui perubahan tambahan pada komponen Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost adalah bagian dari wear.compose.navigation. Saat komponen ini digunakan dengan M3, M3 MaterialTheme akan memperbarui LocalSwipeToDismissBackgroundScrimColor dan LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn adalah bagian dari wear.compose.lazy.foundation dan menambahkan dukungan untuk menskalakan dan mengubah animasi pada item daftar selama scrolling, sehingga meningkatkan pengalaman pengguna. Sangat direkomendasikan agar aplikasi bermigrasi dari ScalingLazyColumn ke TransformingLazyColumn

Mirip dengan ScalingLazyColumn, rememberTransformingLazyColumnState() menyediakan rememberTransformingLazyColumnState() untuk membuat TransformingLazyColumnState yang diingat di seluruh komposisi.

Untuk menambahkan animasi penskalaan dan pengubahan bentuk, tambahkan kode berikut ke setiap item daftar:

• Modifier.transformedHeight, yang memungkinkan Anda menghitung tinggi item yang diubah menggunakan TransformationSpec, Anda dapat menggunakan rememberTransformationSpec() kecuali jika Anda memerlukan penyesuaian lebih lanjut.
• SurfaceTransformation

Untuk memverifikasi bahwa padding sudah benar di bagian atas dan bawah daftar, gunakan pengubah 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

Link penting

Untuk mempelajari migrasi dari M2.5 ke M3 di Compose lebih lanjut, lihat referensi tambahan berikut.

Contoh

• Contoh Wear OS di GitHub
• Compose untuk codelab Wear OS
• Contoh Jetcaster

Referensi API dan kode sumber

• Referensi API Compose Material 3
• Contoh Compose Material 3 dalam kode sumber

Desain

• Panduan desain