מעבר מ-Material 2.5 ל-Material 3 ב-Compose ל-Wear OS

‫Material 3 Expressive הוא השלב הבא בהתפתחות של Material Design. הוא כולל עיצובים, רכיבים ותכונות התאמה אישית מעודכנים, כמו צבע דינמי.

המדריך הזה מתמקד בהעברה של אפליקציות מספריית 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.6.0")

אפשר לראות את הגרסאות האחרונות של M3 בדף הגרסאות של Wear Compose Material 3.

בגרסה 1.6.0 של ספריית 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, ההגדרה הזו חלה על המחלקה 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, שמשתמש בגופני 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

גופנים גמישים מאפשרים למעצבים לציין את רוחב ומשקל הסוג לגדלים ספציפיים.

סגנונות טקסט

ב-M3 זמינים סגנונות הטקסט הבאים. הם מופעלים כברירת מחדל על ידי רכיבי M3 שונים.

צורה

מערכת הצורות ב-M3 שונה מזו שב-M2.5. מספר הפרמטרים של הצורה גדל, השמות שלהם שונים והמיפוי שלהם לרכיבי M3 שונה. אלה הגדלים של הצורות שזמינים:

• קטן במיוחד
• קטן
• בינוני
• גדול
• גדול במיוחד

במצב כתיבה, ההגדרה הזו חלה על מחלקת 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 מספקת ערכי ברירת מחדל ל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 כולל וריאציות חדשות של לחצנים. אפשר לעיין בהם בסקירה הכללית של הפניית API של Compose Material 3.

ב-M3 מוצג כפתור חדש: EdgeButton. ‫EdgeButton זמין ב-4 מידות שונות: אקסטרה סמול, סמול, מדיום ולרג'. ההטמעה של 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 ורכיב ה-Composable החדש 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 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

Placeholder

יש כמה שינויים ב-API בין M2.5 ל-M3. ‫Placeholder.PlaceholderDefaults כולל עכשיו שני משנים:

• ‫Modifier.placeholder, שמוצג במקום תוכן שעדיין לא נטען
• אפקט נצנוץ של placeholder‏ Modifier.placeholderShimmer שפועל בלולאת אנימציה בזמן ההמתנה לטעינת הנתונים.

בטבלה הבאה מפורטים שינויים נוספים ברכיב Placeholder.

SwipeDismissableNavHost

‫SwipeDismissableNavHost הוא חלק מ-wear.compose.navigation. כשמשתמשים ברכיב הזה עם M3, ‏ MaterialTheme של M3 מעדכן את 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

קישורים מועילים

כדי לקבל מידע נוסף על מעבר מ-M2.5 ל-M3 ב-Compose, אפשר לעיין במקורות המידע הנוספים הבאים.

דוגמיות

• דוגמאות ל-Wear OS ב-GitHub
• ‫Compose for Wear OS codelab
• דוגמה ל-Jetcaster

הפניית API וקוד מקור

• הפניית API של Compose Material 3
• דוגמאות לקוד מקור של Material 3

עיצוב

• הנחיות לעיצוב