snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/developers/extend/apps/data/extending-objects.mdx

@@ -0,0 +1,52 @@
+---
+title: 扩展对象
+description: 向标准 Twenty 对象添加字段（Person、Company 等） 或使用 defineField 向其他应用的对象添加字段。
+icon: wand-magic-sparkles
+---
+
+使用 `defineField()` 为你不拥有的对象添加字段——例如像 Person 或 Company 这样的标准 Twenty 对象，或由其他已安装应用提供的对象。 与在 [`defineObject`](/l/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` 保留用于平台管理的数据。 字段的可写性只能比其所属对象的级别更严格，读取操作不会受到影响。 有关完整语义，请参见[对象](/l/zh/developers/extend/apps/data/objects)。
+
+* 要在标准页面布局（例如任务或公司详情页面）中添加一个选项卡，请使用 [`definePageLayoutTab`](/l/zh/developers/extend/apps/layout/page-layouts#definepagelayouttab)，并结合来自 `twenty-sdk/define` 的 `STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS`。
+
+## 向现有对象添加关系
+
+要添加关系字段（例如将你的自定义对象链接到标准 `Person`），请将 `defineField()` 与 `FieldType.RELATION` 一起使用。 模式与内联关系相同，但需要显式设置 `objectUniversalIdentifier`。 有关双向模式，请参见[关系](/l/zh/developers/extend/apps/data/relations)。