ย้ายข้อมูลจาก Material 2.5 ไปยัง Material 3 ใน Compose สำหรับ Wear OS

Material 3 Expressive คือวิวัฒนาการขั้นถัดไปของ Material Design ซึ่งรวมถึง การกำหนดธีม คอมโพเนนต์ และฟีเจอร์การปรับเปลี่ยนในแบบของคุณที่อัปเดตแล้ว เช่น สีแบบเปลี่ยนอัตโนมัติ

คู่มือนี้มุ่งเน้นการย้ายข้อมูลจากไลบรารี Jetpack ของ Wear Compose Material 2.5 (androidx.wear.compose) ไปยังไลบรารี Jetpack ของ Wear Compose Material 3 (androidx.wear.compose.material3) สำหรับแอป

แนวทาง

หากต้องการย้ายข้อมูลโค้ดแอปจาก M2.5 ไปยัง M3 ให้ใช้วิธีเดียวกันกับที่อธิบายไว้ ในคำแนะนำในการย้ายข้อมูล Material Compose สำหรับโทรศัพท์ โดยเฉพาะอย่างยิ่ง

• คุณไม่ควรใช้ทั้ง M2.5 และ M3 ในแอปเดียวในระยะยาว
• คุณไม่ควรใช้ Horologist Composables, Compose Layout หรือไลบรารี Compose Material อีกต่อไป แต่ให้ใช้คอมโพเนนต์ใน M3 แทน
• ใช้แนวทางแบบแบ่งระยะ

การขึ้นต่อกัน

M3 มีแพ็กเกจและเวอร์ชันแยกต่างหากจาก M2.5 ดังนี้

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

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

ดู M3 เวอร์ชันล่าสุดได้ในหน้ารุ่น Wear Compose Material 3

ไลบรารี Wear Compose Foundation เวอร์ชัน 1.6.0 ได้เปิดตัว คอมโพเนนต์ใหม่บางรายการที่ออกแบบมาให้ทำงานร่วมกับคอมโพเนนต์ Material 3 ในทำนองเดียวกัน SwipeDismissableNavHost จากไลบรารีการนำทางของ Wear Compose จะมีภาพเคลื่อนไหวที่อัปเดตเมื่อเรียกใช้ใน Wear OS 6 (ระดับ API 36) ขึ้นไป เมื่ออัปเดตเป็น Wear Compose Material เวอร์ชัน 3 เราขอแนะนำให้อัปเดตไลบรารี Wear Compose Foundation และ Navigation ด้วย

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

ธีม

ทั้งใน M2.5 และ M3 คอมโพสเทเบิลของธีมมีชื่อว่า MaterialTheme แต่ แพ็กเกจการนำเข้าและพารามิเตอร์จะแตกต่างกัน ใน M3 เราได้เปลี่ยนชื่อพารามิเตอร์ Colors เป็น ColorScheme และได้เปิดตัว 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

สี

ระบบสีใน M3 แตกต่างจาก M2.5 อย่างมาก พารามิเตอร์จำนวนสี เพิ่มขึ้น มีชื่อต่างกัน และแมปกับ คอมโพเนนต์ M3 แตกต่างกัน ใน Compose การตั้งค่านี้จะมีผลกับคลาส M2.5 Colors, คลาส M3 ColorScheme และฟังก์ชันที่เกี่ยวข้อง ดังนี้

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

ตารางต่อไปนี้อธิบายความแตกต่างที่สําคัญระหว่าง M2.5 กับ M3

การกำหนดธีมสีแบบเปลี่ยนอัตโนมัติ

ฟีเจอร์ใหม่ใน M3 คือการกำหนดธีมสีแบบไดนามิก หากผู้ใช้เปลี่ยน สีหน้าปัด สีใน UI จะเปลี่ยนให้ตรงกัน

ใช้ฟังก์ชัน dynamicColorScheme เพื่อใช้รูปแบบสีแบบไดนามิก และระบุ defaultColorScheme เป็นตัวเลือกสำรองในกรณีที่รูปแบบสีแบบไดนามิก ไม่พร้อมใช้งาน

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

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

การพิมพ์

ระบบการพิมพ์ใน M3 แตกต่างจาก M2.5 และมีฟีเจอร์ต่อไปนี้

• รูปแบบข้อความใหม่ 9 แบบ
• แบบอักษรแบบยืดหยุ่นซึ่งช่วยให้ปรับแต่งสเกลแบบอักษรสำหรับ ความหนา ความกว้าง และความกลมต่างๆ ได้

• AnimatedText ซึ่งใช้แบบอักษรแบบยืดหยุ่น

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

แบบอักษร Flex

แบบอักษรแบบยืดหยุ่นช่วยให้นักออกแบบระบุความกว้างและน้ำหนักของแบบอักษรสำหรับขนาดที่เฉพาะเจาะจงได้

รูปแบบข้อความ

