Skip to content

The open alternative to Salesforce, designed for AI.

2.9 KB
Raw Blame
---
title: 扩展对象
description: 向标准 Twenty 对象添加字段(Person、Company 等) 或使用 defineField 向其他应用的对象添加字段。
---

使用 `defineField()` 为你不拥有的对象添加字段——例如像 Person 或 Company 这样的标准 Twenty 对象,或由其他已安装应用提供的对象。 与在 [`defineObject`](/zh/developers/extend/apps/data/objects) 中声明的内联字段不同,独立字段需要一个 `objectUniversalIdentifier` 来指定它们要扩展的对象。

```ts src/fields/company-loyalty-tier.field.ts
import { defineField, FieldType } from 'twenty-sdk/define';

export default defineField({
  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
  name: 'loyaltyTier',
  type: FieldType.SELECT,
  label: 'Loyalty Tier',
  icon: 'IconStar',
  options: [
    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
  ],
});
```

## 关键点

* `objectUniversalIdentifier` 用于标识目标对象。 对于标准 Twenty 对象,从 `twenty-sdk` 导入常量:

  ```ts
  import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';

  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier
  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier
  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity.universalIdentifier
  // …
  ```

* 在 **`defineObject()` 内联定义字段** 时,**不需要** `objectUniversalIdentifier`——它会从父对象继承。

* `defineField()` 是为非通过 `defineObject()` 创建的对象添加字段的唯一方式。

* 文件位置由你决定。 约定是使用 `src/fields/\<name>.field.ts`,但 SDK 会在整个 `src/` 中检测字段。

* `writability` 也可以按字段单独设置:`MetadataWritability.APPLICATION` 将写入限制为你应用自身的逻辑函数,`MetadataWritability.SYSTEM` 保留用于平台管理的数据。 字段的可写性只能比其所属对象的级别更严格,读取操作不会受到影响。 有关完整语义,请参见[对象](/zh/developers/extend/apps/data/objects)。

* 要在标准页面布局(例如任务或公司详情页面)中添加一个选项卡,请使用 [`definePageLayoutTab`](/zh/developers/extend/apps/layout/page-layouts#definepagelayouttab),并结合来自 `twenty-sdk/define` 的 `STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS`。

## 向现有对象添加关系

要添加关系字段(例如将你的自定义对象链接到标准 `Person`),请将 `defineField()` 与 `FieldType.RELATION` 一起使用。 模式与内联关系相同,但需要显式设置 `objectUniversalIdentifier`。 有关双向模式,请参见[关系](/zh/developers/extend/apps/data/relations)。