الانتقال إلى المحتوى الرئيسي
تُعد الكائنات المخصصة أنواع سجلات جديدة يضيفها تطبيقك إلى مساحة العمل — مثل بطاقة بريدية، أو فاتورة، أو اشتراك، أو أي شيء خاص بالمجال الذي تعمل فيه. يعلن كل كائن عن مخططه (الحقول، والعلاقات، والقيم الافتراضية) ومعرّف عالمي ثابت يستمر عبر عمليات المزامنة والنشر.
src/objects/post-card.object.ts
import { defineObject, FieldType } from 'twenty-sdk/define';

enum PostCardStatus {
  DRAFT = 'DRAFT',
  SENT = 'SENT',
  DELIVERED = 'DELIVERED',
  RETURNED = 'RETURNED',
}

export default defineObject({
  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
  nameSingular: 'postCard',
  namePlural: 'postCards',
  labelSingular: 'Post Card',
  labelPlural: 'Post Cards',
  description: 'A post card object',
  icon: 'IconMail',
  fields: [
    {
      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
      name: 'content',
      type: FieldType.TEXT,
      label: 'Content',
      description: "Postcard's content",
      icon: 'IconAbc',
    },
    {
      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
      name: 'recipientName',
      type: FieldType.FULL_NAME,
      label: 'Recipient name',
      icon: 'IconUser',
    },
    {
      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
      name: 'recipientAddress',
      type: FieldType.ADDRESS,
      label: 'Recipient address',
      icon: 'IconHome',
    },
    {
      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
      name: 'status',
      type: FieldType.SELECT,
      label: 'Status',
      icon: 'IconSend',
      defaultValue: `'${PostCardStatus.DRAFT}'`,
      options: [
        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
      ],
    },
    {
      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
      name: 'deliveredAt',
      type: FieldType.DATE_TIME,
      label: 'Delivered at',
      icon: 'IconCheck',
      isNullable: true,
      defaultValue: null,
    },
  ],
});

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

  • universalIdentifier يجب أن يكون فريدًا وثابتًا عبر عمليات النشر.
  • يتطلب كل حقل name وtype وlabel ومعرّف universalIdentifier ثابتًا خاصًا به.
  • المصفوفة fields اختيارية — يمكنك تعريف كائنات بدون حقول مخصصة.
  • لا تحتاج الحقول المضمّنة المُعرَّفة هنا إلى objectUniversalIdentifier — إذ تُورَّث من الكائن الأب. استخدم defineField() لإضافة حقول إلى كائنات لا تمتلكها.
  • يمكنك إنشاء كائنات جديدة باستخدام yarn twenty dev:add object، والذي يرشدك خلال التسمية والحقول والعلاقات. راجع Architecture → Scaffolding entities.
تُضاف الحقول الأساسية تلقائيًا. عند تعريف كائن مخصص، ينشئ Twenty حقولًا قياسية مثل id وname وcreatedAt وupdatedAt وcreatedBy وupdatedBy وdeletedAt من أجلك. لا تحتاج إلى تعريفها في مصفوفة fields — أضف فقط حقولك المخصصة. يمكنك تجاوز حقلًا افتراضيًا بتعريف حقل يحمل الاسم نفسه، لكن هذا نادرًا ما يكون فكرة جيدة.

القيم الافتراضية

يجب تضمين القيم النصية الافتراضية بين علامات اقتباس أحادية داخل السلسلة — defaultValue: "'Draft'"، وليس defaultValue: "Draft". لهذا السبب يستخدم الحقل status أعلاه `'${PostCardStatus.DRAFT}'`. السلاسل غير المحاطة بعلامات اقتباس محجوزة للقيم الافتراضية المحسوبة، والتي يتم تقييمها عند إنشاء سجل:
  • 'uuid' — يُنشِئ UUID (لحقول UUID)
  • 'now' — الطابع الزمني الحالي (لحقول DATE_TIME)
ينطبق نفس الاصطلاح على الحقول الفرعية النصية للقيم الافتراضية المركّبة (على سبيل المثال { source: "'MANUAL'" } في حقل ACTOR) وكذلك على قيم SELECT/MULTI_SELECT. سيتسبّب ترك قيمة افتراضية نصية حرفية بدون علامات اقتباس في ظهور تحذير عند إنشاء التطبيق.

ماذا بعد؟

  • اربط هذا الكائن بغيره من الكائنات — راجع صفحة Relations لمعرفة نمط العلاقة ثنائية الاتجاه.
  • أضف حقولًا إلى الكائنات التابعة لتطبيقات أخرى — راجع Extending Objects لمعرفة المزيد حول defineField().
  • اعرض هذا الكائن في واجهة المستخدم — راجع Views وNavigation Menu Items لإظهاره في الشريط الجانبي.