布局 - Twenty Documentation

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

defineView

为对象定义已保存的视图

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

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 在同一对象存在多个视图时控制其排序。

defineNavigationMenuItem

定义侧边栏导航链接

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

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（可选）用于自定义外观。

definePageLayout

为记录视图定义自定义页面布局

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

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）可将自定义选项卡放在内置选项卡之后。

definePageLayoutTab

向现有页面布局添加一个选项卡

definePageLayoutTab 允许你的应用将单个选项卡 — 可选小部件 — 附加到一个现有页面布局。最常见的用例是向 Twenty 内置的某个记录页面添加自定义选项卡（例如，分析或 AI 摘要选项卡），或向你的应用已随附的页面布局添加该选项卡。目标页面布局必须是标准的 Twenty 页面布局，或由 你自己的应用 定义的布局；目前不支持跨应用引用由其他已安装应用拥有的页面布局。

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）。

​布局概念

布局概念