Objekty

Vlastní objekty jsou nové typy záznamů, které vaše aplikace přidává do pracovního prostoru — pohlednice, faktura, předplatné, cokoli specifického pro vaši doménu. Každý objekt definuje své schéma (pole, vztahy, výchozí hodnoty) a stabilní univerzální identifikátor, který přetrvá mezi synchronizacemi a nasazeními.

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,
    },
  ],
});

Hlavní body

Hodnota universalIdentifier musí být jedinečná a stabilní napříč nasazeními.
Každé pole vyžaduje name, type, label a svůj vlastní stabilní universalIdentifier.
Pole fields je volitelné — objekty můžete definovat i bez vlastních polí.
openRecordIn určuje, kde se záznamy tohoto objektu otevřou po kliknutí: ObjectOpenRecordIn.USER_CHOICE (výchozí nastavení, které respektuje individuální předvolbu každého člena pracovního prostoru v Settings → Experience), ObjectOpenRecordIn.SIDE_PANEL nebo ObjectOpenRecordIn.RECORD_PAGE. Připněte jej k RECORD_PAGE pro záznamy, které ke svému používání potřebují celou stránku, stejně jako pracovní postupy a řídicí panely, nebo k SIDE_PANEL pro záznamy, které dávají smysl jen jako rychlý panel, podobně jako události v kalendáři.
writability určuje, kdo vůbec smí zapisovat záznamy objektu, ještě předtím, než se uplatní oprávnění rolí: MetadataWritability.OPEN (výchozí – rozhodují role ve workspace), MetadataWritability.APPLICATION (záznamy mohou vytvářet, aktualizovat nebo mazat pouze logické funkce samotné aplikace; použijte pro objekty podobné konfiguraci, jejichž záznamy určují chování, aby je členové workspace s širokým přístupem k záznamům nemohli upravovat přes API) nebo MetadataWritability.SYSTEM (vyhrazeno pro data spravovaná platformou). Čtení nejsou ovlivněna – toto je vynucováno na straně serveru, na rozdíl od isUIEditable, které pouze skrývá prvky uživatelského rozhraní. Existuje také na úrovni jednotlivých polí, kde může být pouze přísnější než na úrovni objektu.
Pole definovaná zde inline nepotřebují objectUniversalIdentifier — dědí se z nadřazeného objektu. Pomocí defineField() můžete přidávat pole k objektům, které nevlastníte.
Nové objekty můžete vygenerovat pomocí yarn twenty dev:add object, který vás provede pojmenováním, poli a vztahy. Viz Architektura → Scaffolding entit.

Základní pole jsou přidána automaticky. Když definujete vlastní objekt, Twenty pro vás vytvoří standardní pole jako id, name, createdAt, updatedAt, createdBy, updatedBy a deletedAt. Nemusíte je uvádět v poli fields — pouze svá vlastní pole. Výchozí pole můžete přepsat tak, že deklarujete pole se stejným názvem, ale jen zřídka je to dobrý nápad.

Typy polí

Úplná sada hodnot FieldType, exportovaných z twenty-sdk/define:

Kategorie	Typy
Text	`TEXT`, `RICH_TEXT`, `ARRAY` (řetězců), `RAW_JSON`
Číselné	`NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (libovolná přesnost), `RATING`, `POSITION`
Datumy	`DATE`, `DATE_TIME`
Výběr	`BOOLEAN`, `SELECT`, `MULTI_SELECT`
Složené	`FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS`, `CURRENCY`, `ACTOR`, `FILES`
Identifikátory a relace	`UUID`, `RELATION`, `MORPH_RELATION` (viz Relations)
Systém	`TS_VECTOR` (vektor pro fulltextové vyhledávání, spravovaný serverem)

Složené typy ukládají více podpolí (např. FULL_NAME = křestní jméno + příjmení; CURRENCY = amountMicros + currencyCode). SELECT a MULTI_SELECT vyžadují pole options, jak je ukázáno v příkladu výše.

Výchozí hodnoty

Výchozí textové hodnoty musí být uzavřené v jednoduchých uvozovkách uvnitř řetězce — defaultValue: "'Draft'", ne defaultValue: "Draft". Proto pole status výše používá `'${PostCardStatus.DRAFT}'`. Neuzavřené (necitované) řetězce jsou vyhrazené pro vypočítané výchozí hodnoty, které se vyhodnocují při vytvoření záznamu:

'uuid' — generuje UUID (pro pole UUID)
'now' — aktuální časové razítko (pro pole DATE_TIME)

Stejná konvence platí pro řetězcová podpola složených výchozích hodnot (např. { source: "'MANUAL'" } u pole ACTOR) a pro hodnoty SELECT/MULTI_SELECT. Doslovná řetězcová výchozí hodnota ponechaná bez uvozovek vyvolá při sestavení aplikace varování.

Možnost hodnoty NULL

isNullable určuje, zda pole přijímá NULL. Výchozí hodnota je true — pro volitelná pole ji můžete vynechat. Nastavte isNullable: false, aby bylo pole vyžadováno na úrovni databáze. Změny isNullable se použijí při každé synchronizaci, včetně těch, které aktualizují existující pole — takže můžete změnit, zda pole přijímá hodnotu NULL, úpravou manifestu a opětovnou synchronizací.

Změna existujícího pole tak, aby neumožňovalo hodnotu NULL, vyžaduje výchozí hodnotu. Když změníte pole na isNullable: false, musíte také zadat nenulovou hodnotu defaultValue. Výchozí hodnota doplní všechny existující řádky s hodnotou NULL ještě předtím, než se uplatní omezení NOT NULL; bez ní synchronizace selže s chybou Default value cannot be null for non-nullable fields. Relační pole a pole typu TS_VECTOR vždy umožňují hodnotu NULL, takže na ně isNullable nemá žádný efekt.

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

Co dál

Propojte tento objekt s ostatními — vzor obousměrných vztahů najdete v části Relations.
Přidávejte pole k objektům z jiných aplikací — viz Extending Objects pro defineField().
Zobrazit tento objekt v uživatelském rozhraní — viz Položky navigační nabídky pro přidání položky do postranního panelu; viz Zobrazení pro přidání vlastních konfigurací seznamu.

Přehled

Aplikace

API

Vlastní hosting

Přispět

Hlavní body

Typy polí

Výchozí hodnoty

Možnost hodnoty NULL

Co dál

​Hlavní body

​Typy polí

​Výchozí hodnoty

​Možnost hodnoty NULL

​Co dál

Hlavní body

Typy polí

Výchozí hodnoty

Možnost hodnoty NULL

Co dál