העברת עיצובים ב-XML ל-Material 3 ב-Compose

כשמציגים את Compose באפליקציה קיימת, צריך להעביר את העיצובים של Material XML כדי להשתמש ב-MaterialTheme לרכיבי Compose. זה אומר שלעיצוב של האפליקציה יהיו שני מקורות מידע: העיצוב שמבוסס על View והעיצוב של Compose. אם רוצים לשנות את העיצוב, צריך לעשות את זה בכמה מקומות. אחרי שהאפליקציה תועבר באופן מלא ל-Compose, הסירו את העיצוב ב-XML.

אתם יכולים להשתמש בכלי Material Theme Builder כדי להעביר צבעים.

כשמתחילים את ההעברה מ-XML ל-Compose, צריך להעביר את העיצוב לעיצוב של Material 3 Compose.

מילון מונחים

מונח הגדרה
MaterialTheme הפונקציה הקומפוזבילית שמספקת עיצוב (צבעים, טיפוגרפיה, צורות) לרכיבי ממשק המשתמש של Compose.
Shapes אובייקט Compose שמשמש להגדרת צורות של רכיבים בהתאמה אישית ל-MaterialTheme.
Typography אובייקט Compose שמשמש להגדרת סגנונות טקסט בהתאמה אישית (משפחות גופנים, גדלים, משקלים) ל-MaterialTheme.
ColorScheme אובייקט Compose שמשמש להגדרת ערכות צבעים בהתאמה אישית ל-MaterialTheme.
עיצוב XML מערכת העיצוב של Android שמוגדרת בקובצי XML, ומשמשת את מערכת התצוגה.

מגבלות

לפני שמעבירים את הנתונים, חשוב לשים לב למגבלות הבאות:

  • המדריך הזה מתמקד רק במעבר ל-Material 3. כדי לעבור ממערכות עיצוב חלופיות, כדאי לעיין במאמרים Material 2 או מערכות עיצוב בהתאמה אישית ב-Compose.
  • המטרה הסופית היא מעבר מלא ל-Compose, שמאפשר להסיר את העיצוב ב-XML. במדריך הזה מוסבר איך לבצע את ההעברה, אבל לא מוסבר איך להסיר בסופו של דבר את העיצוב ב-XML.

שלב 1: בודקים את מערכת העיצוב

מזהים באיזו מערכת עיצוב משתמשים בפרויקט של תצוגת ה-XML. לנתח את נתיב ההעברה ואת השלבים הנדרשים כדי להעביר את מערכת העיצוב הקיימת ל-Material 3 ב-Compose.

שלב 2: זיהוי קובצי המקור של העיצוב

ב-XML כותבים ?attr/colorPrimary. ב-Compose, ניגשים לערכי העיצוב באמצעות MaterialTheme.*:

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

אפשר להשתמש שוב במשאבים כמו מחרוזות, ואין צורך להעביר אותם.

שלב 3: העברת הצבעים

עיקרון מרכזי: ב-XML משתמשים בקודי צבע הקסדצימליים עם שמות. ב-Material 3 משתמשים בתפקידים סמנטיים (למשל, primary,‏ onPrimary,‏ surface). הפסיקו לתת שמות לצבעים לפי הקוד ההקסדצימלי שלהם, ותנו להם שמות לפי התפקיד שלהם.

דוגמאות:

שם הצבע ב-XML תפקיד ב-Material 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer או secondary
colorAccent secondary או tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

מעבירים את ערכות הצבעים הכהות והבהירות מ-XML למקבילות שלהן ב-Material 3 Compose.

שלב 4: העברת צורות וטיפוגרפיה בהתאמה אישית

  • אם באפליקציה שלכם יש צורות בהתאמה אישית:

    1. בקוד של Compose, מגדירים אובייקט Shapes כדי לשכפל את הגדרות הצורה ב-XML.

    2. צריך לספק את האובייקט Shapes ל-MaterialTheme.

      מידע נוסף זמין במאמר בנושא צורות.

  • אם באפליקציה שלכם נעשה שימוש בטיפוגרפיה בהתאמה אישית:

    1. בקוד של Compose, מגדירים אובייקט Typography כדי לשכפל את סגנונות הטקסט והגדרות הגופנים של ה-XML.

    2. צריך לספק את האובייקט Typography ל-MaterialTheme.

      מידע נוסף זמין במאמר בנושא טיפוגרפיה.

תפקיד כתיבה שם ה-XML
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

שלב 5: העברת סגנונות (styles.xml)

מערכת סגנונות ה-XML‏ (styles.xml) מגדירה את הסגנונות והמראה של:

  1. ווידג'טים, רכיבים, עיצובים לחלונות ולתיבות דו-שיח
  2. טיפוגרפיה
  3. עיצובים ושכבות-על
  4. צורות

תצוגות ורכיבים של XML משלבים כמה מאפיינים כדי ליצור סגנון. הם מגדירים את הסגנונות שלהם מ-styles.xml בשתי דרכים שונות:

  1. הגדרת "style="@style/..." ישירות ובאופן מפורש בתצוגת ה-XML
  2. הגדרת הסגנון באופן עקיף ומרומז לרכיב כחלק מעיצוב גדול יותר (theme.xml)

לסגנונות אין מקבילה ישירה ב-Compose. במקום זאת, הסגנונות מועברים כפרמטרים או כמשתני שינוי לפונקציות ה-composable, באמצעות ה-Styles API החדש והניסיוני שמוגדר ב-AppTheme, או על ידי יצירת וריאציות של פונקציות composable בשכבות שניתן לעשות בהן שימוש חוזר עם הסגנון המוגדר.

צריך לספק פונקציות קומפוזביליות ‎ @Composable נפרדות שנקראות לפי הסגנון והרכיב הבסיסי, כדי לציין את ההבדל בסגנון ובמקרי השימוש של הרכיבים האלה.

  • תבנית: אם רכיב XML משתמש בסגנון אישי (למשל, style="@style/MyPrimaryButton"), אל תנסו לשכפל את הסגנון בתוך השורה. במקום זאת, הציעו ליצור פונקציה קומפוזבילית ספציפית.
  • לדוגמה:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • כתיבה: MyPrimaryButton(onClick = { ... })
  • קבוצות של מאפיינים נפוצים: אם סגנון מסוים מגדיר משתני שינוי נפוצים (כמו מרווח פנימי + גובה), מחלצים אותם למאפיין של תוסף קריא או למשתנה Modifier משותף.

דוגמאות נפוצות

XML אימייל חדש
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium ‫TextStyle(...) מוגדר ב-Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint containerColor ב-ComponentDefaults.ComponentColors()
android:textColor contentColor ב-ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) או Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp ב-TextStyle

שלב 6: אימות העברת העיצוב

תמיד צריך להשתמש בערכי העיצוב הקיימים מעיצוב ה-XML המקורי כמקור האמת להתאמת העיצוב של Google Material Design החדשה ב-Compose. כדי לשמור על עקביות המותג ולמנוע רגרסיות חזותיות, אל תמציאו ערכי עיצוב חדשים במהלך ההעברה.

מוודאים שכל ערכי העיצוב החדשים ב-Compose תואמים לערכי ה-XML הקיימים. אל תגדירו ערכים מועברים בתוך הקוד.