نقل تصميمات 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، والذي يستخدمه نظام View

القيود

قبل نقل البيانات، يُرجى الانتباه إلى القيود التالية:

  • يركّز هذا الدليل على نقل البيانات إلى 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 في رمز 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 = { ... })
  • مجموعات السمات الشائعة: إذا كان أحد الأنماط يضبط معدِّلات شائعة (مثل المساحة المتروكة والارتفاع)، استخرِجها إلى سمة إضافة قابلة للقراءة أو متغيّر 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 الأصلي كمصدر للحصول على معلومات صحيحة بشأن مظهر Material الجديد في Compose. لا تنشئ أبدًا قيمًا جديدة للسمات أثناء نقل البيانات للحفاظ على اتساق العلامة التجارية وتجنُّب المشاكل المرئية.

تأكَّد من أنّ جميع قيم سمة Compose الجديدة تتطابق مع قيم XML الحالية. لا تبرمج أي قيم تم نقلها بشكل ثابت.