المكوّنات الأمامية

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

لا تزال مكوّنات Front قيد التطوير النشط. يعمل الكود الخاص بك على DOM جزئي، وليس على صفحة متصفح حقيقية، لذلك يمكن أن تفشل الاستخدامات المتقدمة، وغالبًا من دون أي إشعار. راجع القيود الحالية.

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

يمكن عرض مكوّنات الواجهة الأمامية في ثلاثة مواقع داخل Twenty:

اللوحة الجانبية — المكوّنات غير عديمة الرأس تفتح في اللوحة الجانبية اليمنى. هذا هو السلوك الافتراضي عندما يتم تشغيل مكوّن واجهة أمامية من قائمة الأوامر.
الويدجت (لوحات المعلومات وصفحات السجلات) — يمكن تضمين مكوّنات الواجهة الأمامية كويدجت داخل تخطيطات الصفحات. عند تكوين لوحة معلومات أو تخطيط صفحة سجل، يمكن للمستخدمين إضافة ويدجت لمكوّن واجهة أمامية.
App settings — يتم تعريفها باستخدام defineSettingsFrontComponent()، حيث يُعرَض مكوّن الواجهة الأمامية كقسم داخل علامة تبويب Settings في التطبيق، ليحل محل واجهة مستخدم تكوين المتغيرات الافتراضية.

مكوّن الواجهة الأمامية بمفرده لا يمكن الوصول إليه من واجهة المستخدم — تحتاج إلى عرضه. الطرق الثلاث للقيام بذلك هي:

إقرانه مع عنصر قائمة الأوامر — يقوم بتسجيله في قائمة الأوامر (Cmd+K) واختياريًا كإجراء سريع مُثبّت.
تضمينه كويدجت في تخطيط صفحة — يضعه في صفحة تفاصيل السجل أو لوحة المعلومات.
عرِّفه باستخدام defineSettingsFrontComponent() — يعرضه كقسم داخل علامة تبويب Settings في التطبيق، ليحل محل واجهة مستخدم تكوين المتغيرات الافتراضية.

مثال أساسي

أسرع طريقة لرؤية مكوّن الواجهة الأمامية أثناء العمل هي إقرانه مع defineCommandMenuItem، بحيث يظهر كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة:

src/front-components/hello-world.tsx

import { defineFrontComponent } from 'twenty-sdk/define';

const HelloWorld = () => {
  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>Hello from my app!</h1>
      <p>This component renders inside Twenty.</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
});

src/command-menu-items/hello-world.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
  shortLabel: 'Hello',
  label: 'Hello World',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

بعد المزامنة باستخدام yarn twenty dev (أو تشغيل الأمر لمرة واحدة yarn twenty apply)، يظهر الإجراء السريع في الزاوية العلوية اليمنى من الصفحة:

انقره لعرض المكوّن مضمنًا داخل الصفحة.

حقول التكوين

الحقل	مطلوب	الوصف
`universalIdentifier`	نعم	معرّف فريد ثابت لهذا المكوّن
`component`	نعم	دالة مكوّن React
`name`	لا	الاسم المعروض
`description`	لا	وصف لما يفعله المكوّن
`isHeadless`	لا	عيّنه على `true` إذا كان المكوّن بلا واجهة مرئية (انظر أدناه)

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

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

مكوّن إعدادات مخصص

لاستبدال واجهة مستخدم تكوين المتغيرات المولَّدة تلقائيًا في علامة تبويب Settings في تطبيقك بمكوّنك الخاص، عرِّفه باستخدام defineSettingsFrontComponent بدلًا من defineFrontComponent. يستخدم نفس حقول الإعدادات (باستثناء isHeadless، الذي لا يُقبل لأن مكوّن الإعدادات يعرض دائمًا واجهة مستخدم مرئية)، ويُحدِّد أيضًا هذا المكوّن باعتباره واجهة إعدادات التطبيق. يتم عرض المكوّن كقسم داخل علامة تبويب الإعدادات، وليس كبديل لعلامة التبويب بالكامل. الأقسام التي يديرها نظام Twenty — الترقية التلقائية، و App URL، والاتصالات — يتم عرضها دائمًا أعلاه ولا يمكن تجاوزها بواسطة التطبيق.

src/front-components/app-settings.tsx

import { defineSettingsFrontComponent } from 'twenty-sdk/define';

const AppSettings = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h2>My app settings</h2>
      {/* render your own configuration UI here */}
    </div>
  );
};

export default defineSettingsFrontComponent({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'app-settings',
  description: "Custom UI for the app's Settings tab",
  component: AppSettings,
});

