Макеты страниц

​

Обзор

​

definePageLayout

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.VERTICAL_LIST,
      widgets: [
        {
          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
          title: 'Hello World',
          type: 'FRONT_COMPONENT',
          heightBehavior: 'TAB_VIEWPORT',
          configuration: {
            configurationType: 'FRONT_COMPONENT',
            frontComponentUniversalIdentifier:
              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
          },
        },
      ],
    },
  ],
});

​

Основные моменты

• type — одно из значений 'RECORD_INDEX', 'RECORD_PAGE', 'DASHBOARD', 'STANDALONE_PAGE' или 'RECORD_FORM'. Используйте 'RECORD_PAGE' для настройки детального представления конкретного объекта. 'RECORD_FORM' описывает форму создания объекта и содержит виджеты FORM_FIELD, каждый из которых отображает одно поле. Twenty предоставляет один макет 'RECORD_FORM' на объект с одним виджетом на каждое доступное для создания поле, поэтому вам редко потребуется создавать такой макет; пока он не отображает формы записей.
• objectUniversalIdentifier указывает, к какому объекту применяется этот макет.
• Каждая tab определяет раздел страницы с title, position и layoutMode: используйте VERTICAL_LIST для страниц записей и автономных страниц, а GRID — для панелей мониторинга. Во вкладке VERTICAL_LIST виджеты располагаются вертикально. Встроенные виджеты, которые управляют собственной прокруткой, например временные шкалы, файлы, заметки, задачи, рабочие процессы и беседы, по умолчанию занимают одну область просмотра; поля, фронтенд-компоненты, графики и другие виджеты с подгонкой по содержимому отображаются с высотой, соответствующей их содержимому или заданным настройкам. Во вкладке GRID виджеты всегда размещаются в виде карточек в 12-колоночной сетке.
• Виджеты на вкладке VERTICAL_LIST наследуют режим макета вкладки, а их порядок задается массивом widgets. Не задавайте position; установите необязательное heightBehavior верхнего уровня в 'TAB_VIEWPORT', если виджет должен занимать одну полную область просмотра вкладки и управлять собственной прокруткой, или в 'FIT_CONTENT', чтобы переопределить встроенное значение по умолчанию для полной высоты. Предшествующие виджеты не уменьшают эту высоту. На вкладку допускается только один активный виджет TAB_VIEWPORT, и он должен располагаться после виджетов с подгонкой по содержимому.
• Виджеты GRID продолжают использовать position: { layoutMode: PageLayoutTabLayoutMode.GRID, row, column, rowSpan, columnSpan }. heightBehavior верхнего уровня допустим только для вкладок VERTICAL_LIST; его использование с GRID или CANVAS является ошибкой валидации.
• Существующие вкладки Canvas и явные позиции виджетов по-прежнему поддерживаются. SDK отображает предупреждения об устаревании с рекомендуемыми заменами.
• Явно задайте layoutMode. Если его не указывать, вы получите VERTICAL_LIST на STANDALONE_PAGE и GRID в остальных случаях, что редко бывает нужно на странице записи.
• Каждый widget внутри вкладки может отображать front component, список связей или другие встроенные типы виджетов.
• Виджет FRONT_COMPONENT может задать для headerCommandMenuItemUniversalIdentifiers упорядоченный массив универсальных идентификаторов пунктов меню команд из того же приложения. Эти действия отображаются как кнопки со значками в заголовке карточки виджета и сохраняют свои проверки доступности и разрешений на уровне команд. Идентификаторы должны быть уникальными и должны разрешаться при установке приложения.
• position у вкладок управляет их порядком. Используйте большие значения (например, 50), чтобы разместить пользовательские вкладки после встроенных.
• twenty app pull записывает макеты страниц обратно вместе с их вкладками и виджетами в строке. О виджете, который экспорт пока не может включить, например о виджете, отображающем собственный front component вашего приложения, или виджете устаревшего типа VIEW, сообщает pull вместо его записи; см. что pull не записывает.

​

Виджеты полей

