The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Объекты
description: Объявляйте новые типы записей — пользовательские таблицы с собственными полями — с помощью defineObject.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## Обзор
Пользовательские **объекты** — это новые типы записей, которые ваше приложение добавляет в рабочее пространство — открытка, счёт-фактура, подписка, что‑то специфичное для вашей предметной области. Каждый объект объявляет свою схему (поля, связи, значения по умолчанию) и стабильный универсальный идентификатор, который сохраняется между синхронизациями и развёртываниями.
```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` для записей, которые уместны только в виде быстрой боковой панели (как события календаря).
* `disabledObjectPermissionActions` перечисляет разрешения объекта, которые нельзя предоставить для объекта: любое из `'canReadObjectRecords'`, `'canUpdateObjectRecords'`, `'canSoftDeleteObjectRecords'` и `'canDestroyObjectRecords'` — те же флаги, которые роль задает для каждого объекта. Пользователи, API-ключи и агенты никогда не получают эти действия для объекта, независимо от того, что позволяет их роль, и сохранение разрешения объекта, предоставляющего одно из них, завершается ошибкой. Их сохраняют собственные логические функции вашего приложения. Например, `['canUpdateObjectRecords', 'canSoftDeleteObjectRecords', 'canDestroyObjectRecords']` делает объект доступным для записи только вашему приложению, для записей, подобных конфигурационным, которые определяют поведение.
* `color` задаёт цвет акцента объекта в пользовательском интерфейсе. Не указывайте его, и Twenty выберет его для объекта.
* `imageIdentifierFieldMetadataUniversalIdentifier` указывает поле, значение которого отображается в качестве аватара записи. Не указывайте его, чтобы Twenty выбрала значение по умолчанию.
* `isLabelSyncedWithName` для объекта или поля синхронизирует имя API с меткой при редактировании метки в настройках. По умолчанию используется значение `false`, поэтому переименование метки не изменяет имя.
* `isSearchable: true` для поля включает его значения в полнотекстовый поиск объекта (глобальный поиск и меню команд). Для этого сам объект должен поддерживать поиск, а тип поля должен быть совместим с текстом. Отсутствующее значение означает, что поиск недоступен, за исключением поля идентификатора метки объекта, для которого поиск всегда доступен и которое нельзя исключить. Каждая синхронизация применяет объявленное состояние, поэтому поле, для которого в настройках включили поиск, вернётся к прежнему состоянию при следующей синхронизации приложения, если это не объявлено в манифесте.
* `isAuditLogged: false` для поля исключает его изменения из хронологии записи. По умолчанию используется `true`, кроме поля `POSITION`, изменения которого отображаются в хронологии пустыми и никогда не регистрируются. Установите это для полей, которые ваше приложение переписывает по расписанию, например для метки времени последнего контакта или сводной связи, чтобы каждая синхронизация не добавляла строку активности в каждую затронутую запись. Обновление, вся разница которого состоит из не журналируемых для аудита полей, вообще не создаёт активности в хронологии. Как и `isSearchable`, каждая синхронизация обеспечивает объявленное состояние.
* `disabledFieldPermissionActions` в поле перечисляет разрешения поля, которые нельзя предоставить для него: `'canReadFieldValue'`, `'canUpdateFieldValue'` или оба — те же флаги, которые роль задаёт для каждого поля. Пользователи, ключи API, агенты и другие приложения никогда не получают эти действия для поля независимо от разрешений, предоставленных их ролью, а сохранение разрешения поля, предоставляющего одно из них, завершается ошибкой. Собственные логические функции вашего приложения сохраняют их. Например, `['canUpdateFieldValue']` сохраняет значение, которое ваше приложение вычисляет или синхронизирует, например статус или оценку, доступным только для чтения для всех остальных. Это также работает с полями, которые вы добавляете в объекты, не принадлежащие вам, с помощью `defineField()`.
* Встроенным полям, определённым здесь, **не** нужен `objectUniversalIdentifier` — он наследуется от родительского объекта. Используйте [`defineField()`](/ru/developers/extend/apps/data/extending-objects), чтобы добавить поля к объектам, которые вам не принадлежат.
* Вы можете сгенерировать заготовки новых объектов с помощью `twenty app add object`, который проведёт вас через настройку названий, полей и связей. См. [Architecture → Scaffolding entities](/ru/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` (`universalSettings.type`: `'url'` (по умолчанию) / `'domain'` — поле домена хранит только хост, поэтому `https://www.acme.com/careers` записывается как `acme.com`, а значение, не являющееся хостом, отклоняется), `CURRENCY`, `ACTOR`, `FILES` |
| Идентификаторы и связи | `UUID`, `RELATION`, `MORPH_RELATION` (см. [Relations](/ru/developers/extend/apps/data/relations)) |
| Система | `TS_VECTOR` (вектор полнотекстового поиска, управляется сервером) |
Составные типы хранят несколько подполей (например, `FULL_NAME` = имя + фамилия; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` и `MULTI_SELECT` требуют массива `options`, как в примере выше.
### Выберите параметры
Для `SELECT` и `MULTI_SELECT` укажите непустой массив объектов `options`. У каждого варианта есть `value`, `label` и `position`. Его `color` необязателен; при отсутствии или значении null по умолчанию используется `gray`.
Если указано, значение `color` должно быть одним из следующих: `red`, `ruby`, `crimson`, `tomato`, `orange`, `amber`, `yellow`, `lime`, `grass`, `green`, `jade`, `mint`, `turquoise`, `cyan`, `sky`, `blue`, `iris`, `violet`, `purple`, `plum`, `pink`, `bronze`, `gold`, `brown`, `gray`.
И `defineObject()`, и `defineField()` возвращают ошибки валидации для неподдерживаемых цветов или записей параметров, являющихся null, примитивами или массивами.
## Значения по умолчанию
Строковые значения по умолчанию должны быть заключены в одинарные кавычки **внутри** строки — `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 для поля, отредактировав манифест и повторно выполнив синхронизацию.
<Note>
**Для существующего обязательного поля требуется значение по умолчанию.** При изменении поля на `isNullable: false` необходимо также указать не равное NULL значение `defaultValue`. Значение по умолчанию заполняет все существующие строки с `NULL` перед применением ограничения `NOT
NULL`; без него синхронизация завершится с ошибкой `Default value
cannot be null for non-nullable fields`. Поля связей и поля `TS_VECTOR`
всегда допускают значение NULL, поэтому параметр `isNullable` на них не влияет.
</Note>
```ts
{
universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
name: 'reference',
type: FieldType.TEXT,
label: 'Reference',
isNullable: false,
defaultValue: "'N/A'",
}
```
## Что дальше
* **Свяжите этот объект с другими** — см. [Relations](/ru/developers/extend/apps/data/relations) для двунаправленного шаблона связей.
* **Добавляйте поля к объектам из других приложений** — см. [Extending Objects](/ru/developers/extend/apps/data/extending-objects) о `defineField()`.
* **Отображать этот объект в интерфейсе** — см. [пункты меню навигации](/ru/developers/extend/apps/layout/navigation-menu-items), чтобы добавить пункт бокового меню; см. [представления](/ru/developers/extend/apps/layout/views), чтобы добавить пользовательские настройки списков.
<PageBanner illustration="card-page-objects" />