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

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

يركّز هذا الدليل على نقل البيانات من مكتبة 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 في تطبيق واحد على المدى الطويل
• اتّبِع نهجًا تدريجيًا

التبعيات

يحتوي M3 على حزمة وإصدار منفصلَين عن M2.5:

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

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

يمكنك الاطّلاع على أحدث إصدارات M3 في صفحة إصدارات Wear Compose Material 3.

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

implementation("androidx.wear.compose:compose-foundation:1.6.0-alpha03")
implementation("androidx.wear.compose:compose-navigation:1.6.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 = AppColorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        motionScheme = AppMotionScheme,
        content = content
)

اللون

يختلف نظام الألوان في 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
)

يوضّح الجدول التالي الاختلافات الرئيسية بين الإصدارَين M2.5 وM3:

تطبيق مظهر "الألوان الديناميكية"

تتضمّن M3 ميزة جديدة هي سمات الألوان الديناميكية. إذا غيّر المستخدمون ألوان خلفية شاشة الساعة، ستتغيّر الألوان في واجهة المستخدم لتتطابق معها.

استخدِم الدالة dynamicColorScheme لتنفيذ نظام ألوان ديناميكي وتوفير defaultColorScheme كخيار احتياطي في حال عدم توفّر نظام الألوان الديناميكي.

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

أسلوب الخط

يختلف نظام الطباعة في M3 عن M2 ويتضمّن الميزات التالية:

• تسعة أنماط نص جديدة
• الخطوط المرنة التي تتيح تخصيص مقاييس الخطوط لأوزان وعرض واستدارة مختلفة

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

خطوط مرنة

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

أنماط النص

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

الشكل

يختلف نظام الأشكال في M3 عن M2. زاد عدد مَعلمات الأشكال، وأصبحت أسماؤها مختلفة، كما أنّها ترتبط بشكل مختلف بمكوّنات 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
)

استخدِم عملية ربط مَعلمات الأشكال من نقل البيانات من Material 2 إلى Material 3 في Compose كنقطة بداية.

تغيير شكل الكائن

تقدّم M3 ميزة "تغيير الشكل": تتغيّر الأشكال الآن استجابةً للتفاعلات.

يتوفّر سلوك "تغيير الشكل" كصيغة لعدد من الأزرار الدائرية، ويمكنك الاطّلاع على قائمة الأزرار التالية التي تتيح ميزة "تغيير الشكل":

المكوّنات والتنسيق

تتوفّر معظم المكوّنات والتصاميم من M2.5 في M3. ومع ذلك، لم تكن بعض مكوّنات وتنسيقات M3 متوفّرة في M2.5. بالإضافة إلى ذلك، تتضمّن بعض مكوّنات M3 خيارات أكثر من تلك المتوفّرة في M2.5.

مع أنّ بعض المكوّنات تتطلّب مراعاة اعتبارات خاصة، يُنصح باستخدام عمليات الربط التالية بين الدوال كنقطة بداية:

في ما يلي قائمة كاملة بجميع عناصر Material 3:

وأخيرًا، إليك قائمة ببعض المكوّنات ذات الصلة من مكتبة Wear Compose Foundation التي تم طرحها لأول مرة في الإصدار 1.6.0-alpha03:

الأزرار

تختلف الأزرار في M3 عن M2.5. تم استبدال شريحة M2.5 بـ Button. يوفر تنفيذ Button قيمًا تلقائية لكل من Text وmaxLines وtextAlign. يمكن تجاهل هذه القيم التلقائية في العنصر 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.

تقدّم لك "الإصدار 3 من Material" زرًا جديدًا: 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
   }
}

سقالة

يختلف التصميم الأساسي في M3 عن التصميم الأساسي في M2.5. في M3، تم استبدال Scaffold بـ AppScaffold وScreenScaffold الجديد القابل للإنشاء. تحدّد AppScaffold وScreenScaffold بنية الشاشة وتنسّق عمليات الانتقال بين المكوّنين ScrollIndicator وTimeText.

تسمح AppScaffold ببقاء عناصر الشاشة الثابتة، مثل TimeText، مرئية أثناء عمليات الانتقال داخل التطبيق، مثل التمرير سريعًا لإغلاق الشاشة. ​​يوفر هذا العنصر مساحة لعرض المحتوى الرئيسي للتطبيق، والذي سيتم توفيره عادةً من خلال أحد مكونات التنقل، مثل SwipeDismissableNavHost

عليك تعريف AppScaffold واحد للنشاط واستخدام 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 مع تأثير التوسيع والتعتيم استنادًا إلى موضعها.

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 {
        …
   }
}

عنصر نائب

هناك بعض التغييرات في واجهة برمجة التطبيقات بين الإصدارين 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، يوفّر 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

روابط مفيدة

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

نماذج

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

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

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

التصميم

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