در Compose for Wear OS از Material 2.5 به Material 3 مهاجرت کنید

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

این راهنما بر مهاجرت از کتابخانه جت‌پک Wear Compose Material 2.5 (androidx.wear.compose) به کتابخانه جت‌پک 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.6.0")

آخرین نسخه‌های M3 را در صفحه انتشار Wear Compose Material 3 مشاهده کنید.

کتابخانه Wear Compose Foundation نسخه ۱.۶.۰ برخی از اجزای جدید را معرفی کرد که برای کار با اجزای Material 3 طراحی شده‌اند. به طور مشابه، SwipeDismissableNavHost از کتابخانه Wear Compose Navigation هنگام اجرا روی 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، این موضوع در مورد کلاس Colors در M2.5، کلاس ColorScheme در M3 و توابع مرتبط صدق می‌کند:

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

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

• 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

فونت‌های فلکس

فونت‌های فلکس به طراحان این امکان را می‌دهند که عرض و ضخامت فونت را برای اندازه‌های خاص مشخص کنند.

سبک‌های متن

سبک‌های متن زیر در 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

از نگاشت پارامترهای Shapes از Migrate from Material 2 to Material 3 در Compose به عنوان نقطه شروع استفاده کنید.

تغییر شکل

M3 قابلیت Shape Morphing را معرفی می‌کند: شکل‌ها اکنون در پاسخ به تعاملات تغییر شکل می‌دهند.

رفتار Shape Morphing به عنوان یک تغییر در تعدادی از دکمه‌های گرد موجود است، لیست دکمه‌هایی که از Shape Morphing پشتیبانی می‌کنند را در زیر مشاهده کنید:

اجزا و طرح‌بندی

بیشتر اجزا و طرح‌بندی‌های M2.5 در M3 موجود هستند. با این حال، برخی از اجزا و طرح‌بندی‌های M3 در M2.5 وجود نداشتند. علاوه بر این، برخی از اجزای M3 نسبت به معادل‌های خود در M2.5 تنوع بیشتری دارند.

اگرچه برخی از اجزا نیاز به ملاحظات خاصی دارند، نگاشت‌های تابع زیر به عنوان نقطه شروع توصیه می‌شوند:

در اینجا لیست کاملی از تمام اجزای Material 3 آمده است:

و در نهایت لیستی از برخی کامپوننت‌های مرتبط از کتابخانه‌ی Wear Compose Foundation:

دکمه‌ها

دکمه‌ها در M3 با M2.5 متفاوت هستند. چیپ M2.5 با Button جایگزین شده است. پیاده‌سازی Button مقادیر پیش‌فرضی برای maxLines و textAlign Text ارائه می‌دهد. این مقادیر پیش‌فرض را می‌توان در عنصر 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,
    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 در M3 با M2.5 متفاوت است. در M3، AppScaffold و ترکیب جدید ScreenScaffold جایگزین Scaffold شده‌اند. AppScaffold و ScreenScaffold ساختار یک صفحه را طرح‌بندی می‌کنند و انتقال‌های کامپوننت‌های ScrollIndicator و TimeText را هماهنگ می‌کنند.

AppScaffold به عناصر ثابت صفحه نمایش مانند TimeText اجازه می‌دهد تا در طول انتقال‌های درون برنامه‌ای مانند کشیدن انگشت برای رد کردن، قابل مشاهده باقی بمانند. این ابزار، فضایی را برای محتوای اصلی برنامه فراهم می‌کند که معمولاً توسط یک کامپوننت ناوبری مانند SwipeDismissableNavHost ارائه می‌شود.

شما یک AppScaffold برای Activity تعریف می‌کنید و برای هر Screen از یک 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 اکنون دو اصلاح‌کننده ارائه می‌دهد:

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

برای تغییرات بیشتر در کامپوننت Placeholder به جدول زیر مراجعه کنید.

میزبان ناوبری قابل حذف با کشیدن انگشت

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

تبدیل ستون تنبل

TransformingLazyColumn بخشی از wear.compose.lazy.foundation است و پشتیبانی از مقیاس‌بندی و انیمیشن‌های تغییر شکل روی آیتم‌های لیست را در حین پیمایش اضافه می‌کند و تجربه کاربری را بهبود می‌بخشد. اکیداً توصیه می‌شود که برنامه‌ها از 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
• آهنگسازی برای Wear OS codelab
• نمونه جت کستر

مرجع API و کد منبع

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

طراحی

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