نقل تصميمات 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 لتكرار أنماط النص وتعريفات الخطوط في تنسيق XML.

    2. قدِّم كائن Typography هذا إلى MaterialTheme.

      لمزيد من التفاصيل، يُرجى الاطّلاع على أسلوب الخط.

الدور في Compose الاسم في 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 View
  2. ضبط النمط بشكل غير مباشر وضمني لمكوّن كجزء من سمة أكبر (theme.xml)

لا تتوفّر أنماط مكافئة مباشرةً في Compose، ولكن يتم بدلاً من ذلك تمرير الأنماط كـ: مَعلمات أو معدِّلات إلى الدوال القابلة للإنشاء، باستخدام Styles API التجريبية الجديدة المحدّدة في AppTheme، أو من خلال إنشاء أشكال مختلفة قابلة للإنشاء وقابلة لإعادة الاستخدام ومتراكبة مع النمط المحدّد.

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

  • النمط: إذا كان أحد عناصر XML يستخدم نمطًا مخصّصًا (مثل style="@style/MyPrimaryButton")، لا تحاول تكرار النمط مضمّنًا. بدلاً من ذلك، ننصحك بإنشاء دالة قابلة للإنشاء محدّدة.
  • مثال:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: 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 الحالية. لا تبرمج أي قيم تم نقلها بشكل ثابت.