يُسمَح بمكوّن واجهة إعدادات واحد فقط لكل تطبيق؛ إعلان أكثر من واحد يؤدي إلى فشل عملية الإنشاء. عند وجوده، تعرض علامة تبويب الإعدادات الخاصة بالتطبيق هذا المكوّن بدلًا من واجهة مستخدم تكوين المتغيّرات الافتراضية.

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

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

src/front-components/sync-tracker.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds, enqueueSnackbar } from 'twenty-sdk/front-component';
import { useEffect } from 'react';

const SyncTracker = () => {
  const [recordId] = useSelectedRecordIds();

  useEffect(() => {
    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
  }, [recordId]);

  return null;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-tracker',
  description: 'Tracks record views silently',
  isHeadless: true,
  component: SyncTracker,
});

نظرًا لأن المكوّن يُرجع null، فإن Twenty يتخطّى عرض حاوية له — ولن تظهر مساحة فارغة في التخطيط. لا يزال لدى المكوّن إمكانية الوصول إلى جميع الخطافات وواجهة برمجة الاتصال مع المضيف.

مكوّنات Command في SDK

توفر حزمة twenty-sdk أربعة مكوّنات مساعدة من نوع Command مصممة للمكوّنات عديمة الرأس في الواجهة الأمامية. كل مكوّن ينفّذ إجراءً عند التركيب، ويتعامل مع الأخطاء بعرض إشعار Snackbar، ويزيل تركيب مكوّن الواجهة الأمامية تلقائيًا عند الانتهاء. استوردها من twenty-sdk/front-component:

Command — يشغّل رد نداء غير متزامن عبر الخاصية execute.
CommandLink — ينتقل إلى مسار في التطبيق. الخصائص: to، params، queryParams، options.
CommandModal — يفتح نافذة تأكيد منبثقة. إذا أكّد المستخدم، ينفّذ رد النداء execute. الخصائص: title، subtitle، execute، confirmButtonText، confirmButtonAccent.
CommandOpenSidePanelPage — يفتح صفحة في اللوحة الجانبية. الـ props تعتمد على page — على سبيل المثال، ViewRecord يأخذ recordId + objectNameSingular (بالإضافة إلى معرّف tab اختياري لفتح السجل في تبويب معيّن)، بينما الصفحات الأخرى تأخذ pageTitle + pageIcon.

فيما يلي مثال كامل لمكوّن واجهة أمامية عديم الرأس يستخدم Command لتشغيل إجراء من قائمة الأوامر:

src/front-components/run-action.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const RunAction = () => {
  const execute = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      createTask: {
        __args: { data: { title: 'Created by my app' } },
        id: true,
      },
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
  name: 'run-action',
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
});

src/command-menu-items/run-action.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
  label: 'Run my action',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});

ومثال يستخدم CommandModal لطلب التأكيد قبل التنفيذ:

src/front-components/delete-draft.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { CommandModal } from 'twenty-sdk/front-component';

const DeleteDraft = () => {
  const execute = async () => {
    // perform the deletion
  };

  return (
    <CommandModal
      title="Delete draft?"
      subtitle="This action cannot be undone."
      execute={execute}
      confirmButtonText="Delete"
      confirmButtonAccent="danger"
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
  name: 'delete-draft',
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
});

ومثال يستخدم CommandOpenSidePanelPage لفتح السجل الحالي في اللوحة الجانبية على تبويب معيّن. tab هو معرّف تبويب تخطيط الصفحة (تستخدم التخطيطات الافتراضية معرّفات مثل company-tab-emails أو company-tab-timeline؛ وتستخدم التخطيطات المخصّصة معرّف التبويب نفسه). إذا لم يكن المعرّف موجودًا في تخطيط السجل، فسيتم فتح التبويب الافتراضي بدلًا منه:

src/front-components/open-company-emails.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  CommandOpenSidePanelPage,
  SidePanelPages,
  useSelectedRecordIds,
} from 'twenty-sdk/front-component';

const OpenCompanyEmails = () => {
  const selectedRecordIds = useSelectedRecordIds();
  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;

  if (!recordId) {
    return null;
  }

  return (
    <CommandOpenSidePanelPage
      page={SidePanelPages.ViewRecord}
      recordId={recordId}
      objectNameSingular="company"
      tab="company-tab-emails"
      resetNavigationStack={false}
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
  name: 'open-company-emails',
  description: 'Opens the current company on its Emails tab',
  component: OpenCompanyEmails,
  isHeadless: true,
});

استدعاء دالة منطقية

