تخطيطات الصفحات

​

نظرة عامة

​

definePageLayout

import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayout({
  universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
  name: 'Example Record Page',
  type: 'RECORD_PAGE',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  tabs: [
    {
      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
      title: 'Hello World',
      position: 50,
      icon: 'IconWorld',
      layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
      widgets: [
        {
          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
          title: 'Hello World',
          type: 'FRONT_COMPONENT',
          heightBehavior: 'TAB_VIEWPORT',
          configuration: {
            configurationType: 'FRONT_COMPONENT',
            frontComponentUniversalIdentifier:
              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
          },
        },
      ],
    },
  ],
});

​

النقاط الرئيسية

• type هو أحد 'RECORD_INDEX' أو 'RECORD_PAGE' أو 'DASHBOARD' أو 'STANDALONE_PAGE' أو 'RECORD_FORM'. استخدم 'RECORD_PAGE' لتخصيص عرض التفاصيل لكائن محدّد. يصف 'RECORD_FORM' نموذج إنشاء كائن ويحتوي على عناصر واجهة FORM_FIELD، يعرض كل منها حقلاً واحداً. يوفر Twenty تخطيط 'RECORD_FORM' واحداً لكل كائن مع عنصر واجهة واحد لكل حقل قابل للإنشاء، لذا نادراً ما تحتاج إلى تأليف واحد؛ وهو لا يعرض نماذج السجلات بعد.
• objectUniversalIdentifier يحدّد الكائن الذي ينطبق عليه هذا التخطيط.
• يُعرّف كل tab قسمًا من الصفحة مع title وposition وlayoutMode: استخدم VERTICAL_LIST لصفحات السجلات والصفحات المستقلة، وGRID للوحات المعلومات. تُرتّب علامة التبويب VERTICAL_LIST عناصر الواجهة عموديًا. تملأ الأدوات المضمنة التي تدير تمريرها الخاص، مثل المخططات الزمنية والملفات والملاحظات والمهام وسير العمل والمحادثات، إطار عرض واحدًا افتراضيًا؛ وتُعرض الحقول والمكونات الأمامية والرسوم البيانية وغيرها من الأدوات الملائمة للمحتوى بارتفاع محتواها أو بارتفاعها المُهيأ. تُرتّب علامة التبويب GRID عناصر واجهتها دائمًا على شكل بطاقات ضمن شبكة من 12 عمودًا.
• ترث عناصر واجهة المستخدم في علامة تبويب VERTICAL_LIST وضع تخطيط علامة التبويب، ويأتي ترتيبها من المصفوفة widgets. لا تضبط position؛ اضبط heightBehavior الاختياري من المستوى الأعلى على 'TAB_VIEWPORT' عندما يجب أن يشغل عنصر واجهة مستخدم منفذ عرض علامة تبويب كاملًا وأن يدير تمريره الخاص، أو على 'FIT_CONTENT' لتجاوز الإعداد الافتراضي المضمّن للارتفاع الكامل. لا تقلل عناصر واجهة المستخدم السابقة ذلك الارتفاع. يُسمح بعنصر واجهة مستخدم نشط واحد فقط من TAB_VIEWPORT لكل علامة تبويب، ويجب أن يأتي بعد عناصر واجهة المستخدم الملائمة للمحتوى.
• تستمر أدوات GRID في استخدام position: { layoutMode: PageLayoutTabLayoutMode.GRID, row, column, rowSpan, columnSpan }. تكون heightBehavior على المستوى الأعلى صالحة فقط لعلامات تبويب VERTICAL_LIST؛ ويُعد استخدامها مع GRID أو CANVAS خطأ في التحقق.
• تظل علامات تبويب Canvas الحالية ومواضع الأدوات الصريحة مدعومة. تعرض SDK تحذيرات الإيقاف مع البدائل الموصى بها.
• عيِّن layoutMode بشكل صريح. إغفاله يمنحك VERTICAL_LIST على STANDALONE_PAGE وGRID في كل مكان آخر، وهو أمر نادرًا ما تريده في صفحة سجل.
• يمكن لكل widget داخل لسان أن يعرض front component، أو قائمة علاقات، أو أنواعًا أخرى من عناصر الواجهة (widgets) المدمجة.
• يمكن لأداة FRONT_COMPONENT تعيين headerCommandMenuItemUniversalIdentifiers إلى مصفوفة مرتبة من المعرّفات العامة لعناصر قائمة الأوامر من التطبيق نفسه. تظهر هذه الإجراءات كأزرار أيقونات في رأس بطاقة الأداة، وتحتفظ بفحوصات التوفر والأذونات على مستوى الأمر. يجب أن تكون المعرّفات فريدة، ويجب أن تُحل عند تثبيت التطبيق.
• يمكن لعنصر واجهة المستخدم IFRAME استخدام الميكروفون أو الكاميرا لمواقع الويب المعتمدة من خلال الخاصية requestedIframeMediaPermissions لتطبيقه المالك. يختار الأعضاء تمكين ويوافقون على تأكيد أصلي من المتصفح يعرض التطبيق، وأصل موقع الويب، والوصول المطلوب إلى الميكروفون أو الكاميرا قبل بدء الوصول. لا تنطبق موافقات أمان مساحة العمل ومنح التطبيقات الأخرى على عناصر واجهة المستخدم المحددة من التطبيق.
• position على الألسنة يتحكّم في ترتيبها. استخدم قيمًا أعلى (مثل 50) لوضع الألسنة المخصّصة بعد الألسنة المدمجة.
• يكتب twenty app pull تخطيطات الصفحات مرة أخرى مع علامات التبويب والأدوات الخاصة بها مضمنة. تُبلّغ عملية pull عن أداة لا يمكن للتصدير نقلها بعد، مثل أداة تعرض المكوّن الأمامي الخاص بتطبيقك أو أداة من النوع VIEW المتوقَّف، بدلاً من كتابتها؛ راجع ما لا تكتبه عملية pull.

