Zum Hauptinhalt springen
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.

​
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.

​
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.