تعمل مكونات الواجهة الأمامية على جانب المتصفح داخل Web Worker مُعزَل داخل iframe ذو origin غير شفاف، بينما تعمل الدوال المنطقية على جانب الخادم. لا توجد استدعاءات مباشرة ضمن العملية بين الاثنين — بدلاً من ذلك، يصل مكون الواجهة الأمامية إلى الدالة المنطقية عبر HTTP. يتم الوصول إلى الدالة المنطقية المُعلَنة باستخدام httpRouteTriggerSettings عبر HTTP عند مسار التوجيه الخاص بها. يتعامل RestApiClient مع المسارات التي تبدأ بـ /s/ باعتبارها مسارات للتطبيق، ويُحوِّلها إلى عنوان الـ URL الذي تُقدَّم منه الدوال الخاصة بك، ويُجري عملية المصادقة عليها باستخدام TWENTY_APP_ACCESS_TOKEN.

على Twenty Cloud، يتم تقديم الدوال المنطقية المُفعَّلة عبر HTTP على نطاق مخصص لكل مساحة عمل عند https://\<your-workspace-subdomain>.withtwenty.com\<path>. للمتصلين الخارجيين، انسخ عنوان URL الدقيق من إعدادات HTTP trigger الخاصة بالدالة أو من علامة تبويب Settings في التطبيق.

يمكن لمكون واجهة أمامية عديم الرأس تنفيذ الاستدعاء عند التركيب عبر مكون Command، ثم إلغاء التركيب تلقائيًا:

src/front-components/sync-prs.tsx

import { RestApiClient } from 'twenty-client-sdk/rest';
import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';

const SyncPrs = () => {
  const execute = async () => {
    await new RestApiClient().post('/s/github/fetch-prs', {
      owner: 'twentyhq',
      repo: 'twenty',
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-prs',
  description: 'Triggers the fetch-prs logic function',
  isHeadless: true,
  component: SyncPrs,
});

المسار المُمرَّر إلى RestApiClient هو قيمة httpRouteTriggerSettings.path الخاصة بدالة المنطق (logic function) مع إضافة البادئة /s. أبقِ isAuthRequired: true؛ فرمز TWENTY_APP_ACCESS_TOKEN الذي تُنشئه Twenty لمكوِّنك هو ما يصادق على الطلب:

src/logic-functions/fetch-prs.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
  // ...fetch from GitHub and persist records...
  return { ok: true };
};

export default defineLogicFunction({
  universalIdentifier: '...',
  name: 'fetch-prs',
  handler,
  httpRouteTriggerSettings: {
    path: '/github/fetch-prs',
    httpMethod: 'POST',
    isAuthRequired: true,
  },
});

يتم حقن TWENTY_APP_ACCESS_TOKEN تلقائيًا — انظر متغيرات التطبيق. نظرًا لأن متغيرات التطبيق السرية لا تُعرَض أبدًا على مكونات الواجهة الأمامية، احتفِظ بمفاتيح واجهة برمجة التطبيقات والمنطق الحساس الآخر داخل الدالة المنطقية، وليس في مكون الواجهة الأمامية.

استدعاء واجهة REST API الخاصة بـ Twenty

لاستدعاء مسارات HTTP الخاصة بالتطبيق أو لقراءة سجلات Twenty وكتابتها من مكوِّن واجهة أمامية، استخدم RestApiClient من twenty-client-sdk/rest. يُرسل المسارات من نوع /s/... إلى عنوان URL الأساسي للدوال في مساحة العمل الخاصة بك، ويُرسل أي مسار آخر، بما في ذلك /rest/...، إلى TWENTY_API_URL.

طريقة	الوصف
`get(path, options?)`	يرسل طلبًا من نوع `GET`
`post(path, body?, options?)`	يرسل طلبًا من نوع `POST`
`put(path, body?, options?)`	يرسل طلبًا من نوع `PUT`
`patch(path, body?, options?)`	يرسل طلبًا من نوع `PATCH`
`delete(path, options?)`	يرسل طلبًا من نوع `DELETE`
`request(method, path, options?)`	طلب عام بأي طريقة HTTP
`resolveUrl(path, options?)`	يُحوِّل مسارًا إلى عنوان URL كامل بدون إرسال طلب (لاستخدامه في الروابط)

تدعم options كلًا من headers وquery (سجل لمعاملات query-string؛ يتم تخطي القيم nullish) وAbortSignal عبر signal. يتم تسلسل كائن body غير من النوع FormData إلى JSON تلقائيًا. عند حدوث 401، يقوم العميل بتحديث رمز الوصول مرة واحدة عبر المضيف ثم يعيد محاولة الطلب. يتم تحديد عنوان URL الأساسي والرمز من بيئة التشغيل بشكل افتراضي. مرِّر معاملات تجاوز (overrides) إلى المُنشئ (constructor) عند الحاجة — على سبيل المثال في الاختبارات:

const client = new RestApiClient({
  baseUrl: 'https://myworkspace.twenty.com',
  token: 'my-token',
});

ترمي الطلبات الفاشلة خطأً من نوع RestApiClientError يعرِّض خصائص status وstatusText وurl بالإضافة إلى body بعد تحليله (parsed):

import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';

const client = new RestApiClient();

try {
  const people = await client.get('/rest/people', {
    query: { limit: 10 },
  });
} catch (error) {
  if (error instanceof RestApiClientError) {
    console.error(error.status, error.body);
  }
}

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

داخل مكوّنك، استخدم خطافات SDK للوصول إلى المستخدم الحالي، والسجل، ومثيل المكوّن:

src/front-components/record-info.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  useUserId,
  useSelectedRecordIds,
  useFrontComponentId,
} from 'twenty-sdk/front-component';

