انتقال از Material 2.5 به Material 3 در Compose برای Wear OS

Material 3 Expressive تحول بعدی «طراحی مواد» است. این نسخه شامل ویژگی‌های به‌روزشده زمینه‌سازی، مؤلفه‌ها، و شخصی‌سازی مثل رنگ پویا است.

این راهنما بر انتقال از کتابخانه Jetpack Wear Compose Material 2.5 (androidx.wear.compose) به کتابخانه Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) برای برنامه‌ها تمرکز دارد.

رویکردها

برای انتقال کد برنامه‌تان از M2.5 به M3، همان رویکرد شرح‌داده‌شده در راهنمای تلفن انتقال Compose Material را دنبال کنید، به‌ویژه:

• نباید از هر دو نسخه 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.8.0-alpha03")

جدیدترین نسخه‌های M3 را در صفحه نسخه‌های Wear Compose ببینید.

نسخه 1.8.0-alpha03 کتابخانه Wear Compose Foundation چند مؤلفه جدید معرفی کرده است که برای کار با مؤلفه‌های Material 3 طراحی شده‌اند. به‌طور مشابه، SwipeDismissableNavHost از کتابخانه Wear Compose Navigation هنگام اجرا در Wear OS 6 (سطح میانای برنامه‌سازی کاربردی ۳۶) یا بالاتر، پویانمایی به‌روزشده‌ای دارد. هنگام به‌روزرسانی به نسخه Wear Compose Material 3، پیشنهاد می‌کنیم کتابخانه‌های Wear Compose Foundation و Navigation را نیز به‌روز کنید:

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

زمینه

در هر دو 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 زمینه رنگ پویا است. اگر کاربران رنگ‌های صفحه ساعت را تغییر دهند، رنگ‌های میانای کاربر نیز برای مطابقت تغییر می‌کند.

از تابع 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 متفاوت است و شامل ویژگی‌های زیر است:

• نه سبک نوشتار جدید
• قلم‌های Flex که امکان سفارشی‌سازی مقیاس‌های نوع را برای وزن‌ها، پهناها، و گردی‌های مختلف فراهم می‌کند

• ‫AnimatedText، که از قلم‌های flex استفاده می‌کند

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

«قلم‌های Flex» به طراحان اجازه می‌دهد تا پهنا و سیاهی قلم را برای اندازه‌های خاص مشخص کنند.

سبک‌های نوشتارمتن

TextStyles زیر در M3 دردسترس است. این‌ها به‌طور پیش‌فرض توسط مؤلفه‌های مختلف M3 به‌کار گرفته می‌شوند.

شکل‌ها

سیستم شکل در M3 با M2.5 متفاوت است. تعداد پارامترهای شکل افزایش یافته است، نام آن‌ها متفاوت است، و به‌طور متفاوتی به مؤلفه‌های M3 نگاشت می‌شوند. اندازه‌های شکل زیر دردسترس است:

• بسیار کوچک
• کوچک
• متوسط
• بزرگ
• بسیار بزرگ

در Compose، این مورد برای کلاس M2.5 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 و معادل‌های Material 2.5 آن‌ها آورده شده است:

و درنهایت فهرستی از برخی مؤلفه‌های مرتبط از کتابخانه 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 در ۴ اندازه مختلف دردسترس است: خیلی کوچک، کوچک، متوسط، و بزرگ. EdgeButton پیاده‌سازی مقدار پیش‌فرضی برای maxLines بسته به اندازه ارائه می‌دهد که می‌تواند سفارشی‌سازی شود.

اگر از TransformingLazyColumn یا ScalingLazyColumn استفاده می‌کنید، EdgeButton را به ScreenScaffold منتقل کنید تا دگرگون شود و شکل آن با پیمایش تغییر کند، به‌جای اینکه EdgeButton را به‌عنوان آخرین مورد فهرست اضافه کنید. برای بررسی نحوه استفاده از EdgeButton با ScreenScaffold و 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

داربست

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

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

اگر از HorizontalPager با HorizontalPageIndicator استفاده می‌کنید، می‌توانید به HorizontalPagerScaffold مهاجرت کنید. HorizontalPagerScaffold در AppScaffold قرار داده شده است. AppScaffold و HorizontalPagerScaffold ساختار «ورق‌زن» را طرح‌بندی می‌کنند و انتقال‌های مؤلفه‌های HorizontalPageIndicator و TimeText را هماهنگ می‌کنند.

HorizontalPagerScaffold به‌طور پیش‌فرض HorizontalPageIndicator را در مرکز-انتهای صفحه نمایش می‌دهد و نمایش و پنهان کردن TimeText و HorizontalPageIndicator را براساس اینکه Pager درحال ورق زدن است یا نه هماهنگ می‌کند، این موضوع توسط PagerState تعیین می‌شود.

همچنین یک مؤلفه جدید AnimatedPage وجود دارد که صفحه‌ای را در یک Pager با جلوه مقیاس‌بندی و پرده براساس موقعیت آن پویانمایی می‌کند.

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

درنهایت، M3 یک VerticalPagerScaffold معرفی می‌کند که از همان الگوی 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

Placeholder

تغییراتی در میانای برنامه‌سازی کاربردی بین M2.5 و M3 وجود دارد. M3 دو اصلاح‌کننده جای‌بان ارائه می‌دهد:

• Modifier.placeholder، که به‌جای محتوایی که هنوز بار نشده است ترسیم می‌شود
• جلوه درخشان جای‌بان Modifier.placeholderShimmer که جلوه درخشان جای‌بانی را ارائه می‌دهد که درحین انتظار برای بار شدن داده‌ها، در حلقه پویانمایی اجرا می‌شود.

برای تغییرات بیشتر در مؤلفه Placeholder، جدول زیر را ببینید.

SwipeDismissableNavHost

‫SwipeDismissableNavHost بخشی از wear.compose.navigation است. وقتی از این مؤلفه با M3 استفاده می‌شود، M3 MaterialTheme LocalSwipeToDismissBackgroundScrimColor و LocalSwipeToDismissContentScrimColor را به‌روز می‌کند.

TransformingLazyColumn

TransformingLazyColumn بخشی از androidx.wear.compose.foundation.lazy است و پشتیبانی از پویانمایی‌های مقیاس‌بندی و دگردیسی را به موارد فهرست درحین پیمایش اضافه می‌کند، و تجربه کاربری را بهبود می‌بخشد. اکیداً توصیه می‌شود که برنامه‌ها از ScalingLazyColumn به TransformingLazyColumn منتقل شوند.

مشابه ScalingLazyColumn، rememberTransformingLazyColumnState() را برای ایجاد TransformingLazyColumnState ارائه می‌دهد که در ترکیب‌بندی‌ها به‌خاطر سپرده می‌شود.

برای افزودن پویانمایی‌های مقیاس‌بندی و دگردیسی، موارد زیر را به هر مورد فهرست اضافه کنید:

• Modifier.transformedHeight، که به شما امکان می‌دهد ارتفاع تبدیل‌شده موارد را بااستفاده از TransformationSpec محاسبه کنید، می‌توانید از rememberTransformationSpec() استفاده کنید، مگراینکه به سفارشی‌سازی بیشتری نیاز داشته باشید.
• یک 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
• Compose برای Wear OS codelab
• نمونه Jetcaster

مرجع میانای برنامه‌سازی کاربردی و کد منبع

• Compose Material 3 API reference
• نمونه‌های Compose Material 3 در کد منبع

طراحی

• راهنمای طراحی