对象

使用 defineObject 声明新的记录类型——具有其自身字段的自定义表。

自定义对象是你的应用在工作区中添加的新记录类型——Post Card、Invoice、Subscription，或任何特定于你业务领域的内容。 每个对象都会声明其模式（字段、关系、默认值）以及一个在多次同步和部署中保持稳定的通用标识符。

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 数组是可选的——你可以定义没有自定义字段的对象。
• 此处定义的内联字段不需要 objectUniversalIdentifier——它会从父对象继承。 使用defineField()为你不拥有的对象添加字段。
• 你可以使用 yarn twenty dev:add object 脚手架创建新对象，它会引导你完成命名、字段和关系。 参见 Architecture → Scaffolding entities。

基础字段会自动添加。 当你定义自定义对象时，Twenty 会为你创建标准字段，例如 id、name、createdAt、updatedAt、createdBy、updatedBy 和 deletedAt。 你无需在 fields 数组中声明这些字段——只需声明你的自定义字段。 你可以通过声明一个同名字段来覆盖默认字段，但这么做通常并不是一个好主意。

​

默认值

字面量字符串默认值必须在字符串内部用单引号包裹——应写成 defaultValue: "'Draft'"，而不是 defaultValue: "Draft"。 这就是上面的 status 字段使用 `'${PostCardStatus.DRAFT}'` 的原因。

未加引号的字符串保留用于计算得到的默认值，这些默认值会在创建记录时进行求值：

• 'uuid' — 生成一个 UUID（用于 UUID 字段）
• 'now' — 当前时间戳（用于 DATE_TIME 字段）

同样的约定也适用于复合默认值的字符串子字段（例如 ACTOR 字段上的 { source: "'MANUAL'" }）以及 SELECT/MULTI_SELECT 值。 在构建应用时，未加引号的字面字符串默认值会触发警告。

​

接下来

• 将此对象与其他对象关联——关于双向关系模式，参见 Relations。
• 为其他应用的对象添加字段——关于 defineField()，参见 Extending Objects。
• 在 UI 中展示此对象——参见 Views 和 Navigation Menu Items，将其放入侧边栏。