--- 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/ru/developers/extend/apps/data/extending-objects), чтобы добавить поля к объектам, которые вам не принадлежат. * Вы можете сгенерировать заготовки новых объектов с помощью `yarn twenty dev:add object`, который проведёт вас через настройку названий, полей и связей. См. [Architecture → Scaffolding entities](/l/ru/developers/extend/apps/getting-started/scaffolding). **Базовые поля добавляются автоматически.** Когда вы определяете пользовательский объект, Twenty создаёт для вас стандартные поля, такие как `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` и `deletedAt`. Вам не нужно объявлять их в массиве `fields` — только ваши пользовательские поля. Вы можете переопределить базовое поле, объявив поле с тем же именем, но это редко бывает хорошей идеей. ## Типы полей Полный набор значений `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` (см. [Relations](/l/ru/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 для поля, отредактировав манифест и повторно выполнив синхронизацию. **Чтобы сделать существующее поле не допускающим значение NULL, требуется значение по умолчанию.** Когда вы изменяете поле на `isNullable: false`, вы также должны предоставить значение `defaultValue`, отличное от `NULL`. Значение по умолчанию заполняет все существующие строки с `NULL` перед применением ограничения `NOT NULL`; без него синхронизация завершится с ошибкой `Default value cannot be null for non-nullable fields`. Поля связей и поля `TS_VECTOR` всегда допускают значение NULL, поэтому параметр `isNullable` на них не влияет. ```ts { universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000', name: 'reference', type: FieldType.TEXT, label: 'Reference', isNullable: false, defaultValue: "'N/A'", } ``` ## Что дальше * **Свяжите этот объект с другими** — см. [Relations](/l/ru/developers/extend/apps/data/relations) для двунаправленного шаблона связей. * **Добавляйте поля к объектам из других приложений** — см. [Extending Objects](/l/ru/developers/extend/apps/data/extending-objects) о `defineField()`. * **Отображать этот объект в интерфейсе** — см. [пункты меню навигации](/l/ru/developers/extend/apps/layout/navigation-menu-items), чтобы добавить пункт бокового меню; см. [представления](/l/ru/developers/extend/apps/layout/views), чтобы добавить пользовательские настройки списков.