TextStyle ต่อไปนี้พร้อมใช้งานใน M3 โดยค่าเริ่มต้น คอมโพเนนต์ M3 ต่างๆ จะใช้ตัวเลือกเหล่านี้

รูปทรง

ระบบรูปร่างใน M3 แตกต่างจาก M2.5 จำนวนพารามิเตอร์รูปร่าง เพิ่มขึ้น มีการตั้งชื่อพารามิเตอร์แตกต่างกัน และมีการแมปกับ คอมโพเนนต์ M3 แตกต่างกัน ขนาดรูปร่างที่พร้อมใช้งานมีดังนี้

• เล็กพิเศษ
• เล็ก
• ปานกลาง
• ใหญ่
• ใหญ่พิเศษ

ใน Compose จะมีผลกับคลาส M2 Shapes และคลาส M3 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

ใช้การแมปพารามิเตอร์รูปร่างจากย้ายข้อมูลจาก Material 2 ไปยัง Material 3 ใน Compose เป็นจุดเริ่มต้น

การเปลี่ยนรูปร่าง

M3 ขอแนะนำการเปลี่ยนรูปร่าง: ตอนนี้รูปร่างจะเปลี่ยนตามการโต้ตอบ

ลักษณะการทำงานของการเปลี่ยนรูปร่างมีให้ใช้งานเป็นรูปแบบต่างๆ ในปุ่มกลมหลายปุ่ม โปรดดูรายการปุ่มต่อไปนี้ที่รองรับการเปลี่ยนรูปร่าง

คอมโพเนนต์และเลย์เอาต์

คอมโพเนนต์และเลย์เอาต์ส่วนใหญ่จาก M2.5 จะพร้อมใช้งานใน M3 อย่างไรก็ตาม คอมโพเนนต์และเลย์เอาต์บางอย่างของ M3 ไม่มีใน M2.5 นอกจากนี้ คอมโพเนนต์ M3 บางรายการ ยังมีตัวแปรมากกว่าคอมโพเนนต์ที่เทียบเท่าใน M2.5

แม้ว่าคอมโพเนนต์บางอย่างจะต้องพิจารณาเป็นพิเศษ แต่เราขอแนะนำให้ใช้การแมปฟังก์ชันต่อไปนี้เป็นจุดเริ่มต้น

รายการคอมโพเนนต์ Material 3 ทั้งหมดมีดังนี้

และสุดท้ายคือรายการคอมโพเนนต์ที่เกี่ยวข้องบางส่วนจากไลบรารี Wear Compose Foundation

ปุ่ม

ปุ่มใน M3 แตกต่างจาก M2.5 ชิป M2.5 ถูกแทนที่ด้วย ปุ่ม การติดตั้งใช้งาน Button จะระบุค่าเริ่มต้นสำหรับ Text maxLines และ textAlign คุณจะลบล้างค่าเริ่มต้นเหล่านั้นได้ในองค์ประกอบ 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 ยังมีปุ่มรูปแบบใหม่ด้วย ดูได้ที่ภาพรวมเอกสารอ้างอิง Compose Material 3 API

M3 เปิดตัวปุ่มใหม่: EdgeButton EdgeButton มีให้เลือก 4 ขนาด ได้แก่ เล็กมาก เล็ก กลาง และใหญ่ EdgeButton การติดตั้งใช้งานจะระบุค่าเริ่มต้นสำหรับ maxLines ตามขนาด ซึ่งปรับแต่งได้

หากคุณใช้ TransformingLazyColumn หรือ ScalingLazyColumn ให้ส่ง EdgeButton ไปยัง ScreenScaffold เพื่อให้เปลี่ยนรูปร่าง เมื่อเลื่อนแทนที่จะเพิ่ม EdgeButton เป็นรายการสุดท้ายในรายการ ดูโค้ดต่อไปนี้เพื่อตรวจสอบวิธีใช้ EdgeButton กับ ScreenScaffold และ 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 ใน M3 แตกต่างจาก M2.5 ใน M3 AppScaffold และ ScreenScaffoldแบบประกอบใหม่ได้แทนที่ Scaffold แล้ว AppScaffold และ ScreenScaffold จะวางโครงสร้างของหน้าจอและประสานงานการเปลี่ยนของคอมโพเนนต์ ScrollIndicator และ TimeText

AppScaffold ช่วยให้องค์ประกอบหน้าจอแบบคงที่ เช่น TimeText ยังคงมองเห็นได้ ในระหว่างการเปลี่ยนหน้าในแอป เช่น การปัดเพื่อปิด ​​โดยมีช่องสำหรับ เนื้อหาแอปพลิเคชันหลัก ซึ่งโดยปกติแล้วจะจัดหาโดยคอมโพเนนต์การนำทาง เช่น SwipeDismissableNavHost