const RecordInfo = () => {
  const userId = useUserId();
  const [recordId] = useSelectedRecordIds();
  const componentId = useFrontComponentId();

  return (
    <div>
      <p>User: {userId}</p>
      <p>Record: {recordId ?? 'No record context'}</p>
      <p>Component: {componentId}</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
  name: 'record-info',
  component: RecordInfo,
});

الخطافات المتاحة:

الخطّاف	القيم المعادة	الوصف
`useUserId()`	`string` أو `null`	معرّف المستخدم الحالي
`useSelectedRecordIds()`	`string[]`	جميع معرّفات السجلات المحددة (مصفوفة فارغة إذا لم يتم تحديد أي منها)
`useRecordId()`	`string` أو `null`	مهمل. استخدم `useSelectedRecordIds()` بدلاً من ذلك
`useFrontComponentId()`	`string`	معرّف مثيل هذا المكوّن
`useColorScheme()`	`'light'` أو `'dark'`	نظام الألوان النشط لواجهة المستخدم المضيفة (`System` تم تحديده بالفعل)
`useFrontComponentExecutionContext(selector)`	يختلف	الوصول إلى سياق التنفيذ الكامل عبر دالة محدِّد

متغيرات التطبيق

متغيرات التطبيق المُعرَّفة في defineApplication() مع isSecret: false تكون متاحة داخل مكوّنات الواجهة عبر أداة getApplicationVariable:

src/front-components/greeting.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { getApplicationVariable } from 'twenty-sdk/front-component';

const Greeting = () => {
  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';

  return <p>Hello, {recipientName}!</p>;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'greeting',
  component: Greeting,
});

المتغيرات السرّية (isSecret: true) لا يتم كشفها لمكوّنات الواجهة. هي متاحة فقط في دوال المنطق، التي تعمل على جهة الخادم. هذا يمنع إرسال القيم الحساسة مثل مفاتيح API إلى المتصفح.

تُرجِع الدالة getApplicationVariable دائمًا سلسلة نصية (أو undefined)، بغضّ النظر عن type المُعلَن للمتغيّر. تُسلسَل السلسلة النصية بشكل متسق حسب النوع (القيم المنطقية على هيئة “true” / “false”، الأعداد كسلاسل عشرية، والمصفوفات/الكائنات كـ JSON)، وهو نفس التنسيق المستخدم مع process.env في وظائف المنطق — قم بتحليلها بنفسك (Number(...)، ‏JSON.parse(...)، ‏=== 'true'). انظر قسم أنواع المتغيرات. متغيرات النظام التالية تكون متاحة دائمًا عبر process.env:

المتغيّر	الوصف
`TWENTY_API_URL`	عنوان URL الأساسي لـ Twenty Core API
`TWENTY_APP_ACCESS_TOKEN`	رمز مميز قصير العمر مُقيَّد بدور تطبيقك

`TWENTY_FUNCTIONS_URL`

