Где можно использовать фронт-компоненты
Фронт-компоненты могут отображаться в двух местах внутри 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) быстрое действие появится в правом верхнем углу страницы:

Поля конфигурации
| Поле | Обязательно | Описание |
|---|---|---|
universalIdentifier | Да | Стабильный уникальный идентификатор для этого компонента |
component | Да | Функция компонента React |
name | Нет | Отображаемое имя |
description | Нет | Описание того, что делает компонент |
isHeadless | Нет | Установите значение true, если у компонента нет видимого пользовательского интерфейса (см. ниже) |
Размещение фронт-компонента на странице
Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в макет страницы. См. макеты страниц для подробностей.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
src/command-menu-items/run-action.command-menu-item.ts
CommandModal для запроса подтверждения перед выполнением:
src/front-components/delete-draft.tsx
Вызов логической функции
Front-компоненты выполняются в браузере в изолированном Web Worker, в то время как логические функции выполняются на стороне сервера. Между ними нет прямого внутрипроцессного вызова — вместо этого front-компонент обращается к логической функции по HTTP. Логическая функция, объявленная сhttpRouteTriggerSettings, доступна по эндпоинту /s/ по адресу ${TWENTY_API_URL}/s\<path>. Ваш front-компонент вызывает этот маршрут с помощью RestApiClient из twenty-client-sdk/rest, который аутентифицируется с использованием TWENTY_APP_ACCESS_TOKEN, который Twenty внедряет в worker.
RestApiClient создан именно для этого. Он считывает TWENTY_API_URL и TWENTY_APP_ACCESS_TOKEN из окружения worker, добавляет заголовок Authorization: Bearer, сериализует и парсит JSON и выбрасывает RestApiClientError, когда токен или URL отсутствуют или ответ не является 2xx — чтобы вам не приходилось реализовывать этот шаблонный код в каждом компоненте.
Безголовый front-компонент может выполнить вызов при монтировании через компонент Command, а затем автоматически размонтироваться:
src/front-components/sync-prs.tsx
httpRouteTriggerSettings.path для логической функции с префиксом /s. Сохраните isAuthRequired: true; клиент передает токен доступа к приложению, который Twenty выпускает для вашего компонента:
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_API_URL и TWENTY_APP_ACCESS_TOKEN внедряются автоматически — см. переменные приложения. Поскольку секретные переменные приложения никогда не раскрываются front-компонентам, храните ключи API и другую конфиденциальную логику в логической функции, а не во front-компоненте.Справочник по RestApiClient
ИмпортируйтеRestApiClient из twenty-client-sdk/rest. Он принадлежит к тому же семейству клиентов, что и CoreApiClient и MetadataApiClient, но предназначен для HTTP-маршрутов вашего приложения вместо GraphQL API.
| Метод | Описание |
|---|---|
get(path, options?) | Отправляет запрос GET |
post(path, body?, options?) | Отправляет запрос POST |
put(path, body?, options?) | Отправляет запрос PUT |
patch(path, body?, options?) | Отправляет запрос PATCH |
delete(path, options?) | Отправляет запрос DELETE |
request(method, path, options?) | Универсальный запрос с любым HTTP-методом |
options принимаются headers, query (объект с параметрами строки запроса; значения, равные null или undefined, пропускаются) и AbortSignal через signal. Объект body, не являющийся FormData, автоматически сериализуется в JSON. При получении 401 клиент один раз обновляет токен доступа через хост и повторяет запрос.
Базовый URL и токен по умолчанию берутся из окружения. При необходимости передавайте переопределения в конструктор — например, в тестах:
RestApiClientError, который содержит status, statusText, url и распарсенное body:
Доступ к контексту времени выполнения
Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:src/front-components/record-info.tsx
| Хук | Возвращает | Описание |
|---|---|---|
useUserId() | string или null | ID текущего пользователя |
useSelectedRecordIds() | string[] | Все выбранные идентификаторы записей (пустой массив, если ничего не выбрано) |
useRecordId() | string или null | Устарело. Используйте useSelectedRecordIds() вместо этого |
useFrontComponentId() | string | ID этого экземпляра компонента |
useColorScheme() | 'light' или 'dark' | Активная цветовая схема интерфейса хоста (значение System уже определено) |
useFrontComponentExecutionContext(selector) | различается | Доступ к полному контексту выполнения с помощью функции-селектора |
Переменные приложения
Переменные приложения, определенные вdefineApplication() с isSecret: false, доступны внутри фронтенд-компонентов через утилиту getApplicationVariable:
src/front-components/greeting.tsx
process.env:
| Переменная | Описание |
|---|---|
TWENTY_API_URL | Базовый URL API Twenty |
TWENTY_APP_ACCESS_TOKEN | Краткоживущий токен с областью действия, ограниченной ролью вашего приложения |
API взаимодействия с хостом
Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций изtwenty-sdk:
| Функция | Описание |
|---|---|
navigate(to, params?, queryParams?, options?) | Перейти на страницу в приложении |
openSidePanelPage(params) | Открыть боковую панель |
closeSidePanel() | Закрыть боковую панель |
openCommandConfirmationModal(params) | Показать диалог подтверждения |
enqueueSnackbar(params) | Показать всплывающее уведомление |
unmountFrontComponent() | Размонтировать компонент |
updateProgress(progress) | Обновить индикатор прогресса |
src/front-components/archive-record.tsx
Работа с несколькими записями
ИспользуйтеuseSelectedRecordIds() для обработки нескольких выбранных записей. Это полезно для массовых операций:
src/front-components/bulk-export.tsx
Публичные ресурсы
Компоненты фронтенда могут получать доступ к файлам из каталога приложения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