คุณประกาศ AppScaffold หนึ่งรายการสำหรับกิจกรรมและใช้ ScreenScaffold สำหรับแต่ละหน้าจอ AppScaffold จะเพิ่มTimeTextคอมโพเนนต์เริ่มต้นลงในหน้าจอ คุณสามารถ ลบล้างได้หากต้องการปรับแต่งโดยใช้พารามิเตอร์ 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

หากคุณใช้ HorizontalPager กับ HorizontalPagerIndicator คุณสามารถย้ายข้อมูลไปยัง HorizontalPagerScaffold ได้ HorizontalPagerScaffold อยู่ภายใน AppScaffold AppScaffold และ HorizontalPagerScaffold จะวางโครงสร้างของ Pager และประสานงานการเปลี่ยนของคอมโพเนนต์ HorizontalPageIndicator และ TimeText

HorizontalPagerScaffold จะแสดง HorizontalPageIndicator ที่ กึ่งกลางด้านท้ายของหน้าจอโดยค่าเริ่มต้น และประสานงานการแสดงและการซ่อน TimeText และ HorizontalPageIndicator ตามว่ามีการแบ่งหน้า Pager หรือไม่ ซึ่งจะกำหนดโดย PagerState

นอกจากนี้ยังมีAnimatedPageคอมโพเนนต์ใหม่ ซึ่งจะเคลื่อนไหวหน้าภายใน Pager ด้วยเอฟเฟกต์การปรับขนาดและเอฟเฟกต์ Scrim ตามตำแหน่งของหน้า

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

สุดท้าย M3 ได้เปิดตัวVerticalPagerScaffold ซึ่งมีรูปแบบเดียวกันกับHorizontalPagerScaffold ดังนี้

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

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

ตัวยึดตำแหน่ง

API มีการเปลี่ยนแปลงบางอย่างระหว่าง M2.5 กับ M3 Placeholder.PlaceholderDefaults มีตัวแก้ไข 2 รายการดังนี้

• Modifier.placeholder ซึ่งจะวาดแทนเนื้อหาที่ยังไม่ได้โหลด
• เอฟเฟกต์แวววาวของตัวยึดตำแหน่ง Modifier.placeholderShimmer ซึ่ง แสดงเอฟเฟกต์แวววาวของตัวยึดตำแหน่งที่ทำงานในลูปภาพเคลื่อนไหวขณะ รอให้โหลดข้อมูล

ดูการเปลี่ยนแปลงเพิ่มเติมในคอมโพเนนต์ Placeholder ได้ในตารางต่อไปนี้

SwipeDismissableNavHost

SwipeDismissableNavHost เป็นส่วนหนึ่งของ wear.compose.navigation เมื่อใช้คอมโพเนนต์นี้กับ M3 ทาง M3 MaterialTheme จะอัปเดต LocalSwipeToDismissBackgroundScrimColor และ LocalSwipeToDismissContentScrimColor

TransformingLazyColumn

TransformingLazyColumn เป็นส่วนหนึ่งของ wear.compose.lazy.foundation และเพิ่ม การรองรับการปรับขนาดและการเปลี่ยนรูปภาพเคลื่อนไหวในรายการระหว่างการเลื่อน เพื่อปรับปรุงประสบการณ์ของผู้ใช้ เราขอแนะนำเป็นอย่างยิ่งให้แอปย้ายข้อมูลจาก ScalingLazyColumn ไปยัง TransformingLazyColumn

เช่นเดียวกับ ScalingLazyColumn ซึ่งมีrememberTransformingLazyColumnState()สำหรับสร้างTransformingLazyColumnStateที่ระบบจดจำได้ในทุกองค์ประกอบ

หากต้องการเพิ่มภาพเคลื่อนไหวการปรับขนาดและการเปลี่ยนรูปร่าง ให้เพิ่มรายการต่อไปนี้ลงในรายการแต่ละรายการ

• Modifier.transformedHeight ซึ่งช่วยให้คุณคำนวณความสูงที่แปลงแล้วของ รายการโดยใช้ TransformationSpec ได้ คุณสามารถใช้ rememberTransformationSpec() ได้ เว้นแต่คุณต้องการปรับแต่งเพิ่มเติม
• A SurfaceTransformation

หากต้องการยืนยันว่าการเว้นวรรคที่ด้านบนและด้านล่างของรายการถูกต้อง ให้ใช้ตัวแก้ไข 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

ลิงก์ที่มีประโยชน์

ดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายข้อมูลจาก M2.5 ไปยัง M3 ใน Compose ได้จากแหล่งข้อมูลเพิ่มเติมต่อไปนี้

ตัวอย่าง

• ตัวอย่าง Wear OS ใน GitHub
• Codelab Compose สำหรับ Wear OS
• ตัวอย่าง Jetcaster

เอกสารอ้างอิง API และซอร์สโค้ด

• เอกสารอ้างอิง API ของ Compose Material 3
• เขียนตัวอย่าง Material 3 ในซอร์สโค้ด

การออกแบบ

• คำแนะนำด้านการออกแบบ