ربط المكوّنات بالرمز الحالي

يمكن للمطوّرين تخصيص عملية إنشاء الرموز من خلال توفير عملية ربط بين حزمة واجهة المستخدم ومكوِّن رمز حالي بدلاً من الرمز الذي تم إنشاؤه. يكون هذا مفيدًا عندما يتضمّن التنفيذ الحالي ميزات لا يمكن تحقيقها باستخدام الرمز البرمجي الذي تم إنشاؤه، مثل الرسوم المتحركة أو السلوك المعقد (مثل القائمة المنسدلة).

يحدد المطورون كيفية ربط المكونات باستخدام ملف تعيين. يخبر ملف التعيين منشئ التعليمات البرمجية، على الأقل، بكيفية الوصول إلى الدالة القابلة للإنشاء المستهدفة، بحيث يمكن إنشاء رمز العميل الصحيح.

يُرجى الاطّلاع على المثال أدناه:

في Figma، ينشئ مصمم مكون بطاقة يحتوي على مثيل للمكون Play Bar، ويحزم كلا المكونين، ويرسلهما إلى أحد مطوري البرامج.

عندما يستورد المطوّر حزم واجهة المستخدِم من Figma، يتمّ إنشاء دليلَين في ui-packages: card وplay_bar. عند إنشاء المشروع، يتم إنشاء دالتَين قابلتَين للإنشاء: Card وPlayBar عادةً، لأن البطاقة تحتوي على مثيل Play Bar في Figma، تحتوي الدالة Card القابلة للإنشاء على استدعاء الدالة PlayBar القابلة للإنشاء.

ومع ذلك، يريد المصمم والمطوّر أن يستخدم Card بدلاً من ذلك عنصر MyExistingPlaybar الحالي القابل للإنشاء، والذي يحتوي على وظائف يصعب وصفها في Figma. لذلك، يضيف المطوّر ملف ربط يُسمى play_bar.json يعيّن حزمة واجهة المستخدم play_bar إلى MyExistingPlaybar:

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

والآن، عندما ينشئ المطوّر المشروع، يطلب Card الرمز MyExistingPlaybar بدلاً من PlayBar. تجدر الإشارة إلى أنّ MyExistingPlaybar يجب أن يتضمّن المعلَمات نفسها مثل PlayBar (مع أنّه قد يكون هناك بعض الاختلافات، كما هو موضّح في الإرشادات الإضافية أدناه).

ملف التعيين

في مشاريع "استوديو Android"، تتم إضافة ملفات الربط ضمن ui-package-resources/mappings بجانب مجلد ui-packages. يبحث تطبيق Relay عن ملفات التعيين أثناء الإنشاء.

إنشاء ملف تعيين

يمكن للإرسال إنشاء ملف تعيين لأي حزمة واجهة مستخدم تم استيرادها. اتبع هذه الخطوات:

1. انقر بزر الماوس الأيمن على مجلد الحزمة أو أي ملف داخل مجلد ui-package الهدف. اختَر إنشاء ملف ربط.

   

2. اضبط الخيارات التالية في مربّع الحوار:

   

   • موقع الملف: لتحديد موقع ملف التعيين الذي تم إنشاؤه.

   • عنصر قابل للإنشاء المستهدف: يضبط عنصر قابل للإنشاء المخصّص الذي يتم استخدامه بدلاً من العنصر القابل للإنشاء الذي تم إنشاؤه. يمكنك استخدام عنصر قابل للإنشاء أو إنشاء عنصر جديد من مربّع الحوار. يؤدي إنشاء عنصر جديد قابل للإنشاء إلى إنشاء عنصر قابل للإنشاء بنفس المعلمات كما هو محدد في حزمة واجهة المستخدم.

   ملاحظة: يجب أن يبدأ عنصر الهدف القابل للإنشاء بحرف كبير.
   • الملف الذي تم إنشاؤه: يضبط خيارَي generateImplementation وgeneratePreview في ملف الربط. راجِع ربط محتوى الملف أدناه للاطّلاع على مزيد من التفاصيل.

3. انقر على إنشاء ملف ربط. يتم إنشاء ملف ربط جديد داخل مجلد ui-package-resources/mapping بالإعدادات المحددة.

يمكنك أيضًا فتح مربّع الحوار إنشاء ملف تعيين من واجهة مستخدم وحدة حزمة الإرسال باتّباع الخطوات التالية:

1. انقر على أي ملف لحزمة واجهة المستخدم داخل مجلد ui-package الهدف.

2. إذا لم يتم فتح نافذة أداة الإرسال تلقائيًا، فانقر على رمز الإرسال لفتح النافذة.

3. انقر على الزر إنشاء ملف تعيين ضمن خيارات الحزمة.

   

   ملاحظة: في حال توفُّر ملف ربط لحزمة واجهة المستخدم المحددة، سيتم عرض رابط لفتح الملف بدلاً من ذلك.

اسم ملف التعيين

