Где можно использовать фронт-компоненты
Фронт-компоненты могут отображаться в двух местах внутри Twenty:- Боковая панель — фронт-компоненты с интерфейсом открываются в правой боковой панели. Это поведение по умолчанию, когда фронт-компонент запускается из меню команд.
- Виджеты (дашборды и страницы записей) — фронт-компоненты можно встраивать как виджеты в макеты страниц. При настройке дашборда или макета страницы записи пользователи могут добавить виджет фронт-компонента.
Простой пример
Самый быстрый способ увидеть фронтенд-компонент в действии — зарегистрировать его как команду. Добавление поляcommand с isPinned: true делает его кнопкой быстрого действия в правом верхнем углу страницы — макет страницы не требуется:
src/front-components/hello-world.tsx
yarn twenty dev (или однократного запуска yarn twenty dev --once) быстрое действие появится в правом верхнем углу страницы:

Поля конфигурации
| Поле | Обязательно | Описание |
|---|---|---|
universalIdentifier | Да | Стабильный уникальный идентификатор для этого компонента |
component | Да | Функция компонента React |
name | Нет | Отображаемое имя |
description | Нет | Описание того, что делает компонент |
isHeadless | Нет | Установите значение true, если у компонента нет видимого пользовательского интерфейса (см. ниже) |
command | Нет | Зарегистрируйте компонент как команду (см. параметры команды ниже) |
Размещение фронт-компонента на странице
Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в макет страницы. См. раздел definePageLayout для подробностей.Headless и non-headless
Фронт-компоненты поддерживают два режима отображения, управляемых опциейisHeadless:
Non-headless (по умолчанию) — компонент отображает видимый интерфейс. При запуске из меню команд он открывается в боковой панели. Это поведение по умолчанию, когда isHeadless имеет значение false или опущен.
Headless (isHeadless: true) — компонент монтируется невидимо в фоновом режиме. Он не открывает боковую панель. Компоненты headless предназначены для действий, которые выполняют логику и затем размонтируются — например, запуск асинхронной задачи, переход на страницу или показ модального окна подтверждения. Они естественно сочетаются с компонентами SDK Command, описанными ниже.
src/front-components/sync-tracker.tsx
null, Twenty пропускает рендеринг контейнера для него — в макете не появляется пустое место. Компонент по-прежнему имеет доступ ко всем хукам и API взаимодействия с хостом.
Компоненты SDK Command
Пакетtwenty-sdk предоставляет четыре вспомогательных компонента Command, предназначенных для headless фронт-компонентов. Каждый компонент выполняет действие при монтировании, обрабатывает ошибки, показывая уведомление snackbar, и автоматически размонтирует фронт-компонент по завершении.
Импортируйте их из twenty-sdk/command:
Command— запускает асинхронный колбэк через пропexecute.CommandLink— переходит по пути внутри приложения. Пропы:to,params,queryParams,options.CommandModal— открывает модальное окно подтверждения. Если пользователь подтвердит, выполняет колбэкexecute. Пропы:title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— открывает конкретную страницу боковой панели. Пропы:page,pageTitle,pageIcon.
Command для запуска действия из меню команд:
src/front-components/run-action.tsx
CommandModal для запроса подтверждения перед выполнением:
src/front-components/delete-draft.tsx
Доступ к контексту времени выполнения
Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:src/front-components/record-info.tsx
| Хук | Возвращает | Описание |
|---|---|---|
useUserId() | string или null | ID текущего пользователя |
useRecordId() | string или null | ID текущей записи (при размещении на странице записи) |
useFrontComponentId() | string | ID этого экземпляра компонента |
useFrontComponentExecutionContext(selector) | различается | Доступ к полному контексту выполнения с помощью функции-селектора |
API взаимодействия с хостом
Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций изtwenty-sdk:
| Функция | Описание |
|---|---|
navigate(to, params?, queryParams?, options?) | Перейти на страницу в приложении |
openSidePanelPage(params) | Открыть боковую панель |
closeSidePanel() | Закрыть боковую панель |
openCommandConfirmationModal(params) | Показать диалог подтверждения |
enqueueSnackbar(params) | Показать всплывающее уведомление |
unmountFrontComponent() | Размонтировать компонент |
updateProgress(progress) | Обновить индикатор прогресса |
src/front-components/archive-record.tsx
Параметры команды
Добавление поляcommand в defineFrontComponent регистрирует компонент в меню команд (Cmd+K). Если isPinned имеет значение true, команда также отображается как кнопка быстрого действия в правом верхнем углу страницы.
| Поле | Обязательно | Описание |
|---|---|---|
universalIdentifier | Да | Стабильный уникальный идентификатор для команды |
label | Да | Полная метка, отображаемая в меню команд (Cmd+K) |
shortLabel | Нет | Короткая метка, отображаемая на закреплённой кнопке быстрого действия |
icon | Нет | Имя значка, отображаемое рядом с меткой (например, 'IconBolt', 'IconSend') |
isPinned | Нет | При значении true показывает команду как кнопку быстрого действия в правом верхнем углу страницы |
availabilityType | Нет | Определяет, где отображается команда: 'GLOBAL' (доступна всегда), 'RECORD_SELECTION' (только при выборе записей) или 'FALLBACK' (показывается, когда другие команды не подходят) |
availabilityObjectUniversalIdentifier | Нет | Ограничивает команду страницами определённого типа объектов (например, только для записей Company) |
conditionalAvailabilityExpression | Нет | Логическое выражение для динамического управления видимостью команды (см. ниже) |
Выражения условной доступности
ПолеconditionalAvailabilityExpression позволяет управлять видимостью команды в зависимости от текущего контекста страницы. Импортируйте типизированные переменные и операторы из twenty-sdk, чтобы составлять выражения:
| Переменная | Тип | Описание |
|---|---|---|
pageType | string | Текущий тип страницы (например, 'RecordIndexPage', 'RecordShowPage') |
isInSidePanel | boolean | Указывает, рендерится ли компонент в боковой панели |
numberOfSelectedRecords | number | Количество выбранных в данный момент записей |
isSelectAll | boolean | Активен ли режим “выбрать все” |
selectedRecords | массив | Объекты выбранных записей |
favoriteRecordIds | массив | ID избранных записей |
objectPermissions | object | Разрешения для текущего типа объекта |
targetObjectReadPermissions | object | Права на чтение для целевого объекта |
targetObjectWritePermissions | object | Права на запись для целевого объекта |
featureFlags | object | Активные флаги функций |
objectMetadataItem | object | Метаданные текущего типа объекта |
hasAnySoftDeleteFilterOnView | boolean | Есть ли у текущего представления фильтр мягкого удаления |
| Оператор | Описание |
|---|---|
isDefined(value) | true, если значение не null/undefined |
isNonEmptyString(value) | true, если значение — непустая строка |
includes(array, value) | true, если массив содержит значение |
includesEvery(array, prop, value) | true, если свойство каждого элемента включает значение |
every(array, prop) | true, если свойство истинно для каждого элемента |
everyDefined(array, prop) | true, если свойство определено у каждого элемента |
everyEquals(array, prop, value) | true, если свойство равно значению у каждого элемента |
some(array, prop) | true, если свойство истинно хотя бы у одного элемента |
someDefined(array, prop) | true, если свойство определено хотя бы у одного элемента |
someEquals(array, prop, value) | true, если свойство равно значению хотя бы у одного элемента |
someNonEmptyString(array, prop) | true, если свойство является непустой строкой хотя бы у одного элемента |
none(array, prop) | true, если свойство ложно для каждого элемента |
noneDefined(array, prop) | true, если свойство не определено ни у одного элемента |
noneEquals(array, prop, value) | true, если свойство не равно значению ни у одного элемента |
Публичные ресурсы
Компоненты фронтенда могут получать доступ к файлам из каталога приложенияpublic/ с помощью getPublicAssetUrl:
Стилизация
Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:- Встроенные стили —
style={{ color: 'red' }} - Компоненты Twenty UI — импорт из
twenty-sdk/ui(Button, Tag, Status, Chip, Avatar и другие) - Emotion — CSS-in-JS с
@emotion/react - Styled-components — паттерны
styled.div - Tailwind CSS — утилитарные классы
- Любая библиотека CSS-in-JS, совместимая с React