نقل تصميمات XML إلى Material 3 في Compose

عند استخدام Compose في تطبيق حالي، عليك نقل مظاهر Material XML لاستخدام MaterialTheme لمكوّنات Compose. هذا يعني أنّ تطبيقك سيتضمّن مصدرَين أساسيَّين للمظهر: المظهر المستنِد إلى العرض ومظهر 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 View. تحليل مسار نقل البيانات والخطوات اللازمة لنقل نظام التصميم الحالي إلى 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 في رمز Compose لتكرار أنماط نص 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، بل يتم تمرير الأنماط على النحو التالي: مَعلمات أو مُعدِّلات للدوال المركّبة، باستخدام واجهة برمجة التطبيقات الجديدة التجريبية للأنماط المحدّدة في AppTheme، أو من خلال إنشاء صيغ دوال مركّبة ذات طبقات وقابلة لإعادة الاستخدام بالنمط المحدّد.

قدِّم دوال مركّبة @Composable منفصلة تتم تسميتها وفقًا للنمط والمكوّن الأساسي، للإشارة إلى الاختلاف في الأنماط وحالات الاستخدام لهذه المكوّنات.

  • النمط: إذا كان عنصر XML يستخدم نمطًا مخصّصًا (مثل style="@style/MyPrimaryButton")، لا تحاول تكرار النمط في السطر. بدلاً من ذلك، اقترح إنشاء دالة مركّبة محددة.
  • مثال:
    • ‫XML: <Button style="@style/MyPrimaryButton" ... />
    • إنشاء: MyPrimaryButton(onClick = { ... })
  • مجموعات السمات الشائعة: إذا كان النمط يحدّد معدِّلات شائعة (مثل المساحة المتروكة والارتفاع)، يمكنك استخراجها إلى سمة إضافة قابلة للقراءة أو متغيّر معدِّل مشترك.

أمثلة شائعة

تنسيق 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 الأصلي كمصدر موثوق لتخصيص التصميم المتعدد الأبعاد الجديد في Compose. لا تبتكر أبدًا قيمًا جديدة للمظهر أثناء عملية النقل، وذلك للحفاظ على اتساق العلامة التجارية وتجنُّب التراجعات المرئية.

تأكَّد من أنّ جميع قيم المظاهر الجديدة في Compose تتطابق مع قيم XML الحالية. لا تضع أي قيم تم نقلها في الرمز البرمجي.