{
  universalIdentifier: 'c1c2c3c4-c5c6-4000-8000-000000000003',
  title: 'People → Opportunities',
  type: 'FIELD',
  configuration: {
    configurationType: 'FIELD',
    fieldMetadataId: PEOPLE_FIELD_UNIVERSAL_IDENTIFIER,
    fieldDisplayMode: 'TABLE',
    nestedRelationFieldMetadataId: OPPORTUNITIES_FIELD_UNIVERSAL_IDENTIFIER,
  },
}

• fieldMetadataId принимает универсальный идентификатор поля в объекте макета.
• fieldDisplayMode может иметь одно из следующих значений: 'FIELD', 'CARD', 'EDITOR', 'VIEW' или 'TABLE'. TABLE встраивает представление, отображающее записи поля связи «один‑ко‑многим».
• isUIEditable применяется к полям связи в режиме отображения TABLE. По умолчанию задано значение true; установите значение false, чтобы запретить редактирование записей из встроенной таблицы или канбана.
• nestedRelationFieldMetadataId является необязательным и принимает универсальный идентификатор поля связи «один‑ко‑многим» на целевом объекте связи, чтобы перечислять записи на два перехода связи дальше (например, страница Company, перечисляющая сделки людей этой компании, или страница Person, перечисляющая сделки компании этого человека). Первый переход может быть полем связи «один‑ко‑многим» или «многие‑к‑одному», второй обязан быть «один‑ко‑многим» (соединительные связи не поддерживаются), и это требует fieldDisplayMode: 'TABLE' — комбинирование его с любым другим режимом отображения является ошибкой валидации, поскольку вложенный виджет всегда отображается как встраиваемое представление.

​

Виджеты таблицы записей

{
  universalIdentifier: 'd1d2d3d4-d5d6-4000-8000-000000000004',
  title: 'Open opportunities',
  type: 'RECORD_TABLE',
  configuration: {
    configurationType: 'RECORD_TABLE',
    viewUniversalIdentifier: OPPORTUNITIES_VIEW_UNIVERSAL_IDENTIFIER,
    recordLimit: 8,
    isUIEditable: false,
  },
}

• viewUniversalIdentifier определяет представление для отображения.
• recordLimit является необязательным и ограничивает количество записей, отображаемых виджетом.
• isUIEditable применяется к представлениям таблицы и канбана. Он позволяет редактировать ячейки таблицы или редактировать, перемещать и создавать карточки канбана. По умолчанию задано значение true для макетов RECORD_PAGE и false для других макетов.
• isUIEditable управляет только действиями интерфейса. Разрешения для записей по-прежнему применяются, а настройки представления можно редактировать только в редакторе макета страницы.

​

definePageLayoutTab