يقوم Twenty أيضًا بحقن TWENTY_FUNCTIONS_URL في مكوِّنات الواجهة الأمامية والدوال المنطقية: وهو عنوان URL الأساسي الذي تُقدَّم منه الدوال المنطقية المُفعَّلة عبر HTTP في تطبيقك. وهو موجود لأن ذلك العنوان (URL) ليس دائمًا هو خادم Twenty نفسه. على Twenty Cloud، يتم تقديم مسارات التطبيق على نطاق مخصص لكل مساحة عمل (https://\<your-workspace-subdomain>.withtwenty.com، أو نطاق التطبيق العمومي الأساسي عندما يتم تكوينه) بحيث تعمل الاستجابات المنشأة من التطبيق على أصل (origin) معزول بدلاً من أصل تطبيق Twenty. تُقدِّم النسخ المستضافة ذاتيًا والمحلية مسارات التطبيق تحت البادئة /s على الخادم نفسه وقد لا تضبط المتغير إطلاقًا. نظرًا لاختلاف عنوان URL الأساسي حسب مساحة العمل وحسب كل نسخة، لا يمكن لشفرتك (code) أن تُضمِّنه بشكل ثابت (hard-code) — يقوم الخادم بحقن القيمة الصحيحة وقت التشغيل. نادرًا ما تحتاج إلى قراءته مباشرة. استدعِ مساراتك عبر RestApiClient باستخدام مسار يبدأ بالبادئة /s/، وسيقوم العميل بحل عنوان URL نيابةً عنك: يزيل بادئة /s ويستخدم TWENTY_FUNCTIONS_URL كهدف، مع الرجوع إلى \<TWENTY_API_URL>/s عندما لا يكون المتغير مضبوطًا. استخدم resolveUrl('/s/\<path>') للحصول على عنوان URL مطلق بدون إرسال طلب، على سبيل المثال لاستخدامه في رابط. اقرأ المتغير مباشرةً فقط عند إنشاء عنوان URL يدويًا:

const routeUrl = `${process.env.TWENTY_FUNCTIONS_URL || `${process.env.TWENTY_API_URL}/s`}/documents/generate`;

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

يمكن للمكوّنات الأمامية تشغيل التنقّل والنوافذ المنبثقة والإشعارات باستخدام دوال من twenty-sdk:

دالة	الوصف
`navigate(to, params?, queryParams?, options?)`	الانتقال إلى صفحة داخل التطبيق
`openSidePanelPage(params)`	فتح لوحة جانبية
`closeSidePanel()`	إغلاق اللوحة الجانبية
`openCommandConfirmationModal(params)`	عرض مربع حوار تأكيد
`enqueueSnackbar(params)`	عرض إشعار توست
`unmountFrontComponent()`	إلغاء تركيب المكوّن
`updateProgress(progress)`	تحديث مؤشّر التقدّم

فيما يلي مثال يستخدم واجهة برمجة تطبيقات المضيف لعرض Snackbar وإغلاق اللوحة الجانبية بعد اكتمال الإجراء:

src/front-components/archive-record.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { enqueueSnackbar, closeSidePanel, useSelectedRecordIds } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const ArchiveRecord = () => {
  const [recordId] = useSelectedRecordIds();

  const handleArchive = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      updateTask: {
        __args: { id: recordId, data: { status: 'ARCHIVED' } },
        id: true,
      },
    });

    await enqueueSnackbar({
      message: 'Record archived',
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Archive this record?</p>
      <button onClick={handleArchive}>Archive</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
  name: 'archive-record',
  description: 'Archives the current record',
  component: ArchiveRecord,
});

العمل مع سجلات متعددة

استخدم useSelectedRecordIds() لمعالجة عدة سجلات محددة. هذا مفيد للعمليات المجمّعة:

src/front-components/bulk-export.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds } from 'twenty-sdk/front-component';
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const BulkExport = () => {
  const selectedRecordIds = useSelectedRecordIds();

  const handleExport = async () => {
    const client = new CoreApiClient();

    for (const recordId of selectedRecordIds) {
      await client.mutation({
        updateTask: {
          __args: { id: recordId, data: { exported: true } },
          id: true,
        },
      });
    }

    await enqueueSnackbar({
      message: `Exported ${selectedRecordIds.length} records`,
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Export {selectedRecordIds.length} selected record(s)?</p>
      <button onClick={handleExport}>Export</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
  name: 'bulk-export',
  description: 'Export selected records',
  component: BulkExport,
});

أبرِزْه باستخدام عنصر قائمة الأوامر المقيّد بتحديدات السجلات:

src/command-menu-items/bulk-export.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
  label: 'Bulk Export',
  availabilityType: 'RECORD_SELECTION',
  frontComponentUniversalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
});

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

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

import { defineFrontComponent } from 'twenty-sdk/define';
import { getPublicAssetUrl } from 'twenty-sdk/utils';

const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'logo',
  component: Logo,
});

راجع قسم الأصول العامة للتفاصيل.

التنسيق

تدعم المكوّنات الأمامية عدة أساليب للتنسيق. يمكنك استخدام:

أنماط مضمنة — style={{ color: 'red' }}
مكوّنات Twenty UI — مكتبة المكوّنات الخاصة بـ Twenty؛ راجع استخدام مكوّنات Twenty UI أدناه
Emotion — CSS-in-JS مع @emotion/react
Styled-components — أنماط styled.div
Tailwind CSS — أصناف مساعدة
أي مكتبة CSS-in-JS متوافقة مع React

استخدام مكوّنات Twenty UI

توفّر Twenty مكتبة المكوّنات الخاصة بها على شكل حزمة twenty-ui. يمكن للمكوّنات الأمامية استخدامه للأزرار، والوسوم، وشارات الحالة، والرقاقات، والصور الرمزية، والأيقونات، والطباعة، ورموز السمات التي تتطابق تلقائيًا مع نسق مساحة العمل الفاتح أو الداكن.

