Objekte

Deklarieren Sie neue Datensatztypen — benutzerdefinierte Tabellen mit eigenen Feldern — mit defineObject.

Benutzerdefinierte Objekte sind neue Datensatztypen, die Ihre App zu einem Arbeitsbereich hinzufügt – Postkarte, Rechnung, Abonnement, alles, was spezifisch für Ihre Domäne ist. Jedes Objekt deklariert sein Schema (Felder, Relationen, Standardwerte) und einen stabilen universellen Bezeichner, der über Synchronisierungen und Deployments hinweg bestehen bleibt.

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

​

Hauptpunkte

• Der universalIdentifier muss eindeutig und über Deployments hinweg stabil sein.
• Jedes Feld benötigt name, type, label und einen eigenen stabilen universalIdentifier.
• Das Array fields ist optional — Sie können Objekte ohne benutzerdefinierte Felder definieren.
• Inline definierte Felder benötigen kein objectUniversalIdentifier – er wird vom übergeordneten Objekt geerbt. Verwenden Sie defineField(), um Objekten Felder hinzuzufügen, die Ihnen nicht gehören.
• Sie können mit yarn twenty dev:add object neue Objekte erzeugen; der Assistent führt Sie durch Benennung, Felder und Beziehungen. Siehe Architektur → Gerüste für Entitäten.

Basisfelder werden automatisch hinzugefügt. Wenn Sie ein benutzerdefiniertes Objekt definieren, erstellt Twenty Standardfelder wie id, name, createdAt, updatedAt, createdBy, updatedBy und deletedAt für Sie. Sie müssen diese nicht in Ihrem fields-Array deklarieren – nur Ihre benutzerdefinierten Felder. Sie können ein Standardfeld überschreiben, indem Sie eines mit demselben Namen deklarieren, aber das ist nur selten eine gute Idee.

​

Feldtypen

Die vollständige Menge von FieldType-Werten, exportiert aus twenty-sdk/define:

Kategorie	Typen
Text	TEXT, RICH_TEXT, ARRAY (von Zeichenketten), RAW_JSON
Numerisch	NUMBER (universalSettings.dataType: 'float' / 'int' / 'bigint'), NUMERIC (beliebige Genauigkeit), RATING, POSITION
Datumsangaben	DATE, DATE_TIME
Auswahl	BOOLEAN, SELECT, MULTI_SELECT
Zusammengesetzt	FULL_NAME, ADDRESS, EMAILS, PHONES, LINKS, CURRENCY, ACTOR, FILES
Bezeichner & Relationen	UUID, RELATION, MORPH_RELATION (siehe Relationen)
System	TS_VECTOR (Volltext-Suchvektor, vom Server verwaltet)

Zusammengesetzte Typen speichern mehrere Unterfelder (z. B. FULL_NAME = Vorname + Nachname; CURRENCY = amountMicros + currencyCode). SELECT und MULTI_SELECT erfordern ein options-Array wie im obigen Beispiel.

​

Standardwerte

Wörtliche Zeichenfolgen-Standardwerte müssen in einfache Anführungszeichen innerhalb der Zeichenfolge eingeschlossen werden — defaultValue: "'Draft'", nicht defaultValue: "Draft". Deshalb verwendet das status-Feld oben `'${PostCardStatus.DRAFT}'`.

Nicht in Anführungszeichen gesetzte Zeichenfolgen sind für berechnete Standardwerte reserviert, die ausgewertet werden, wenn ein Datensatz erstellt wird:

• 'uuid' — generiert eine UUID (für UUID-Felder)
• 'now' — der aktuelle Zeitstempel (für DATE_TIME-Felder)

Dieselbe Konvention gilt für Zeichenketten-Unterfelder zusammengesetzter Standardwerte (z. B. { source: "'MANUAL'" } in einem ACTOR-Feld) und für SELECT-/MULTI_SELECT-Werte. Ein wörtlicher Zeichenfolgen-Standardwert, der nicht in Anführungszeichen gesetzt ist, löst beim Build deiner App eine Warnung aus.

​

Nullbarkeit

isNullable steuert, ob ein Feld NULL akzeptiert. Standardmäßig ist es true – lasse es für optionale Felder weg. Setze isNullable: false, um ein Feld auf Datenbankebene erforderlich zu machen.

Änderungen an isNullable werden bei jedem Sync angewendet, einschließlich Syncs, die ein vorhandenes Feld aktualisieren – so kannst du die Nullbarkeit eines Feldes ändern, indem du das Manifest bearbeitest und erneut synchronisierst.

Das Ändern eines vorhandenen Feldes in nicht nullbar erfordert einen Standardwert. Wenn du ein Feld auf isNullable: false änderst, musst du auch einen defaultValue angeben, der nicht NULL ist. Der Standardwert füllt alle vorhandenen NULL-Zeilen auf, bevor die NOT NULL-Einschränkung angewendet wird; ohne ihn schlägt die Synchronisierung mit Default value cannot be null for non-nullable fields fehl. Relationsfelder und TS_VECTOR-Felder sind immer nullbar, daher hat isNullable keine Auswirkung auf sie.

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

​

Was kommt als Nächstes

• Verbinden Sie dieses Objekt mit anderen – siehe Relationen für das bidirektionale Relationsmuster.
• Fügen Sie Objekten aus anderen Apps Felder hinzu – siehe Objekte erweitern für defineField().
• Zeigen Sie dieses Objekt in der UI an – siehe Ansichten und Navigationsmenüeinträge, um es in der Seitenleiste zu platzieren.