تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

نظرة عامة على المكوّنات المُعرَّفة
الرسم البياني

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

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

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

ومع ذلك، يريد المصمّم والمطوّر أن يستخدم 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 عن ملفات الربط أثناء عملية الإنشاء.

ربط الملف في عرض
المشروع

إنشاء ملف ربط

يمكن أن ينشئ Relay ملف ربط لأي حزمة واجهة مستخدم مستورَدة. اتّبِع الخطوات التالية:

انقر بزر الماوس الأيمن على مجلد الحزمة أو أي ملف داخل المجلد ui-package الهدف. انقر على إنشاء ملف ربط.
اضبط الخيارات التالية في مربّع الحوار:
- موقع الملف: لضبط موقع ملف الربط الذي تم إنشاؤه.
- العنصر المخصّص المستهدَف: يحدّد العنصر المخصّص المستخدَم بدلاً من العنصر المخصّص الذي تم إنشاؤه. يمكنك استخدام ملف ملف محتوى قابل للتجميع حالي أو إنشاء ملف جديد من مربّع الحوار. يؤدي إنشاء ملف مكوّن جديد إلى إنشاء ملف مكوّن بالمَعلمات نفسها المحدّدة في حزمة واجهة المستخدم.
ملاحظة: يجب أن يبدأ العنصر المُركّب المستهدَف بحرف كبير.
- الملف الذي تم إنشاؤه: يضبط خيارَي generateImplementation و generatePreview في ملف الربط. اطّلِع على ربط محتوى الملف أدناه للحصول على مزيد من التفاصيل.
انقر على إنشاء ملف الربط. يتم إنشاء ملف ربط جديد داخل المجلد ui-package-resources/mapping باستخدام الإعدادات المحدّدة.

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

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

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

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

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

تعيين محتوى الملفات

يحتوي ملف الربط على السمات التالية:

‫target: (مطلوبة) اسم الدالة المخصّصة القابلة للتجميع. بشكلٍ تلقائي، هذا هو اسم الدالة التي تم إنشاؤها بواسطة الرمز الذي تم إنشاؤه.
```
"target" : "CustomComposableName"
```
‫package: (مطلوبة) اسم الحزمة التي يقع فيها العنصر المخصّص وتكون هذه الحزمة تلقائيًا حزمة الدالة التي تم إنشاؤها باستخدام التعليمات البرمجية التي تم إنشاؤها.
```
"package" : "com.example.podcastapp.ui.components"
```
‫generateImplementation: (اختياري) صحيح أو خطأ إذا كانت القيمة صحيحة، سيستمر إنشاء تنفيذ لحزمة واجهة المستخدم هذه في ملف الرمز المبرمَج الذي تم إنشاؤه. إذا كانت القيمة خطأ، لن يتم إنشاء عملية التنفيذ. يكون هذا الخيار صحيحًا تلقائيًا.
```
"generateImplementation" : true
```
‫generatePreviews: (اختياري) صحيح أو خطأ إذا كانت القيمة صحيحة، يتم إنشاء معاينة للوحدة المخصّصة المُضَمنة في ملف الرمز البرمجي الذي تم إنشاؤه. إذا كانت القيمة خطأ، لن يتم إنشاء معاينة. يكون هذا الخيار صحيحًا تلقائيًا.
```
"generatePreviews" : true
```

الأسعار المُحدَّدة

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

@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 في Relay.