​

عناصر واجهة الحقول

{
  universalIdentifier: 'c1c2c3c4-c5c6-4000-8000-000000000003',
  title: 'People → Opportunities',
  type: 'FIELD',
  configuration: {
    configurationType: 'FIELD',
    fieldMetadataId: PEOPLE_FIELD_UNIVERSAL_IDENTIFIER,
    fieldDisplayMode: 'TABLE',
    nestedRelationFieldMetadataId: OPPORTUNITIES_FIELD_UNIVERSAL_IDENTIFIER,
  },
}

• fieldMetadataId يأخذ المعرف العالمي لحقل على كائن المخطط.
• fieldDisplayMode يكون واحداً من 'FIELD'، 'CARD'، 'EDITOR'، 'VIEW' أو 'TABLE'. TABLE يضمّن عرضاً يسرد السجلات لحقل علاقة من نوع واحد إلى متعدد.
• ينطبق isUIEditable على حقول العلاقات في وضع العرض TABLE. تكون قيمته الافتراضية true؛ اضبطها على false لمنع تحرير السجلات من الجدول المضمّن أو لوحة كانبان.
• nestedRelationFieldMetadataId اختياري، ويأخذ المعرّف العالمي لحقل علاقة من نوع واحد‑إلى‑متعدد على الكائن الهدف للعلاقة، وذلك لسرد السجلات التي تبعد قفزتين في سلسلة العلاقات (مثل صفحة شركة تسرد الفرص الخاصة بأشخاص الشركة، أو صفحة شخص تسرد الفرص الخاصة بشركة الشخص). يمكن أن تكون القفزة الأولى حقل علاقة من نوع واحد‑إلى‑متعدد أو من نوع متعدد‑إلى‑واحد، بينما يجب أن تكون القفزة الثانية من نوع واحد‑إلى‑متعدد (علاقات الوصل غير مدعومة)، ويتطلب ذلك fieldDisplayMode: 'TABLE' — إذ يُعد الجمع بينه وبين أي نمط عرض آخر خطأ في التحقق من الصحة، نظرًا لأن الودجة المتداخلة يتم عرضها دائمًا كعرض مضمن.

