Объекты

Обзор

Пользовательские объекты — это новые типы записей, которые ваше приложение добавляет в рабочее пространство — открытка, счёт-фактура, подписка, что‑то специфичное для вашей предметной области. Каждый объект объявляет свою схему (поля, связи, значения по умолчанию) и стабильный универсальный идентификатор, который сохраняется между синхронизациями и развёртываниями.

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(), чтобы добавить поля к объектам, которые вам не принадлежат.
Вы можете сгенерировать заготовки новых объектов с помощью twenty app add object, который проведёт вас через настройку названий, полей и связей. См. Architecture → Scaffolding entities.

Базовые поля добавляются автоматически. Когда вы определяете пользовательский объект, 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` (`universalSettings.type`: `'url'` (по умолчанию) / `'domain'` — поле домена хранит только хост, поэтому `https://www.acme.com/careers` записывается как `acme.com`, а значение, не являющееся хостом, отклоняется), `CURRENCY`, `ACTOR`, `FILES`
Идентификаторы и связи	`UUID`, `RELATION`, `MORPH_RELATION` (см. 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 для поля, отредактировав манифест и повторно выполнив синхронизацию.

Для существующего обязательного поля требуется значение по умолчанию. При изменении поля на isNullable: false необходимо также указать не равное NULL значение defaultValue. Значение по умолчанию заполняет все существующие строки с NULL перед применением ограничения NOT NULL; без него синхронизация завершится с ошибкой Default value cannot be null for non-nullable fields. Поля связей и поля TS_VECTOR всегда допускают значение NULL, поэтому параметр isNullable на них не влияет.

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

Что дальше

Свяжите этот объект с другими — см. Relations для двунаправленного шаблона связей.
Добавляйте поля к объектам из других приложений — см. Extending Objects о defineField().
Отображать этот объект в интерфейсе — см. пункты меню навигации, чтобы добавить пункт бокового меню; см. представления, чтобы добавить пользовательские настройки списков.

Разработчики

Приложения

API

Самостоятельный хостинг

Внести вклад

Библиотека интерфейса

Обзор

Основные моменты

Типы полей

Выберите параметры

Значения по умолчанию

Допустимость значения NULL

Что дальше

​Обзор

​Основные моменты

​Типы полей

​Выберите параметры

​Значения по умолчанию

​Допустимость значения NULL

​Что дальше

Обзор

Основные моменты

Типы полей

Выберите параметры

Значения по умолчанию

Допустимость значения NULL

Что дальше