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

Поля конфигурации
Размещение фронт-компонента на странице
Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в макет страницы. См. макеты страниц для подробностей.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— например,ViewRecordпринимаетrecordId+objectNameSingular, другие страницы принимаютpageTitle+pageIcon.
Command для запуска действия из меню команд:
src/front-components/run-action.tsx
src/command-menu-items/run-action.command-menu-item.ts
CommandModal для запроса подтверждения перед выполнением:
src/front-components/delete-draft.tsx
Вызов логической функции
Front-компоненты выполняются в браузере в изолированном Web Worker, в то время как логические функции выполняются на стороне сервера. Между ними нет прямого внутрипроцессного вызова — вместо этого front-компонент обращается к логической функции по HTTP. Логическая функция, объявленная сhttpRouteTriggerSettings, доступна по HTTP по своему пути маршрута. Twenty внедряет в воркер базовый URL, с которого обслуживаются ваши функции, в виде TWENTY_FUNCTIONS_URL вместе с TWENTY_APP_ACCESS_TOKEN, который аутентифицирует вызов. Пока что нет отдельного клиентского SDK для вызова ваших собственных функций, поэтому вызывайте их с помощью обычного fetch:
В Twenty Cloud логические функции с HTTP-триггером обслуживаются на выделенном домене для каждого рабочего пространства по адресуБезголовый front-компонент может выполнить вызов при монтировании через компонентhttps://\<your-workspace-subdomain>.twenty.com\<path>— именно к этому и разрешаетсяTWENTY_FUNCTIONS_URL. Для внешних вызовов скопируйте точный URL из настроек HTTP trigger функции или на вкладке Settings приложения.
Command, а затем автоматически размонтироваться:
src/front-components/sync-prs.tsx
TWENTY_FUNCTIONS_URL, — это значение httpRouteTriggerSettings.path логической функции. Сохраните isAuthRequired: true; TWENTY_APP_ACCESS_TOKEN, который Twenty выпускает для вашего компонента, аутентифицирует запрос:
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_FUNCTIONS_URL и TWENTY_APP_ACCESS_TOKEN внедряются автоматически — см. переменные приложения. Поскольку секретные переменные приложения никогда не раскрываются front-компонентам, храните ключи API и другую конфиденциальную логику в логической функции, а не во front-компоненте.Вызов REST API Twenty
Чтобы читать или изменять записи Twenty из фронт-компонента, используйтеRestApiClient из twenty-client-sdk/rest. Он принадлежит к тому же семейству клиентов, что и CoreApiClient и MetadataApiClient, но нацелен на REST API Twenty (/rest/...) вместо GraphQL API, считывая базовый URL из TWENTY_API_URL.
В
options принимаются headers, query (объект с параметрами строки запроса; значения, равные null или undefined, пропускаются) и AbortSignal через signal. Объект body, не являющийся FormData, автоматически сериализуется в JSON. При получении 401 клиент один раз обновляет токен доступа через хост и повторяет запрос.
Базовый URL и токен по умолчанию берутся из окружения. При необходимости передавайте переопределения в конструктор — например, в тестах:
RestApiClientError, который содержит status, statusText, url и распарсенное body:
Доступ к контексту времени выполнения
Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:src/front-components/record-info.tsx
Переменные приложения
Переменные приложения, определенные вdefineApplication() с isSecret: false, доступны внутри фронтенд-компонентов через утилиту getApplicationVariable:
src/front-components/greeting.tsx
process.env:
API взаимодействия с хостом
Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций изtwenty-sdk:
Пример, который использует API хоста для показа snackbar и закрытия боковой панели после завершения действия:
src/front-components/archive-record.tsx
Работа с несколькими записями
ИспользуйтеuseSelectedRecordIds() для обработки нескольких выбранных записей. Это полезно для массовых операций:
src/front-components/bulk-export.tsx
Публичные ресурсы
Компоненты фронтенда могут получать доступ к файлам из каталога приложенияpublic/ с помощью getPublicAssetUrl:
Стилизация
Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:- Встроенные стили —
style={{ color: 'red' }} - Twenty UI components — собственная библиотека компонентов Twenty; см. раздел Using Twenty UI components ниже
- Emotion — CSS-in-JS с
@emotion/react - Styled-components — паттерны
styled.div - Tailwind CSS — утилитарные классы
- Любая библиотека CSS-in-JS, совместимая с React
Использование компонентов Twenty UI
Twenty поставляет свою библиотеку компонентов как пакетtwenty-ui. Компоненты фронтенда могут использовать его для кнопок, тегов, статусных плашек, чипов, аватаров, иконок, типографики и токенов темы, которые автоматически соответствуют светлой и тёмной теме рабочего пространства.
Установка
Добавьте пакет в своё приложение, зафиксировав его на версии, с которой поставляется ваш экземпляр Twenty:twenty-ui включается в ваш компонент фронтенда на этапе сборки, поэтому его достаточно иметь в зависимостях вашего приложения — во время выполнения ничего настраивать не нужно.
Импорт компонентов
Импортируйте из соответствующего подпути, а не из корня пакета, чтобы в ваш бандл попали только те компоненты, которые вы используете:Иконки
Импортируйте отдельные иконки изtwenty-ui/icon:
IconsProvider, useIcons и iconsState — они подключают весь набор иконок Tabler (несколько мегабайт).
Темизация и токены темы
Компоненты Twenty UI автоматически подстраиваются под светлую и тёмную темы рабочего пространства — рендерер применяет активную цветовую схему на хосте, а компоненты вычисляют свои цвета относительно неё. Чтобы использовать те же дизайн‑токены в собственных встроенных стилях, вызовите хукuseTheme(). Он возвращает токены темы Twenty (отступы, цвета, радиусы, шрифты), привязанные к активной теме, без необходимости настраивать ThemeProvider в вашем компоненте:
useTheme() — это хук, вы читаете токены внутри тела компонента, поэтому значения всегда соответствуют активной теме. Та же карта токенов также экспортируется как константа themeCssVariables, но в компонентах фронтенда предпочтительнее использовать useTheme() — модульная константа, разыменующая themeCssVariables, может быть undefined, пока извлекается манифест приложения.
Чтобы явно разветвлять логику по активной цветовой схеме, считайте её с помощью useColorScheme() из twenty-sdk/front-component, который возвращает 'light' или 'dark'.