التثبيت

أضِف الحزمة إلى تطبيقك، مع تثبيتها على الإصدار الذي تأتي به نسخة Twenty لديك:

yarn add twenty-ui@1.0.0-alpha.1

twenty-ui تكون مضمّنة في المكوّن الأمامي لديك وقت البناء، لذلك تحتاج فقط إلى أن تكون تابعة (dependency) لتطبيقك — ولا يوجد ما يلزم تهيئته وقت التشغيل.

استيراد المكوّنات

استورِد من المسار الفرعي المطابق بدلًا من جذر الحزمة، حتى لا ينتهي الأمر إلا بالمكوّنات التي تستخدمها داخل حزمة التطبيق (bundle) لديك:

المسار الفرعي	ما الذي يصدِّره
`twenty-ui/input`	`Button` ومدخلات النماذج
`twenty-ui/data-display`	`Tag`، و`Status`، و`Chip`، و`Avatar`، وغير ذلك
`twenty-ui/feedback`	`Callout`، و`Banner`، و`Info`، وغير ذلك
`twenty-ui/typography`	`H1Title`، و`H2Title`، و`H3Title`، و`Label`، وغير ذلك
`twenty-ui/icon`	مكوّنات `Icon*` (مثلًا `IconCheck`)
`twenty-ui/theme-constants`	`ThemeProvider`، و`themeCssVariables`

import { defineFrontComponent } from 'twenty-sdk/define';
import { Status, Tag } from 'twenty-ui/data-display';
import { Button } from 'twenty-ui/input';

const StyledWidget = () => {
  return (
    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
      <Button title="Click me" onClick={() => alert('Clicked!')} />
      <Tag text="Active" color="green" />
      <Status color="green" text="Online" />
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
  name: 'styled-widget',
  component: StyledWidget,
});

الأيقونات

استورِد الأيقونات الفردية من twenty-ui/icon:

import { IconBox, IconCheck } from 'twenty-ui/icon';

كل أيقونة مسمّاة قابلة للإزالة عبر تقنية tree-shaking، لذا فإن استيراد عدد قليل منها لا يزيد حجم الحزمة إلا قليلًا. تجنّب استخدام IconsProvider، وuseIcons، وiconsState — لأنها تجلب مجموعة أيقونات Tabler الكاملة (عدة ميغابايت).

التنسيق ورموز السمات

تتكيّف مكوّنات Twenty UI تلقائيًا مع نسق مساحة العمل الفاتح أو الداكن — إذ يطبّق المُصيّر (renderer) مخطط الألوان النشط على المضيف، وتضبط المكوّنات ألوانها وفقًا له. لاستخدام نفس رموز التصميم في أنماطك المضمّنة (inline styles)، استدعِ الخطّاف useTheme(). يُرجِع هذا الخطّاف رموز سمة Twenty (للمسافات، والألوان، وأنصاف الأقطار، والخطوط) المرتبطة بالنسق النشِط، دون الحاجة إلى إعداد ThemeProvider في المكوّن لديك:

import { useTheme } from 'twenty-ui/theme-constants';

const Card = () => {
  const theme = useTheme();

  return (
    <div
      style={{
        padding: theme.spacing[4],
        background: theme.background.secondary,
        color: theme.font.color.primary,
      }}
    >
      Themed card
    </div>
  );
};

نظرًا لأن useTheme() خطّاف، فإنك تقرأ الرموز داخل جسم المكوّن، لذا تعكس القيم دائمًا النسق المباشر (الحالي). تُصدَّر خريطة الرموز نفسها أيضًا كثابت themeCssVariables، لكن يُفضَّل استخدام useTheme() في المكوّنات الأمامية — إذ يمكن أن يكون الثابت على مستوى الوحدة الذي يفكّ مرجعية themeCssVariables غير معرَّف أثناء استخراج بيان التطبيق (app manifest). للتفرّع بناءً على النظام النشِط (active scheme) صراحةً، اقرأه باستخدام useColorScheme() من twenty-sdk/front-component، والذي يعيد 'light' أو 'dark'.

القيود الحالية

مكوّنات Front قيد التطوير النشط. الترسيم والتنسيق والتعامل مع الأحداث تعمل بشكل جيد. أي شيء يتجاوز مرحلة الترسيم (قياس عنصر، استدعاء دالة DOM على ref، إنشاء portal خارج الشجرة الخاصة بك، أو لمس تخزين المتصفح) مفقود أو غير مكتمل حاليًا، ومعظم هذه الحالات تفشل بصمت: لا يتم رمي استثناء، ولا يظهر خطأ TypeScript أيضًا، لأن القالب مكتوب استنادًا إلى DOM الكامل للمتصفح. إذا كان أحد هذه الأمور يعيقك، افتح تذكرة ليتم إعطاؤه أولوية.

