در 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 در یک برنامه واحد استفاده کنید.
• اتخاذ رویکرد مرحله‌ای

وابستگی‌ها

M3 بسته و نسخه جداگانه‌ای نسبت به M2.5 دارد:

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

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

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

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

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

تم

در هر دو 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 = AppColorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        motionScheme = AppMotionScheme,
        content = content
)

رنگ

سیستم رنگ در 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
)

جدول زیر تفاوت‌های کلیدی بین M2.5 و M3 را شرح می‌دهد:

تم رنگی پویا

یکی از ویژگی‌های جدید در M3 ، تم رنگی پویا است. اگر کاربران رنگ صفحه ساعت را تغییر دهند، رنگ‌های رابط کاربری نیز متناسب با آن تغییر می‌کنند.

از تابع dynamicColorScheme برای پیاده‌سازی طرح رنگ پویا استفاده کنید و یک defaultColorScheme به عنوان جایگزین در صورتی که طرح رنگ پویا در دسترس نباشد، ارائه دهید.

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

تایپوگرافی

سیستم تایپوگرافی در M3 با M2 متفاوت است و شامل ویژگی‌های زیر می‌شود:

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

• 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
)

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

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

سبک‌های متن

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

شکل

سیستم شکل در M3 با M2 متفاوت است. تعداد پارامترهای شکل افزایش یافته است، نام آنها متفاوت است و به طور متفاوتی به اجزای 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
)

از نگاشت پارامترهای 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 که اولین بار در نسخه 1.6.0-alpha04 معرفی شد:

دکمه‌ها

دکمه‌ها در M3 با M2.5 متفاوت هستند. چیپ M2.5 با Button جایگزین شده است. پیاده‌سازی Button مقادیر پیش‌فرضی برای maxLines و textAlign Text ارائه می‌دهد. این مقادیر پیش‌فرض را می‌توان در عنصر Text لغو کرد.

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

import androidx.wear.compose.material3.Button

//M3 Buttons
Button(...)
CompactButton(...)
IconButton(...)
TextButton(...)

M3 همچنین شامل انواع جدیدی از دکمه‌ها است. می‌توانید آنها را در نمای کلی مرجع Compose Material 3 API بررسی کنید.

M3 یک دکمه جدید معرفی می‌کند: EdgeButton . EdgeButton در ۴ اندازه مختلف موجود است: خیلی کوچک، کوچک، متوسط ​​و بزرگ. پیاده‌سازی EdgeButton یک مقدار پیش‌فرض برای maxLines بسته به اندازه ارائه می‌دهد که می‌تواند سفارشی‌سازی شود.

اگر از TransformingLazyColumn و ScalingLazyColumn استفاده می‌کنید، EdgeButton به ScreenScaffold ارسال کنید تا با اسکرول کردن، شکل آن تغییر کند. برای بررسی نحوه استفاده از EdgeButton با ScreenScaffold و TransformingLazyColumn ، به کد زیر مراجعه کنید.

import androidx.wear.compose.material3.EdgeButton
import androidx.wear.compose.material3.ScreenScaffold

ScreenScaffold(
   scrollState = state,
   contentPadding = contentPadding,
   edgeButton = {
      EdgeButton(...)
   }
){ contentPadding ->
   TransformingLazyColumn(state = state, contentPadding = contentPadding,){
   // additional code here
   }
}

داربست

Scaffold در M3 با M2.5 متفاوت است. در M3، AppScaffold و ترکیب جدید ScreenScaffold جایگزین Scaffold شده‌اند. AppScaffold و ScreenScaffold ساختار یک صفحه را طرح‌بندی می‌کنند و انتقال‌های کامپوننت‌های ScrollIndicator و TimeText را هماهنگ می‌کنند.

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

شما یک AppScaffold برای Activity تعریف می‌کنید و برای هر Screen از یک ScreenScaffold استفاده می‌کنید.

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 پیروی می‌کند:

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.VerticalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

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

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

جایگذار

برخی تغییرات 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 ، این متد rememberTransformingLazyColumnState() را برای ایجاد یک TransformingLazyColumnState که در بین ترکیب‌ها به خاطر سپرده می‌شود، فراهم می‌کند.

برای افزودن انیمیشن‌های تغییر مقیاس و شکل‌دهی، موارد زیر را به هر مورد لیست اضافه کنید:

• Modifier.transformedHeight که به شما امکان می‌دهد ارتفاع تبدیل‌شده‌ی آیتم‌ها را با استفاده از TransformationSpec محاسبه کنید، می‌توانید rememberTransformationSpec() استفاده کنید، مگر اینکه به سفارشی‌سازی بیشتری نیاز داشته باشید.
• یک SurfaceTransformation

val columnState = rememberTransformingLazyColumnState()
val contentPadding = rememberResponsiveColumnPadding(
    first = ColumnItemType.ListHeader,
    last = ColumnItemType.Button,
)
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState,
    contentPadding = contentPadding
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                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 در کد منبع

طراحی

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