نقل البيانات من Material 2.5 إلى Material 3 في تطبيق Compose لنظام التشغيل Wear OS

‫Material 3 Expressive هو التطوّر التالي في التصميم المتعدد الأبعاد. يتضمّن هذا الإصدار ميزات محدّثة للتصميم والمكوّنات والتخصيص، مثل الألوان الديناميكية.

يركّز هذا الدليل على نقل البيانات من مكتبة Wear Compose Material 2.5 (androidx.wear.compose) Jetpack إلى مكتبة Wear Compose Material 3 (androidx.wear.compose.material3) Jetpack للتطبيقات.

الأساليب

لترحيل رمز تطبيقك من 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.

قدّم الإصدار 1.6.0 من مكتبة Wear Compose Foundation بعض المكوّنات الجديدة المصمّمة للعمل مع مكوّنات Material 3. وبالمثل، يتضمّن الرمز SwipeDismissableNavHost من مكتبة Wear Compose Navigation رسمًا متحركًا معدَّلاً عند تشغيله على الإصدار 6 من نظام التشغيل Wear OS (مستوى واجهة برمجة التطبيقات 36) أو الإصدارات الأحدث. عند التحديث إلى الإصدار 3 من Wear Compose Material، ننصحك أيضًا بتحديث مكتبتَي 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 ميزة جديدة هي سمات الألوان الديناميكية. إذا غيّر المستخدمون ألوان خلفية شاشة الساعة، ستتغيّر الألوان في واجهة المستخدم لتتطابق معها.

استخدِم الدالة 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، الذي يستخدم خطوطًا مرنة

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

الخطوط المتغيرة

تتيح الخطوط المرنة للمصمّمين تحديد عرض الخط ووزنه لأحجام معيّنة.

أنماط النص

تتوفّر TextStyles التالية في M3. تستخدم العديد من مكونات M3 هذه القيم تلقائيًا.

الشكل

يختلف نظام الأشكال في M3 عن M2.5. زاد عدد مَعلمات الأشكال، وأصبحت أسماؤها مختلفة، كما أنّها ترتبط بشكل مختلف بمكوّنات Material Design 3. تتوفّر أحجام الأشكال التالية:

• صغير جدًا
• صغير
• متوسط
• كبير
• كبير جدًا

في 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. يوفر تنفيذ 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.

تقدّم 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

سقالة

يختلف التصميم الأساسي في M3 عن M2.5. في الإصدار 3 من Material Design، تم استبدال Scaffold بـ AppScaffold وScreenScaffold الجديد القابل للإنشاء. تحدّد 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 مع تأثير التوسيع والتعتيم استنادًا إلى موضعها.

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

عنصر نائب

هناك بعض التغييرات في واجهة برمجة التطبيقات بين الإصدارين M2.5 وM3. توفّر Placeholder.PlaceholderDefaults الآن معدِّلَين:

• 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() ما لم تكن بحاجة إلى المزيد من التخصيص.
• ‫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

روابط مفيدة

لمزيد من المعلومات حول نقل البيانات من الإصدار 2.5 إلى الإصدار 3 من Material Design في Compose، يُرجى الاطّلاع على المراجع الإضافية التالية.

نماذج

• نماذج Wear OS على GitHub
• درس تطبيقي حول الترميز: Compose for Wear OS
• عيّنة Jetcaster

مرجع واجهة برمجة التطبيقات ورمز المصدر

• مرجع واجهة برمجة التطبيقات Compose Material 3
• إنشاء عيّنات من Material 3 في رمز المصدر

التصميم

• إرشادات التصميم