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

حقول التكوين
| الحقل | مطلوب | الوصف |
|---|---|---|
universalIdentifier | نعم | معرّف فريد ثابت لهذا المكوّن |
component | نعم | دالة مكوّن React |
name | لا | اسم العرض |
description | لا | وصف لما يفعله المكوّن |
isHeadless | لا | عيِّنه إلى true إذا كان المكوّن بلا واجهة مرئية (انظر أدناه) |
command | لا | سجّل المكوّن كأمر (انظر خيارات الأوامر أدناه) |
وضع مكوّن أمامي على صفحة
إضافةً إلى الأوامر، يمكنك تضمين مكوّن أمامي مباشرةً في صفحة سجل عبر إضافته كودجت في تخطيط صفحة. راجع قسم 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
| الخطّاف | القيم المعادة | الوصف |
|---|---|---|
useUserId() | string أو null | معرّف المستخدم الحالي |
useRecordId() | string أو null | معرّف السجل الحالي (عند وضعه على صفحة سجل) |
useFrontComponentId() | string | معرّف مثيل هذا المكوّن |
useFrontComponentExecutionContext(selector) | يختلف | الوصول إلى سياق التنفيذ الكامل عبر دالة محدِّد |
واجهة الاتصال مع المضيف
يمكن للمكوّنات الأمامية تشغيل التنقّل والنوافذ المنبثقة والإشعارات باستخدام دوال منtwenty-sdk:
| دالة | الوصف |
|---|---|
navigate(to, params?, queryParams?, options?) | الانتقال إلى صفحة داخل التطبيق |
openSidePanelPage(params) | فتح لوحة جانبية |
closeSidePanel() | إغلاق اللوحة الجانبية |
openCommandConfirmationModal(params) | عرض مربع حوار تأكيد |
enqueueSnackbar(params) | عرض إشعار توست |
unmountFrontComponent() | إلغاء تركيب المكوّن |
updateProgress(progress) | تحديث مؤشّر التقدّم |
src/front-components/archive-record.tsx
خيارات الأوامر
إضافة حقلcommand إلى defineFrontComponent تُسجِّل المكوّن في قائمة الأوامر (Cmd+K). إذا كانت قيمة isPinned هي true، فسيظهر أيضًا كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة.
| الحقل | مطلوب | الوصف |
|---|---|---|
universalIdentifier | نعم | معرّف فريد ثابت للأمر |
label | نعم | التسمية الكاملة المعروضة في قائمة الأوامر (Cmd+K) |
shortLabel | لا | تسمية أقصر تُعرَض على زر الإجراء السريع المثبّت |
icon | لا | اسم الأيقونة المعروض بجانب التسمية (مثل 'IconBolt' و'IconSend') |
isPinned | لا | عند كونها true، يعرض الأمر كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة |
availabilityType | لا | تتحكّم في مكان ظهور الأمر: 'GLOBAL' (متاح دائمًا)، و'RECORD_SELECTION' (فقط عند تحديد سجلات)، أو 'FALLBACK' (يُعرَض عند عدم تطابق أي أوامر أخرى) |
availabilityObjectUniversalIdentifier | لا | تقييد الأمر بصفحات نوع كائن معيّن (مثل سجلات Company فقط) |
conditionalAvailabilityExpression | لا | تعبير منطقي للتحكم ديناميكيًا في ما إذا كان الأمر مرئيًا (انظر أدناه) |
تعابير الإتاحة الشرطية
يتيح لك الحقلconditionalAvailabilityExpression التحكّم في وقت ظهور الأمر بناءً على سياق الصفحة الحالي. استورد متغيّرات ومشغّلات مضبوطة الأنواع من twenty-sdk لبناء التعابير:
| المتغيّر | النوع | الوصف |
|---|---|---|
pageType | string | نوع الصفحة الحالي (مثل 'RecordIndexPage' و'RecordShowPage') |
isInSidePanel | boolean | ما إذا كان المكوّن معروضًا في لوحة جانبية |
numberOfSelectedRecords | number | عدد السجلات المحدّدة حاليًا |
isSelectAll | boolean | ما إذا كان “تحديد الكل” مفعّلًا |
selectedRecords | array | كائنات السجلات المحدّدة |
favoriteRecordIds | array | معرّفات السجلات المفضّلة |
objectPermissions | object | الأذونات الخاصة بنوع الكائن الحالي |
targetObjectReadPermissions | object | أذونات القراءة للكائن الهدف |
targetObjectWritePermissions | object | أذونات الكتابة للكائن الهدف |
featureFlags | object | أعلام الميزات المفعَّلة |
objectMetadataItem | object | بيانات التعريف لنوع الكائن الحالي |
hasAnySoftDeleteFilterOnView | قيمة منطقية | ما إذا كان العرض الحالي يحتوي على مرشّح حذف منطقي |
| المُشغِّل | الوصف |
|---|---|
isDefined(value) | true إذا لم تكن القيمة null/undefined |
isNonEmptyString(value) | true إذا كانت القيمة سلسلة غير فارغة |
includes(array, value) | true إذا كانت المصفوفة تحتوي على القيمة |
includesEvery(array, prop, value) | true إذا كانت خاصية كل عنصر تتضمن القيمة |
every(array, prop) | true إذا كانت الخاصية تُقيَّم بصحّة في كل عنصر |
everyDefined(array, prop) | true إذا كانت الخاصية معرّفة في كل عنصر |
everyEquals(array, prop, value) | true إذا كانت الخاصية تساوي القيمة في كل عنصر |
some(array, prop) | true إذا كانت الخاصية تُقيَّم بصحّة في عنصر واحد على الأقل |
someDefined(array, prop) | true إذا كانت الخاصية معرّفة في عنصر واحد على الأقل |
someEquals(array, prop, value) | true إذا كانت الخاصية تساوي القيمة في عنصر واحد على الأقل |
someNonEmptyString(array, prop) | true إذا كانت الخاصية سلسلة غير فارغة في عنصر واحد على الأقل |
none(array, prop) | true إذا كانت الخاصية تُقيَّم بخطأ في كل عنصر |
noneDefined(array, prop) | true إذا كانت الخاصية غير معرّفة في كل عنصر |
noneEquals(array, prop, value) | true إذا لم تكن الخاصية تساوي القيمة في أي عنصر |
الأصول العامة
يمكن للمكوّنات الأمامية الوصول إلى ملفات من دليل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