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

عند إضافة Compose إلى تطبيق حالي، عليك نقل سمات Material XML لاستخدام MaterialTheme لمكوّنات Compose. وهذا يعني أنّ تصميم تطبيقك سيستند إلى مصدرَين للحقيقة، وهما التصميم المستند إلى العرض والتصميم المستند إلى Compose. يجب إجراء أي تغييرات على الأنماط في مواضع متعددة. بعد نقل تطبيقك بالكامل إلى Compose، أزِل تصميم XML.

يمكنك استخدام أداة Material Theme Builder لنقل الألوان.

عند بدء عملية نقل البيانات من XML إلى Compose، عليك نقل نظام التصميم إلى نظام التصميم المتوافق مع Material 3 في Compose.

مسرد المصطلحات

العبارة التعريف
MaterialTheme الدالة القابلة للإنشاء التي توفّر السمات (الألوان وأسلوب الخط والأشكال) لمكوّنات واجهة مستخدم Compose
Shape أحد عناصر Compose المستخدَمة لتحديد أشكال مخصّصة للمكوّنات في MaterialTheme
Typography عنصر Compose يُستخدَم لتحديد أنماط نص مخصّصة (مجموعات الخطوط وأحجامها وأوزانها) لعنصر MaterialTheme.
Color كائن 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، حدِّد كائن Shape لتكرار تعريفات شكل XML.

    2. قدِّم عنصر Shape هذا إلى 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.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) معرَّف في Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.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 الحالية. لا تبرمج أي قيم تم نقلها بشكل ثابت.