التخطيط والقياس

لا يوجد أي شيء يمكنه قياس نفسه بعد.

واجهة برمجة التطبيقات	ما الذي يحدث
`getBoundingClientRect()`, `getClientRects()`	يرمي استثناء
`offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, …	قيمة `undefined` بصمت، لذا فإن `width ?? 0` تعطي `0` و `width > 600` تكون دائمًا خاطئة
`ResizeObserver`, `IntersectionObserver`	`ReferenceError` (`typeof` guards تعمل)
`window.matchMedia()`, `window.getComputedStyle()`	يرمي استثناء
`window.innerWidth`, `innerHeight`, `devicePixelRatio`	قيمة `undefined` بصمت
`new MutationObserver(fn)`	يتم الإنشاء، ثم ترمي `.observe()` استثناء

لذلك فإن recharts ResponsiveContainer، و Floating UI / Popper، وvirtualization للقوائم، والسحب لتغيير الحجم لا تعمل بعد. قم بتنفيذ التخطيط في CSS بدلًا من ذلك: ورقة الأنماط الخاصة بك تصل إلى الصفحة الحقيقية، لذا فإن flexbox و grid و aspect-ratio و clamp() و ‎@container كلها تتصرف بشكل طبيعي.

requestAnimationFrame, fetch, setTimeout و queueMicrotask تعمل بدون بادئة window.. فقط window.requestAnimationFrame(...) وما شابهها ترمي استثناء.

الوصول إلى DOM

يعطيك ref عنصرًا في sandbox، وليس HTMLElement.

ما الذي تكتبه	ما الذي يحدث	استخدم بدلًا من ذلك
`ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()`	يرمي استثناء	مكوّنات مضبوطة (Controlled components)؛ اقرأ القيم من `event.target`
`element.classList.add(...)`	يرمي استثناء (`classList` هو `undefined`)	قم ببناء سلسلة `className` بنفسك
`document.getElementById()`, `getElementsByClassName()`, `createTreeWalker()`	يرمي استثناء	`querySelector()` / `querySelectorAll()`, والتي تعمل
`document.activeElement`	دائمًا `undefined`	تتبّع التركيز باستخدام `onFocus` / `onBlur`
`\<canvas>`	لا يَرسُم أي شيء، بدون خطأ	استخدم SVG، أو ارسم خارج الشاشة ثم اعرض `<img src={dataUrl}>`
`createPortal(node, document.body)`	لا يَرسُم أي شيء، بينما `isConnected` يُبلغ عن النجاح	استخدم الطبقات العائمة (overlays) داخل التخطيط نفسه مع `position: absolute`، أو مرّر إلى المكتبة عنصر الحاوية الخاص بك

فجوة الـ portal هي السبب في أن عناصر popover في Radix و Headless UI و MUI و react-select لا ترسُم أي شيء بشكل افتراضي. معظمها يقبل خاصية container؛ وجّهها إلى عنصر قمت بترسيمه.

الأحداث

أحداث الماوس، والمؤشر، واللمس، والسحب، ولوحة المفاتيح، والتركيز، وinput/change/submit، وscroll/wheel/contextmenu وanimationend/transitionend تمر إلى المضيف، بالإضافة إلى عدد قليل لكل عنصر: load/error على <img>، والحافظة والتكوين على <input>/\<textarea>، والوسائط على \<video>/\<audio>، وtoggle على \<details>/\<dialog>. أي شيء آخر (onAuxClick, onSelect, onInvalid, onReset, onAnimationStart, التقاط المؤشر، onLoad خارج <img>) يتم إسقاطه دون تحذير. document.addEventListener() و window.addEventListener() تُسجِّلان بدون خطأ لكن لا تُطلقان أبدًا، وهذا هو السبب في أن السحب يتوقف بمجرد أن يغادر المؤشر العنصر الذي بدأ عليه. event.preventDefault() لا يعبر أيضًا؛ إرسال النماذج، وdragover/drop ونقرات الروابط محمية مسبقًا من أجلك.

السمات والأنماط

كل عنصر يمرّر خصائصه الخاصة إلى DOM المضيف (href على \<a>, و src/alt على <img>, و value/placeholder/disabled على <input>, وهكذا)، بالإضافة إلى مجموعة مشتركة على كل عنصر: id, className, style, title, tabIndex, role, draggable وأي سمة aria-* / data-* (مفصولة بشرطات، لذا يتم إسقاط ariaLabel). أي شيء خارج ذلك يتم تجاهله بصمت، لذا عبّر عن الحالة المخصّصة كـ data-*. يتم حقن CSS الخاص بالمكوّن، سواءً من import './styles.css' أو CSS-in-JS أو عنصر \<style>، في وسم \<head> لصفحة المضيف بدون نطاق. لذا تتصادم أسماء الأصناف مع أسماء Twenty نفسها (قم بإضافة بادئة لها، ولا تكتب أبدًا محددًا مثل div { ... })، و @media تطابِق نافذة المتصفح بدلاً من الودجت الخاص بك (استخدم @container مع container-type الخاص بك). خصائص style المضمنة لا تتأثر.

التخزين والشبكة

localStorage وsessionStorage وIndexedDB وملفات تعريف الارتباط وواجهة برمجة تطبيقات Cache وBroadcastChannel كلها غير متاحة، لأن المكوّن يعمل في عامل (worker) بأصل غير شفاف. للاحتفاظ بالحالة، استدعِ دالة منطقية واستخدم مخزن القيم المفتاحية الخاص بها. fetch يعمل، مع بعض التحفّظات:

يتم تمرير الاستدعاءات إلى Twenty API ومسارات تطبيقك عبر المضيف، لذا يُفضَّل استخدام RestApiClient. في الاستدعاءات الممرَّرة عبر الوكيل، يتم إسقاط AbortSignal وخيارات RequestInit الأخرى، ولا يتم دعم سوى الأجسام من نوع string وURLSearchParams.
تغادر النطاقات (origins) الأخرى صندوق العزل مع Origin: null، لذلك يجيب طرف ثالث لواجهة برمجة التطبيقات فقط إذا أرسل Access-Control-Allow-Origin: *. استدعِها من دالة منطقية بدلًا من ذلك.
fetch('/rest/people') لا يتطابق أبدًا مع Twenty API، لأن صندوق العزل ليس لديه عنوان URL للصفحة لحساب مسار نسبي بناءً عليه.

فجوات أخرى

محتويات الملفات. يُرجِع <input type="file"> إلى معالجك بيانات تعريف الملف فقط، وليس البايتات، لذلك فإن FileReader وعمليات الرفع غير ممكنة بعد.
حمولات السحب والإفلات. أحداث السحب تُطلق، لكن event.dataTransfer هي undefined.
الوحدات المدمجة في Node. fs وpath وnode:crypto تفشل في عملية البناء، لذا انقل ذلك العمل إلى دالة منطقية. Web Crypto و fetch و TextEncoder و URL متوفرة.
يتم دائمًا إعادة عزل \<iframe> دون allow-same-origin، لذلك يعمل التضمين الذي يعتمد على جلسته الخاصة في وضع “تسجيل الخروج”. ليس لديه onLoad أيضًا.

نظرة عامة

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

المكوّنات الأمامية

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

مثال أساسي

حقول التكوين

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

مكوّن إعدادات مخصص

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

مكوّنات Command في SDK

استدعاء دالة منطقية

استدعاء واجهة REST API الخاصة بـ Twenty

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

متغيرات التطبيق

`TWENTY_FUNCTIONS_URL`

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

العمل مع سجلات متعددة

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

التنسيق

استخدام مكوّنات Twenty UI

التثبيت

استيراد المكوّنات

الأيقونات

التنسيق ورموز السمات

القيود الحالية

التخطيط والقياس

الوصول إلى DOM

الأحداث

السمات والأنماط

التخزين والشبكة

فجوات أخرى

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

​مثال أساسي

​حقول التكوين

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

​مكوّن إعدادات مخصص

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

​مكوّنات Command في SDK

​استدعاء دالة منطقية

​استدعاء واجهة REST API الخاصة بـ Twenty

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

​متغيرات التطبيق

​TWENTY_FUNCTIONS_URL

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

​العمل مع سجلات متعددة

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

​التنسيق

​استخدام مكوّنات Twenty UI

​التثبيت

​استيراد المكوّنات

​الأيقونات

​التنسيق ورموز السمات

​القيود الحالية

​التخطيط والقياس

​الوصول إلى DOM

​الأحداث

​السمات والأنماط

​التخزين والشبكة

​فجوات أخرى

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

مثال أساسي

حقول التكوين

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

مكوّن إعدادات مخصص

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

مكوّنات Command في SDK

استدعاء دالة منطقية

استدعاء واجهة REST API الخاصة بـ Twenty

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

متغيرات التطبيق

`TWENTY_FUNCTIONS_URL`

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

العمل مع سجلات متعددة

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

التنسيق

استخدام مكوّنات Twenty UI

التثبيت

استيراد المكوّنات

الأيقونات

التنسيق ورموز السمات

القيود الحالية

التخطيط والقياس

الوصول إلى DOM

الأحداث

السمات والأنماط

التخزين والشبكة

فجوات أخرى