Skip to main content
المكوّنات الأمامية هي مكوّنات React تُعرَض مباشرة داخل واجهة مستخدم Twenty. تعمل ضمن Web Worker معزول باستخدام Remote DOM — تكون شيفرتك في صندوق عزل لكنها تُعرَض أصيلًا داخل الصفحة، وليس ضمن iframe.

أين يمكن استخدام مكوّنات الواجهة الأمامية

يمكن عرض مكوّنات الواجهة الأمامية في موقعين داخل Twenty:
  • اللوحة الجانبية — المكوّنات غير عديمة الرأس تفتح في اللوحة الجانبية اليمنى. هذا هو السلوك الافتراضي عندما يتم تشغيل مكوّن واجهة أمامية من قائمة الأوامر.
  • الويدجت (لوحات المعلومات وصفحات السجلات) — يمكن تضمين مكوّنات الواجهة الأمامية كويدجت داخل تخطيطات الصفحات. عند تكوين لوحة معلومات أو تخطيط صفحة سجل، يمكن للمستخدمين إضافة ويدجت لمكوّن واجهة أمامية.

مثال أساسي

أسرع طريقة لرؤية مكوّن أمامي قيد العمل هي تسجيله كأمر. إضافة حقل command مع isPinned: true يجعلُه يظهر كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة — دون الحاجة إلى تخطيط صفحة:
src/front-components/hello-world.tsx
بعد المزامنة باستخدام yarn twenty dev (أو تشغيل الأمر لمرة واحدة yarn twenty dev --once)، يظهر الإجراء السريع في الزاوية العلوية اليمنى من الصفحة:
زر إجراء سريع في الزاوية العلوية اليمنى
انقره لعرض المكوّن مضمنًا داخل الصفحة.

حقول التكوين

وضع مكوّن أمامي على صفحة

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

عديم الرأس مقابل غير عديم الرأس

تأتي مكوّنات الواجهة الأمامية بوضعَي عرض يتحكّم بهما الخيار isHeadless: غير عديم الرأس (افتراضي) — يعرض المكوّن واجهة مستخدم مرئية. عند تشغيله من قائمة الأوامر يفتح في اللوحة الجانبية. هذا هو السلوك الافتراضي عندما تكون isHeadless تساوي false أو يتم تجاهلها. عديم الرأس (isHeadless: true) — يتم تركيب المكوّن بشكل غير مرئي في الخلفية. لا يفتح اللوحة الجانبية. تم تصميم المكوّنات عديمة الرأس لإجراءات تنفّذ منطقًا ثم تُزيل تركيبها ذاتيًا — على سبيل المثال، تشغيل مهمة غير متزامنة، أو الانتقال إلى صفحة، أو إظهار نافذة تأكيد منبثقة. تتوافق بشكل طبيعي مع مكوّنات Command في SDK الموصوفة أدناه.
src/front-components/sync-tracker.tsx
نظرًا لأن المكوّن يُرجع null، فإن Twenty يتخطّى عرض حاوية له — ولن تظهر مساحة فارغة في التخطيط. لا يزال لدى المكوّن إمكانية الوصول إلى جميع الخطافات وواجهة برمجة الاتصال مع المضيف.

مكوّنات Command في SDK

توفر حزمة twenty-sdk أربعة مكوّنات مساعدة من نوع Command مصممة للمكوّنات عديمة الرأس في الواجهة الأمامية. كل مكوّن ينفّذ إجراءً عند التركيب، ويتعامل مع الأخطاء بعرض إشعار Snackbar، ويزيل تركيب مكوّن الواجهة الأمامية تلقائيًا عند الانتهاء. استوردها من twenty-sdk/command:
  • Command — يشغّل رد نداء غير متزامن عبر الخاصية execute.
  • CommandLink — ينتقل إلى مسار في التطبيق. الخصائص: to، params، queryParams، options.
  • CommandModal — يفتح نافذة تأكيد منبثقة. إذا أكّد المستخدم، ينفّذ رد النداء execute. الخصائص: title، subtitle، execute، confirmButtonText، confirmButtonAccent.
  • CommandOpenSidePanelPage — يفتح صفحة محدّدة في اللوحة الجانبية. الخصائص: page، pageTitle، pageIcon.
فيما يلي مثال كامل لمكوّن واجهة أمامية عديم الرأس يستخدم Command لتشغيل إجراء من قائمة الأوامر:
src/front-components/run-action.tsx
ومثال يستخدم CommandModal لطلب التأكيد قبل التنفيذ:
src/front-components/delete-draft.tsx

الوصول إلى سياق وقت التشغيل

داخل مكوّنك، استخدم خطافات SDK للوصول إلى المستخدم الحالي، والسجل، ومثيل المكوّن:
src/front-components/record-info.tsx
الخطافات المتاحة:

واجهة الاتصال مع المضيف

يمكن للمكوّنات الأمامية تشغيل التنقّل والنوافذ المنبثقة والإشعارات باستخدام دوال من twenty-sdk: فيما يلي مثال يستخدم واجهة برمجة تطبيقات المضيف لعرض Snackbar وإغلاق اللوحة الجانبية بعد اكتمال الإجراء:
src/front-components/archive-record.tsx

خيارات الأوامر

إضافة حقل command إلى defineFrontComponent تُسجِّل المكوّن في قائمة الأوامر (Cmd+K). إذا كانت قيمة isPinned هي true، فسيظهر أيضًا كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة.

تعابير الإتاحة الشرطية

يتيح لك الحقل conditionalAvailabilityExpression التحكّم في وقت ظهور الأمر بناءً على سياق الصفحة الحالي. استورد متغيّرات ومشغّلات مضبوطة الأنواع من twenty-sdk لبناء التعابير:
متغيّرات السياق — تُمثّل الحالة الحالية للصفحة: المُشغِّلات — جمّع المتغيّرات في تعابير منطقية:

الأصول العامة

يمكن للمكوّنات الأمامية الوصول إلى ملفات من دليل public/ للتطبيق باستخدام getPublicAssetUrl:
راجع قسم الأصول العامة للتفاصيل.

التنسيق

تدعم المكوّنات الأمامية عدة أساليب للتنسيق. يمكنك استخدام:
  • أنماط مضمنةstyle={{ color: 'red' }}
  • مكوّنات Twenty لواجهة المستخدم — استورد من twenty-sdk/ui (Button وTag وStatus وChip وAvatar وغيرها)
  • Emotion — CSS-in-JS مع @emotion/react
  • Styled-components — أنماط styled.div
  • Tailwind CSS — أصناف مساعدة
  • أي مكتبة CSS-in-JS متوافقة مع React