يجب أن يتطابق اسم ملف تعيين معين مع اسم مجلد حزمة واجهة المستخدم للمكون الذي يستبدله. وبالتالي، يعيّن play_bar.json حزمة واجهة المستخدم في المجلد ui-packages/mappings إلى مكوّن رمز حالي.

محتوى ملف الربط

يحتوي ملف التعيين على السمات التالية:

• target: (مطلوبة) اسم الدالة المخصّصة القابلة للإنشاء. بشكل افتراضي، هذا هو اسم الدالة التي تم إنشاؤها بواسطة التعليمات البرمجية التي تم إنشاؤها.

  "target" : "CustomComposableName"
  

• package: (مطلوبة) اسم الحزمة المضمّنة في العنصر القابل للإنشاء المخصّص. بشكل افتراضي، هذه هي حزمة الدالة التي تم إنشاؤها من خلال التعليمات البرمجية التي تم إنشاؤها.

  "package" : "com.example.podcastapp.ui.components"
  

• generateImplementation: (اختياري) true أو false. إذا كانت الإجابة صحيحة، فلا يزال يتم إنشاء تنفيذ لحزمة واجهة المستخدم هذه في ملف التعليمة البرمجية الذي تم إنشاؤه. وفي حال اختيار القيمة "false"، لن يتم إنشاء عملية التنفيذ. ويكون هذا صحيحًا تلقائيًا.

  "generateImplementation" : true
  

• generatePreviews: (اختياري) true أو false. إذا كانت القيمة "true"، يتم إنشاء معاينة للمكون المخصص المعين في ملف التعليمات البرمجية الذي تم إنشاؤه. إذا كانت القيمة "false"، فلن يتم إنشاء معاينة. ويكون هذا صحيحًا تلقائيًا.

  "generatePreviews" : true
  

الصيغ المرتبطة

إذا كان لمكوِّن Figma متغيرات، فإن العنصر القابل للإنشاء يحتوي على معلمات تعداد تعمل على ترميز المتغير (كما هو موضح في البرنامج التعليمي Handling Design Variants). إذا كنت ترغب في تعيين مكون Figma بمتغيرات مع التعليمات البرمجية الموجودة، فيجب تعيينه إلى عنصر قابل للإنشاء يأخذ نفس المعلمات مثل الكائن القابل للإنشاء الذي تم إنشاؤه. على سبيل المثال، بالنسبة إلى أحد مكونات Figma يُسمى Chip مع متغيّر تكون خاصته ChipType، فإن التوقيع القابل للإنشاء الذي أنشأه Chip يبدو على النحو التالي:

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

إذا كنت تريد تعيين عنصر Chip Figma إلى عنصر MyChip قابل للإنشاء، يجب أن يتضمّن توقيع MyChip نفس التوقيع القابل للإنشاء الذي تم إنشاؤه (بافتراض عدم تحديد أي توجيهات إضافية). من الناحية النظرية، يشير هذا إلى أن مكون التعليمات البرمجية الحالي قادر على نفس متغيرات التصميم مثل مكون Figma.

توجيهات إضافية

على سبيل المثال، إذا كانت الدالة القابلة للإنشاء التي تريد استهدافها تحمل التوقيع التالي:

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

يمكنك إضافة مجموعة fieldMappings إلى ملف الربط الذي يؤثّر في كيفية ربط المَعلمات. في هذه الحالة، يحتوي الحقل على تعيين من المَعلمة chipText في Chip إلى المَعلمة description في MyChip.

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

تشمل أنواع مجموعة fieldMappings ما يلي:

• parameter: يربط حقل حزمة واجهة المستخدم بمَعلمة رمز.
  • source: اسم المَعلمة على النحو المحدّد في حزمة واجهة المستخدم
  • target: اسم المَعلمة على النحو المحدّد في مكوّن الرمز المستهدَف
• lambda: تربط حقل حزمة واجهة المستخدم بحقل lambda للمحتوى.
  • source: اسم المَعلمة على النحو المحدّد في حزمة واجهة المستخدم
  • target: اسم المَعلمة على النحو المحدّد في مكوّن الرمز المستهدَف

• modifier: يربط حقل حزمة واجهة المستخدم إلى طريقة معدِّل.

  ملاحظة: يتم اعتماد هذا النوع من عمليات الربط، لا سيما التعامل مع نطاقات المستلِمين.
  • source: اسم المَعلمة على النحو المحدّد في حزمة واجهة المستخدم
  • method: الطريقة على كائن التعديل الذي يجب استدعاؤه في الرمز الذي تم إنشاؤه.
  • parameter: اسم المَعلمة ضمن طريقة "المعدِّل" المحدّدة
  • library: اسم الحزمة المؤهلة المطلوب استيرادها للوصول إلى طريقة التعديل.
  • scope: إحدى القيمتين اللتين تشيران إلى نطاق "المعدِّل":
  • any: يمكن استخدام المحرِّر في أي نطاق للمستلِم.
  • relay: يجب استخدام المعدِّل في نطاق المستلِم لكائن RelayContainer الخاص بالإرسال.