​

عناصر واجهة جدول السجلات

{
  universalIdentifier: 'd1d2d3d4-d5d6-4000-8000-000000000004',
  title: 'Open opportunities',
  type: 'RECORD_TABLE',
  configuration: {
    configurationType: 'RECORD_TABLE',
    viewUniversalIdentifier: OPPORTUNITIES_VIEW_UNIVERSAL_IDENTIFIER,
    recordLimit: 8,
    isUIEditable: false,
  },
}

• يحدّد viewUniversalIdentifier العرض الذي سيتم عرضه.
• recordLimit اختياري ويحدّد الحد الأقصى لعدد السجلات التي يعرضها عنصر الواجهة.
• ينطبق isUIEditable على عروض الجدول وكانبان. يتيح تحرير خلايا الجدول أو تحرير بطاقات كانبان ونقلها وإنشاؤها. تكون قيمته الافتراضية true في تخطيطات RECORD_PAGE وfalse في التخطيطات الأخرى.
• يتحكم isUIEditable في إجراءات واجهة المستخدم فقط. تظل أذونات السجلات سارية، وتبقى إعدادات العرض قابلة للتحرير فقط في محرر تخطيط الصفحة.

​

definePageLayoutTab

import {
  definePageLayoutTab,
  PageLayoutTabLayoutMode,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutTab({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
  pageLayoutUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage
      .universalIdentifier,
  title: 'Hello World',
  position: 1000,
  icon: 'IconWorld',
  layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
  widgets: [
    {
      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
      title: 'Hello World',
      type: 'FRONT_COMPONENT',
      configuration: {
        configurationType: 'FRONT_COMPONENT',
        frontComponentUniversalIdentifier:
          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
      },
    },
  ],
});

​

النقاط الرئيسية

• إن pageLayoutUniversalIdentifier مطلوب ويجب أن يشير إلى تخطيط صفحة موجود بالفعل وقت التثبيت — سواء كان تخطيط Twenty قياسيًا أو تخطيطًا معرّفًا بواسطة تطبيقك الخاص. المراجع المتقاطعة بين التطبيقات إلى التخطيطات المملوكة لتطبيق آخر مُثبَّت غير مدعومة حاليًا. عند فقدان التخطيط الأب، يفشل التثبيت مع ظهور خطأ تحقق واضح.
• بالنسبة لتخطيطات Twenty القياسية، استورد المعرفات من twenty-sdk/define:
  import { STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
  
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.personRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.opportunityRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.noteRecordPage.universalIdentifier
  // …
  
  كل إدخال تخطيط يوفّر أيضًا tabs الخاصة به وwidgets التابعة لها، بحيث يمكنك الرجوع إلى أي مستوى:
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home
    .universalIdentifier;
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home.widgets
    .fields.universalIdentifier;
  
  يتوفر أيضًا اسم قصير STANDARD_PAGE_LAYOUT:
  import { STANDARD_PAGE_LAYOUT } from 'twenty-sdk/define';
  
  STANDARD_PAGE_LAYOUT.companyRecordPage.universalIdentifier;
  
• يكون نطاق widgets مقتصرًا على هذا اللسان فقط — فهي تشير إلى front components، والعروض، وما إلى ذلك تمامًا مثل عناصر الواجهة (widgets) المُعرَّفة مضمّنة داخل definePageLayout.
• position يتحكّم في الترتيب مقارنةً بعلامات التبويب الموجودة على التخطيط المستهدف. اختر قيمة تضع علامة التبويب الخاصة بك في الموضع الذي تريده بالنسبة إلى علامات التبويب المضمنة.
• استخدم هذا بدلًا من definePageLayout عندما تريد فقط الإضافة إلى تخطيط موجود. استخدم definePageLayout عندما تملك التخطيط بالكامل.
• يكتب twenty app pull علامة تبويب أضفتها إلى تخطيط صفحة لا تملكه مرة أخرى كملف definePageLayoutTab()، مع أدواته مضمنة، ضمن الحدود نفسها المطبقة على أدوات definePageLayout().

​

definePageLayoutWidget

import {
  definePageLayoutWidget,
  PageLayoutTabLayoutMode,
  PageLayoutWidgetVerticalListHeightBehavior,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutWidget({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000003',
  pageLayoutTabUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.tabs.home
      .universalIdentifier,
  title: 'Hello World',
  type: 'FRONT_COMPONENT',
  position: {
    layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
    index: 1000,
    heightBehavior: PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT,
  },
  configuration: {
    configurationType: 'FRONT_COMPONENT',
    frontComponentUniversalIdentifier:
      HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
  },
});

​

النقاط الرئيسية

• إن pageLayoutTabUniversalIdentifier مطلوب ويجب أن يشير إلى لسان موجود بالفعل وقت التثبيت: لسان Twenty قياسي (STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.\<object>RecordPage.tabs.\<tab>.universalIdentifier)، أو لسان من أحد تخطيطاتك الخاصة، أو لسان من صفحة السجل التي ينشئها Twenty لأحد كائناتك. للعلامات المُنشأة معرّفات حتمية، لذا يمكنك حسابها:
  import {
    getSystemPageLayoutTabUniversalIdentifier,
    getSystemRecordPageLayoutUniversalIdentifier,
  } from 'twenty-sdk/define';
  
  const EXAMPLE_HOME_TAB_UNIVERSAL_IDENTIFIER =
    getSystemPageLayoutTabUniversalIdentifier({
      objectMetadataApplicationUniversalIdentifier:
        APPLICATION_UNIVERSAL_IDENTIFIER,
      pageLayoutUniversalIdentifier:
        getSystemRecordPageLayoutUniversalIdentifier({
          objectMetadataApplicationUniversalIdentifier:
            APPLICATION_UNIVERSAL_IDENTIFIER,
          objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
        }),
      title: 'Home',
    });
  
• position مطلوب، لأن اللسان ليس جزءًا من البيان الخاص بك ولا يمكن استنتاج وضع تخطيطه. طابق وضع تخطيط اللسان: علامات تبويب صفحة السجل هي قوائم عمودية، لذا استخدم { layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST, index } مع فهرس أعلى من عناصر الواجهة المضمنة (يوجد عنصر واجهة الحقول عند 0).
• بالنسبة إلى قائمة عمودية، عيّن position.heightBehavior إلى PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT لملء منفذ عرض علامة تبويب واحدة، أو إلى PageLayoutWidgetVerticalListHeightBehavior.FIT_CONTENT لاستخدام محتوى الأداة أو ارتفاعها المُكوَّن. استورد هذا التعداد من twenty-sdk/define، كما في المثال أعلاه. إذا تم حذفه، تحتفظ الأداة بقيمتها الافتراضية المضمنة. يمكن لأداة نشطة واحدة فقط لكل علامة تبويب ملء منفذ العرض، ويجب أن يضعها فهرسها بعد جميع الأدوات ذات ملاءمة المحتوى. لا تُدعم heightBehavior في مواضع GRID أو CANVAS.
• يعمل configuration تمامًا مثل عنصر واجهة معرّف مضمنًا في definePageLayout أو definePageLayoutTab: إذ يشير إلى المكوّنات الأمامية، والعروض، والحقول، وما إلى ذلك.
• استخدم هذا بدلًا من definePageLayoutTab عندما يكون اللسان موجودًا بالفعل وتريد فقط وضع عنصر واجهة واحد عليه. استخدم definePageLayoutTab عندما تريد لسانًا خاصًا بك.
• يكتب twenty app pull أداة أضفتها إلى علامة تبويب لا تملكها مرة أخرى كملف definePageLayoutWidget()، ضمن الحدود نفسها المطبقة على أدوات definePageLayout().