github-actions[bot]
f2e7009baa
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22400?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
126 lines
5.7 KiB
Plaintext
126 lines
5.7 KiB
Plaintext
---
|
|
title: 对象
|
|
description: 使用 defineObject 声明新的记录类型——具有其自身字段的自定义表。
|
|
icon: table
|
|
---
|
|
|
|
自定义**对象**是你的应用在工作区中添加的新记录类型——Post Card、Invoice、Subscription，或任何特定于你业务领域的内容。 每个对象都会声明其模式（字段、关系、默认值）以及一个在多次同步和部署中保持稳定的通用标识符。
|
|
|
|
```ts 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()`](/l/zh/developers/extend/apps/data/extending-objects)为你不拥有的对象添加字段。
|
|
* 你可以使用 `yarn twenty dev:add object` 脚手架创建新对象，它会引导你完成命名、字段和关系。 参见 [Architecture → Scaffolding entities](/l/zh/developers/extend/apps/getting-started/scaffolding)。
|
|
|
|
<Note>
|
|
**基础字段会自动添加。** 当你定义自定义对象时，Twenty 会为你创建标准字段，例如 `id`、`name`、`createdAt`、`updatedAt`、`createdBy`、`updatedBy` 和 `deletedAt`。 你无需在 `fields` 数组中声明这些字段——只需声明你的自定义字段。 你可以通过声明一个同名字段来覆盖默认字段，但这么做通常并不是一个好主意。
|
|
</Note>
|
|
|
|
## 默认值
|
|
|
|
字面量字符串默认值必须在字符串**内部**用单引号包裹——应写成 `defaultValue: "'Draft'"`，而不是 `defaultValue: "Draft"`。 这就是上面的 `status` 字段使用 `` `'${PostCardStatus.DRAFT}'` `` 的原因。
|
|
|
|
未加引号的字符串保留用于计算得到的默认值，这些默认值会在创建记录时进行求值：
|
|
|
|
* `'uuid'` — 生成一个 UUID（用于 `UUID` 字段）
|
|
* `'now'` — 当前时间戳（用于 `DATE_TIME` 字段）
|
|
|
|
同样的约定也适用于复合默认值的字符串子字段（例如 `ACTOR` 字段上的 `{ source: "'MANUAL'" }`）以及 `SELECT`/`MULTI_SELECT` 值。 在构建应用时，未加引号的字面字符串默认值会触发警告。
|
|
|
|
## 可空性
|
|
|
|
`isNullable` 控制字段是否接受 `NULL`。 它默认是 `true` —— 对可选字段可以省略。 将 `isNullable` 设为 `false`，可在数据库层面将字段设为必填。
|
|
|
|
对 `isNullable` 的更改会在每次同步时应用，包括更新现有字段的同步——因此你可以通过编辑 manifest 并重新同步来切换字段的可空性。
|
|
|
|
<Note>
|
|
**将现有字段改为不可为空时需要提供默认值。** 当你将字段更改为 `isNullable: false` 时，还必须提供一个非空的 `defaultValue`。 在应用 `NOT NULL` 约束之前，默认值会为所有现有的 `NULL` 行进行回填；如果没有默认值，同步将失败，并出现错误：`Default value cannot be null for non-nullable fields`。 关系字段和 `TS_VECTOR` 字段始终可为空，因此 `isNullable` 对它们不起作用。
|
|
</Note>
|
|
|
|
```ts
|
|
{
|
|
universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
|
|
name: 'reference',
|
|
type: FieldType.TEXT,
|
|
label: 'Reference',
|
|
isNullable: false,
|
|
defaultValue: "'N/A'",
|
|
}
|
|
```
|
|
|
|
## 接下来
|
|
|
|
* **将此对象与其他对象关联**——关于双向关系模式，参见 [Relations](/l/zh/developers/extend/apps/data/relations)。
|
|
* **为其他应用的对象添加字段**——关于 `defineField()`，参见 [Extending Objects](/l/zh/developers/extend/apps/data/extending-objects)。
|
|
* **在 UI 中展示此对象**——参见 [Views](/l/zh/developers/extend/apps/layout/views) 和 [Navigation Menu Items](/l/zh/developers/extend/apps/layout/navigation-menu-items)，将其放入侧边栏。
|