import {
  definePageLayoutTab,
  PageLayoutTabLayoutMode,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutTab({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
  pageLayoutUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage
      .universalIdentifier,
  title: 'Hello World',
  position: 1000,
  icon: 'IconWorld',
  layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
  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 является обязательным и должен указывать на макет страницы, который уже существует на момент установки — либо стандартный макет Twenty, либо определённый вашим собственным приложением. Кросс-приложенческие ссылки на макеты, которыми владеет другое установленное приложение, на данный момент не поддерживаются. Если родительский макет отсутствует, установка завершается с понятной ошибкой проверки.
• Для стандартных макетов Twenty импортируйте идентификаторы из twenty-sdk/define:
  import { STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
  
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.personRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.opportunityRecordPage.universalIdentifier
  // STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.noteRecordPage.universalIdentifier
  // …
  
  Каждый элемент макета также предоставляет свои tabs и их widgets, поэтому вы можете ссылаться на любой уровень:
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home
    .universalIdentifier;
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.taskRecordPage.tabs.home.widgets
    .fields.universalIdentifier;
  
  Также доступен короткий псевдоним STANDARD_PAGE_LAYOUT:
  import { STANDARD_PAGE_LAYOUT } from 'twenty-sdk/define';
  
  STANDARD_PAGE_LAYOUT.companyRecordPage.universalIdentifier;
  
• widgets ограничены только этой вкладкой — они ссылаются на front components, представления и т. п. точно так же, как виджеты, определённые непосредственно в definePageLayout.
• position управляет порядком относительно существующих вкладок в целевом макете. Выберите значение, которое поместит вашу вкладку в нужное место относительно встроенных вкладок.
• Используйте это вместо definePageLayout, когда вы хотите только добавить к существующему макету. Используйте definePageLayout, когда вы управляете всем макетом.
• twenty app pull записывает добавленную вами вкладку в макет страницы, который вам не принадлежит, обратно в виде файла definePageLayoutTab() с её виджетами в строке и с теми же ограничениями, что и для виджетов definePageLayout().

​

definePageLayoutWidget

import {
  definePageLayoutWidget,
  PageLayoutTabLayoutMode,
  PageLayoutWidgetVerticalListHeightBehavior,
  STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';

export default definePageLayoutWidget({
  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000003',
  pageLayoutTabUniversalIdentifier:
    STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.companyRecordPage.tabs.home
      .universalIdentifier,
  title: 'Hello World',
  type: 'FRONT_COMPONENT',
  position: {
    layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
    index: 1000,
    heightBehavior: PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT,
  },
  configuration: {
    configurationType: 'FRONT_COMPONENT',
    frontComponentUniversalIdentifier:
      HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
  },
});

​

Основные моменты

• pageLayoutTabUniversalIdentifier является обязательным и должен указывать на вкладку, которая уже существует на момент установки: стандартную вкладку Twenty (STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS.\<object>RecordPage.tabs.\<tab>.universalIdentifier), вкладку одного из ваших собственных макетов или вкладку страницы записи, которую Twenty создаёт для одного из ваших объектов. Созданные вкладки имеют детерминированные идентификаторы, поэтому вы можете вычислить их:
  import {
    getSystemPageLayoutTabUniversalIdentifier,
    getSystemRecordPageLayoutUniversalIdentifier,
  } from 'twenty-sdk/define';
  
  const EXAMPLE_HOME_TAB_UNIVERSAL_IDENTIFIER =
    getSystemPageLayoutTabUniversalIdentifier({
      objectMetadataApplicationUniversalIdentifier:
        APPLICATION_UNIVERSAL_IDENTIFIER,
      pageLayoutUniversalIdentifier:
        getSystemRecordPageLayoutUniversalIdentifier({
          objectMetadataApplicationUniversalIdentifier:
            APPLICATION_UNIVERSAL_IDENTIFIER,
          objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
        }),
      title: 'Home',
    });
  
• position является обязательным, поскольку вкладка не является частью вашего манифеста и её режим макета невозможно определить автоматически. Выберите режим макета, соответствующий вкладке: вкладки страниц записей представляют собой вертикальные списки, поэтому используйте { layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST, index } с индексом выше встроенных виджетов (виджет Fields находится на позиции 0).
• Для вертикального списка задайте position.heightBehavior как PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT, чтобы заполнить область просмотра одной вкладки, или как PageLayoutWidgetVerticalListHeightBehavior.FIT_CONTENT, чтобы использовать содержимое виджета или настроенную высоту. Импортируйте это перечисление из twenty-sdk/define, как в примере выше. Если значение не указано, виджет сохраняет встроенное значение по умолчанию. Только один активный виджет на вкладку может заполнять область просмотра, и его индекс должен располагать его после всех виджетов с высотой по содержимому. heightBehavior не поддерживается в позициях GRID или CANVAS.
• configuration работает точно так же, как виджет, определённый встроенно в definePageLayout или definePageLayoutTab: он ссылается на фронтенд-компоненты, представления, поля и т. д.
• Используйте это вместо definePageLayoutTab, когда вкладка уже существует и вы хотите разместить на ней только один виджет. Используйте definePageLayoutTab, когда вам нужна собственная вкладка.
• twenty app pull записывает добавленный вами виджет во вкладку, которая вам не принадлежит, обратно в виде файла definePageLayoutWidget() с теми же ограничениями, что и для виджетов definePageLayout().