---
title: 布局
description: 定义视图、导航菜单项和页面布局，以塑造你的应用在 Twenty 中的呈现方式。
icon: table-columns
---

布局实体控制你的应用如何在 Twenty 的 UI 中呈现——侧边栏中有哪些内容、应用随附哪些已保存的视图，以及记录详情页如何排布。

## 布局概念

| 概念          | 控制内容                                | 实体                         |
| ----------- | ----------------------------------- | -------------------------- |
| **视图**      | 对象的已保存列表配置——可见字段、顺序、筛选器、分组          | `defineView`               |
| **导航菜单项**   | 左侧侧边栏中的一项，链接到某个视图或外部 URL            | `defineNavigationMenuItem` |
| **页面布局**    | 构成记录详情页的选项卡和小部件                     | `definePageLayout`         |
| **页面布局选项卡** | 附加到现有页面布局（标准页面布局或你自己的应用的页面布局）的独立选项卡 | `definePageLayoutTab`      |

视图、导航菜单项和页面布局通过 `universalIdentifier` 相互引用：

* 类型为 `VIEW` 的**导航菜单项**指向一个 `defineView` 标识符，因此侧边栏链接会打开该已保存视图。
* 类型为 `RECORD_PAGE` 的**页面布局**面向某个对象，并可在其选项卡内嵌入[前端组件](/l/zh/developers/extend/apps/front-components)作为小部件。

<AccordionGroup>
<Accordion title="defineView" description="为对象定义已保存的视图">

视图是关于对象记录如何显示的已保存配置——包括哪些字段可见、它们的顺序，以及应用的任何筛选器或分组。 使用 `defineView()` 随你的应用一起提供预配置的视图：

```ts src/views/example-view.ts
import { defineView, ViewKey } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';

export default defineView({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'All example items',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  key: ViewKey.INDEX,
  position: 0,
  fields: [
    {
      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});
```

关键点：
* `objectUniversalIdentifier` 指定此视图适用于哪个对象。
* `key` 决定视图类型（例如，主列表视图使用 `ViewKey.INDEX`）。
* `fields` 控制显示哪些列及其顺序。 每个字段引用一个 `fieldMetadataUniversalIdentifier`。
* 你还可以定义 `filters`、`filterGroups`、`groups` 和 `fieldGroups` 以进行更高级的配置。
* `position` 在同一对象存在多个视图时控制其排序。

</Accordion>
<Accordion title="defineNavigationMenuItem" description="定义侧边栏导航链接">

导航菜单项会在工作区侧边栏中添加自定义条目。 使用 `defineNavigationMenuItem()` 链接到视图、外部 URL 或对象：

```ts src/navigation-menu-items/example-navigation-menu-item.ts
import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';

export default defineNavigationMenuItem({
  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
  name: 'example-navigation-menu-item',
  icon: 'IconList',
  color: 'blue',
  position: 0,
  type: NavigationMenuItemType.VIEW,
  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
});
```

关键点：
* `type` 决定菜单项链接到的目标：`NavigationMenuItemType.VIEW` 表示已保存视图，`NavigationMenuItemType.LINK` 表示外部 URL。
* 对于视图链接，设置 `viewUniversalIdentifier`。 对于外部链接，设置 `link`。
* `position` 控制在侧边栏中的排序。
* `icon` 和 `color`（可选）用于自定义外观。

</Accordion>
<Accordion title="definePageLayout" description="为记录视图定义自定义页面布局">

页面布局使你可以自定义记录详情页的外观——显示哪些选项卡、每个选项卡内有哪些小部件，以及它们如何排列。 使用 `definePageLayout()` 随你的应用一起提供自定义布局：

```ts src/page-layouts/example-record-page-layout.ts
import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayout({
  universalIdentifier: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
  name: 'Example Record Page',
  type: 'RECORD_PAGE',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  tabs: [
    {
      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
      title: 'Hello World',
      position: 50,
      icon: 'IconWorld',
      layoutMode: PageLayoutTabLayoutMode.CANVAS,
      widgets: [
        {
          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
          title: 'Hello World',
          type: 'FRONT_COMPONENT',
          configuration: {
            configurationType: 'FRONT_COMPONENT',
            frontComponentUniversalIdentifier:
              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
          },
        },
      ],
    },
  ],
});
```

关键点：
* `type` 通常为 'RECORD_PAGE'，用于自定义特定对象的详情视图。
* `objectUniversalIdentifier` 指定此布局适用于哪个对象。
* 每个 `tab` 使用 `title`、`position` 和 `layoutMode` 定义页面的一个部分（`CANVAS` 表示自由布局）。
* 选项卡内的每个 `widget` 可以渲染一个前端组件、关系列表或其他内置小部件类型。
* 选项卡上的 `position` 控制其顺序。 使用更高的值（例如 50）可将自定义选项卡放在内置选项卡之后。

</Accordion>
<Accordion title="definePageLayoutTab" description="向现有页面布局添加一个选项卡">

`definePageLayoutTab` 允许你的应用将单个选项卡 — 可选小部件 — 附加到一个**现有**页面布局。 最常见的用例是向 Twenty 内置的某个记录页面添加自定义选项卡（例如，分析或 AI 摘要选项卡），或向你的应用已随附的页面布局添加该选项卡。

目标页面布局必须是 **标准** 的 Twenty 页面布局，或由 **你自己的应用** 定义的布局；目前不支持跨应用引用由其他已安装应用拥有的页面布局。

```ts src/page-layouts/example-extra-tab.ts
import {
  definePageLayoutTab,
  PageLayoutTabLayoutMode,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
  '20202020-ab01-4001-8001-c0aba11c0100';

export default definePageLayoutTab({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
  pageLayoutUniversalIdentifier:
    COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
  title: 'Hello World',
  position: 1000,
  icon: 'IconWorld',
  layoutMode: PageLayoutTabLayoutMode.CANVAS,
  widgets: [
    {
      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
      title: 'Hello World',
      type: 'FRONT_COMPONENT',
      configuration: {
        configurationType: 'FRONT_COMPONENT',
        frontComponentUniversalIdentifier:
          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
      },
    },
  ],
});
```

关键点：
* `pageLayoutUniversalIdentifier` 在使用 `definePageLayoutTab` 时是**必需**的，并且必须指向在安装时已存在的页面布局（标准布局或你的应用的布局）。 当父页面布局缺失时，安装会失败，并给出清晰的验证错误。
* `widgets` 仅作用于此选项卡 — 它们引用前端组件、视图等，其方式与在 `definePageLayout` 中内联定义的小部件完全相同。
* `position` 控制目标布局中相对于现有选项卡的排序。 选择一个取值，使你的选项卡相对于内置选项卡位于你想要的位置。
* 当你只想向现有布局进行**添加**时，请使用此功能，而不是 `definePageLayout`。 当你拥有整个布局时，请使用 `definePageLayout`（通常是你在应用中提供的对象的 `RECORD_PAGE`，或 `STANDALONE_PAGE`）。

</Accordion>
</AccordionGroup>