upstream-twenty/packages/twenty-docs/l/ar/developers/extend/apps/data/objects.mdx

---
title: كائنات
description: عرّف أنواعًا جديدة من السجلات — جداول مخصصة بحقولها الخاصة — باستخدام defineObject.
icon: table
---

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

```ts 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` اختيارية — يمكنك تعريف كائنات بدون حقول مخصصة.
* `openRecordIn` يحدد أين تُفتح سجلات هذا الكائن عند النقر عليها: `ObjectOpenRecordIn.USER_CHOICE` (الإعداد الافتراضي، الذي يتبع تفضيل كل عضو في مساحة العمل من Settings → Experience)، أو `ObjectOpenRecordIn.SIDE_PANEL`، أو `ObjectOpenRecordIn.RECORD_PAGE`. ثبِّتها على `RECORD_PAGE` للسجلات التي تحتاج إلى صفحة كاملة لتكون قابلة للاستخدام، كما هو الحال في سير العمل ولوحات المعلومات، أو على `SIDE_PANEL` للسجلات التي لا تكون منطقية إلا كلوحة سريعة، كما هو الحال في أحداث التقويم.
* تتحكم الخاصية `writability` في من يمكنه كتابة سجلات الكائن من الأساس، قبل تطبيق أذونات الأدوار: `MetadataWritability.OPEN` (القيمة الافتراضية — أدوار مساحة العمل هي التي تقرر)، أو `MetadataWritability.APPLICATION` (يمكن لوظائف منطق تطبيقك فقط إنشاء السجلات أو تحديثها أو حذفها؛ استخدم هذا لكائنات تشبه التهيئة التي تمنح سجلاتها سلوكًا، بحيث لا يتمكن أعضاء مساحة العمل الذين لديهم وصول واسع إلى السجلات من تعديلها عبر واجهة برمجة التطبيقات API)، أو `MetadataWritability.SYSTEM` (محجوزة للبيانات التي تُدار من قبل المنصّة). لا تتأثر عمليات القراءة — يتم فرض هذا من جانب الخادم، على عكس `isUIEditable`، التي تقتصر على إخفاء عناصر واجهة المستخدم. توجد هذه الخاصية أيضًا على مستوى الحقل، حيث لا يمكن أن تكون إلا أكثر تقييدًا من مستوى الكائن.
* لا تحتاج الحقول المضمّنة المُعرَّفة هنا إلى `objectUniversalIdentifier` — إذ تُورَّث من الكائن الأب. استخدم [`defineField()`](/l/ar/developers/extend/apps/data/extending-objects) لإضافة حقول إلى كائنات لا تمتلكها.
* يمكنك إنشاء كائنات جديدة باستخدام `yarn twenty dev:add object`، والذي يرشدك خلال التسمية والحقول والعلاقات. راجع [Architecture → Scaffolding entities](/l/ar/developers/extend/apps/getting-started/scaffolding).

<Note>
**تُضاف الحقول الأساسية تلقائيًا.** عند تعريف كائن مخصص، ينشئ Twenty حقولًا قياسية مثل `id` و`name` و`createdAt` و`updatedAt` و`createdBy` و`updatedBy` و`deletedAt` من أجلك. لا تحتاج إلى تعريفها في مصفوفة `fields` — أضف فقط حقولك المخصصة. يمكنك تجاوز حقلًا افتراضيًا بتعريف حقل يحمل الاسم نفسه، لكن هذا نادرًا ما يكون فكرة جيدة.
</Note>

## أنواع الحقول

مجموعة القيم الكاملة لـ`FieldType`، والمصدَّرة من `twenty-sdk/define`:

| الفئة                | الأنواع                                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| نص                   | `TEXT`، `RICH_TEXT`، `ARRAY` (من السلاسل النصية)، `RAW_JSON`                                                               |
| عددية                | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`)، `NUMERIC` (بدقة اعتباطية)، `RATING`، `POSITION` |
| التواريخ             | `DATE`, `DATE_TIME`                                                                                                        |
| اختيار               | `BOOLEAN`، `SELECT`، `MULTI_SELECT`                                                                                        |
| مركّبة               | `FULL_NAME`، `ADDRESS`، `EMAILS`، `PHONES`، `LINKS`، `CURRENCY`، `ACTOR`، `FILES`                                          |
| المعرِّفات والعلاقات | `UUID`، `RELATION`، `MORPH_RELATION` (انظر [العلاقات](/l/ar/developers/extend/apps/data/relations))                             |
| النظام               | `TS_VECTOR` (متجه بحث نصي كامل، يُدار بواسطة الخادم)                                                                       |

تُخزِّن الأنواع المركّبة عدّة حقول فرعية (مثلًا `FULL_NAME` = الاسم الأول + اسم العائلة؛ `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` و`MULTI_SELECT` يتطلّبان مصفوفة `options` كما في المثال أعلاه.

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

يجب تضمين القيم النصية الافتراضية بين علامات اقتباس أحادية **داخل** السلسلة — `defaultValue: "'Draft'"`، وليس `defaultValue: "Draft"`. لهذا السبب يستخدم الحقل `status` أعلاه `` `'${PostCardStatus.DRAFT}'` ``.

السلاسل غير المحاطة بعلامات اقتباس محجوزة للقيم الافتراضية المحسوبة، والتي يتم تقييمها عند إنشاء سجل:

* `'uuid'` — يُنشِئ UUID (لحقول `UUID`)
* `'now'` — الطابع الزمني الحالي (لحقول `DATE_TIME`)

ينطبق نفس الاصطلاح على الحقول الفرعية النصية للقيم الافتراضية المركّبة (على سبيل المثال `{ source: "'MANUAL'" }` في حقل `ACTOR`) وكذلك على قيم `SELECT`/`MULTI_SELECT`. سيتسبّب ترك قيمة افتراضية نصية حرفية بدون علامات اقتباس في ظهور تحذير عند إنشاء التطبيق.

## قابلية قبول NULL

`isNullable` تتحكم في ما إذا كان الحقل يقبل `NULL`. القيمة الافتراضية هي `true` — يمكنك حذفها من الحقول الاختيارية. عيِّن `isNullable: false` لجعل الحقل مطلوبًا على مستوى قاعدة البيانات.

يتم تطبيق التغييرات على `isNullable` في كل عملية مزامنة، بما في ذلك عمليات المزامنة التي تحدّث حقلًا موجودًا — وبالتالي يمكنك تبديل قابلية الحقل لقبول NULL عن طريق تعديل ملف manifest وإعادة المزامنة.

<Note>
**جعل حقل موجود غير قابل لأن يكون فارغًا يتطلب قيمة افتراضية.** عندما تغيّر حقلًا إلى `isNullable: false`، يجب أيضًا توفير `defaultValue` غير فارغ. القيمة الافتراضية تملأ أي صفوف موجودة تحتوي على `NULL` قبل تطبيق القيد `NOT NULL`؛ من دونها تفشل المزامنة مع الخطأ `Default value cannot be null for non-nullable fields`. حقول العلاقات وحقول `TS_VECTOR` تكون دائمًا قابلة لأن تكون فارغة، لذلك لا يكون لـ `isNullable` أي تأثير عليها.
</Note>

```ts
{
  universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
  name: 'reference',
  type: FieldType.TEXT,
  label: 'Reference',
  isNullable: false,
  defaultValue: "'N/A'",
}
```

## ماذا بعد؟

* **اربط هذا الكائن بغيره من الكائنات** — راجع صفحة [Relations](/l/ar/developers/extend/apps/data/relations) لمعرفة نمط العلاقة ثنائية الاتجاه.
* **أضف حقولًا إلى الكائنات التابعة لتطبيقات أخرى** — راجع [Extending Objects](/l/ar/developers/extend/apps/data/extending-objects) لمعرفة المزيد حول `defineField()`.
* **اعرض هذا الكائن في واجهة المستخدم (UI)** — راجع [عناصر قائمة التنقل](/l/ar/developers/extend/apps/layout/navigation-menu-items) لإضافة عنصر في الشريط الجانبي؛ وراجع [طرق العرض](/l/ar/developers/extend/apps/layout/views) لإضافة تكوينات قوائم مخصصة.