snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx

@@ -0,0 +1,849 @@
+---
+title: Компоненты фронтенда
+description: Создавайте компоненты React, которые отображаются внутри интерфейса Twenty в изолированной песочнице.
+icon: window-maximize
+---
+
+Фронтенд-компоненты — это компоненты React, которые отображаются непосредственно внутри интерфейса Twenty. Они выполняются в **изолированном Web Worker** с использованием Remote DOM — ваш код исполняется внутри изолированного iframe с непрозрачным источником (opaque-origin), но его UI всё равно нативно рендерится на странице, а не ограничивается этим iframe.
+
+<Warning>
+Конструкции передней части все еще активно развиваются. Ваш код запускается с частичным DOM, а не с реальной страницей браузера, так что использование расширенного кода может привести к ошибке, часто молчанию. См. [Текущие ограничения](#current-limitations).
+</Warning>
+
+## Где можно использовать фронт-компоненты
+
+Фронт-компоненты могут отображаться в трёх местах внутри Twenty:
+
+* **Боковая панель** — фронт-компоненты с интерфейсом открываются в правой боковой панели. Это поведение по умолчанию, когда фронт-компонент запускается из меню команд.
+* **Виджеты (дашборды и страницы записей)** — фронт-компоненты можно встраивать как виджеты в [макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts). При настройке дашборда или макета страницы записи пользователи могут добавить виджет фронт-компонента.
+* **Настройки приложения (App settings)** — если определить фронт-компонент с помощью [`defineSettingsFrontComponent()`](#custom-settings-component), он будет отображаться как раздел на вкладке **Settings** приложения, заменяя стандартный интерфейс настройки переменных.
+
+Сам по себе фронт-компонент недоступен из интерфейса — его нужно *сделать доступным*. Сделать это можно тремя способами:
+
+* **Связать его с [элементом командного меню](/l/ru/developers/extend/apps/layout/command-menu-items)** — регистрирует его в командном меню (Cmd+K) и, при необходимости, как закреплённое быстрое действие.
+* **Встроить его как виджет в [макет страницы](/l/ru/developers/extend/apps/layout/page-layouts)** — размещает его на странице деталей записи или на дашборде.
+* **Определить его с помощью [`defineSettingsFrontComponent()`](#custom-settings-component)** — отображает его как раздел на вкладке **Settings** приложения, заменяя стандартный интерфейс настройки переменных.
+
+## Простой пример
+
+Самый быстрый способ увидеть фронт-компонент в действии — связать его с [`defineCommandMenuItem`](/l/ru/developers/extend/apps/layout/command-menu-items), чтобы он появился как кнопка быстрого действия в правом верхнем углу страницы:
+
+```tsx src/front-components/hello-world.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const HelloWorld = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>Hello from my app!</h1>
+      <p>This component renders inside Twenty.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+  name: 'hello-world',
+  description: 'A simple front component',
+  component: HelloWorld,
+});
+```
+
+```ts src/command-menu-items/hello-world.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+  shortLabel: 'Hello',
+  label: 'Hello World',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+});
+```
+
+После синхронизации с помощью `yarn twenty dev` (или однократного запуска `yarn twenty apply`) быстрое действие появится в правом верхнем углу страницы:
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/quick-action.png" alt="Кнопка быстрого действия в правом верхнем углу" />
+</div>
+
+Нажмите её, чтобы отобразить компонент инлайн.
+
+## Поля конфигурации
+
+| Поле                  | Обязательно | Описание                                                                                           |
+| --------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `universalIdentifier` | Да          | Стабильный уникальный идентификатор для этого компонента                                           |
+| `component`           | Да          | Функция компонента React                                                                           |
+| `name`                | Нет         | Отображаемое имя                                                                                   |
+| `description`         | Нет         | Описание того, что делает компонент                                                                |
+| `isHeadless`          | Нет         | Установите значение `true`, если у компонента нет видимого пользовательского интерфейса (см. ниже) |
+
+## Размещение фронт-компонента на странице
+
+Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в **макет страницы**. См. [макеты страниц](/l/ru/developers/extend/apps/layout/page-layouts) для подробностей.
+
+## Пользовательский компонент настроек
+
+Чтобы заменить автоматически сгенерированный интерфейс настройки переменных на вкладке **Settings** вашего приложения собственным компонентом, определите его с помощью `defineSettingsFrontComponent` вместо `defineFrontComponent`. Он использует те же [поля конфигурации](#configuration-fields) (за исключением `isHeadless`, которое не принимается, поскольку компонент настроек всегда отрисовывает видимый интерфейс пользователя) и дополнительно помечает компонент как интерфейс настроек приложения.
+
+Компонент отрисовывается как раздел **внутри** вкладки Settings, а не как замена всей вкладки. Управляемые системой Twenty разделы — автообновление, App URL и подключения — всегда отрисовываются над ним и не могут быть переопределены приложением.
+
+```tsx src/front-components/app-settings.tsx
+import { defineSettingsFrontComponent } from 'twenty-sdk/define';
+
+const AppSettings = () => {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h2>My app settings</h2>
+      {/* render your own configuration UI here */}
+    </div>
+  );
+};
+
+export default defineSettingsFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'app-settings',
+  description: "Custom UI for the app's Settings tab",
+  component: AppSettings,
+});
+```
+
+Для каждого приложения допускается только один фронт-компонент настроек; объявление более одного приведет к ошибке сборки. Если он присутствует, вкладка **Settings** приложения отрисовывает этот компонент вместо стандартного интерфейса конфигурации переменных.
+
+## Headless и non-headless
+
+Фронт-компоненты поддерживают два режима отображения, управляемых опцией `isHeadless`:
+
+**Non-headless (по умолчанию)** — компонент отображает видимый интерфейс. При запуске из меню команд он открывается в боковой панели. Это поведение по умолчанию, когда `isHeadless` имеет значение `false` или опущен.
+
+**Headless (`isHeadless: true`)** — компонент монтируется невидимо в фоновом режиме. Он не открывает боковую панель. Компоненты headless предназначены для действий, которые выполняют логику и затем размонтируются — например, запуск асинхронной задачи, переход на страницу или показ модального окна подтверждения. Они естественно сочетаются с компонентами SDK Command, описанными ниже.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, enqueueSnackbar } from 'twenty-sdk/front-component';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+  const [recordId] = useSelectedRecordIds();
+
+  useEffect(() => {
+    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+  }, [recordId]);
+
+  return null;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'sync-tracker',
+  description: 'Tracks record views silently',
+  isHeadless: true,
+  component: SyncTracker,
+});
+```
+
+Поскольку компонент возвращает `null`, Twenty пропускает рендеринг контейнера для него — в макете не появляется пустое место. Компонент по-прежнему имеет доступ ко всем хукам и API взаимодействия с хостом.
+
+## Компоненты SDK Command
+
+Пакет `twenty-sdk` предоставляет четыре вспомогательных компонента Command, предназначенных для headless фронт-компонентов. Каждый компонент выполняет действие при монтировании, обрабатывает ошибки, показывая уведомление snackbar, и автоматически размонтирует фронт-компонент по завершении.
+
+Импортируйте их из `twenty-sdk/front-component`:
+
+* **`Command`** — запускает асинхронный колбэк через проп `execute`.
+* **`CommandLink`** — переходит по пути внутри приложения. Пропы: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — открывает модальное окно подтверждения. Если пользователь подтвердит, выполняет колбэк `execute`. Пропы: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — открывает страницу боковой панели. Пропсы зависят от `page` — например, `ViewRecord` принимает `recordId` + `objectNameSingular` (а также необязательный id `tab`, чтобы открыть запись на определённой вкладке), другие страницы принимают `pageTitle` + `pageIcon`.
+
+Полный пример headless фронт-компонента, использующего `Command` для запуска действия из меню команд:
+
+```tsx src/front-components/run-action.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Command } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const RunAction = () => {
+  const execute = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      createTask: {
+        __args: { data: { title: 'Created by my app' } },
+        id: true,
+      },
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+  name: 'run-action',
+  description: 'Creates a task from the command menu',
+  component: RunAction,
+  isHeadless: true,
+});
+```
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+});
+```
+
+А также пример с использованием `CommandModal` для запроса подтверждения перед выполнением:
+
+```tsx src/front-components/delete-draft.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { CommandModal } from 'twenty-sdk/front-component';
+
+const DeleteDraft = () => {
+  const execute = async () => {
+    // perform the deletion
+  };
+
+  return (
+    <CommandModal
+      title="Delete draft?"
+      subtitle="This action cannot be undone."
+      execute={execute}
+      confirmButtonText="Delete"
+      confirmButtonAccent="danger"
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
+  name: 'delete-draft',
+  description: 'Deletes a draft with confirmation',
+  component: DeleteDraft,
+  isHeadless: true,
+});
+```
+
+И пример использования `CommandOpenSidePanelPage` для открытия текущей записи в боковой панели на определённой вкладке. `tab` — это id вкладки в макете страницы (в стандартных макетах используются id вроде `company-tab-emails` или `company-tab-timeline`; в пользовательских макетах используется собственный id вкладки). Если такого id нет в макете записи, откроется вкладка по умолчанию:
+
+```tsx src/front-components/open-company-emails.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import {
+  CommandOpenSidePanelPage,
+  SidePanelPages,
+  useSelectedRecordIds,
+} from 'twenty-sdk/front-component';
+
+const OpenCompanyEmails = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;
+
+  if (!recordId) {
+    return null;
+  }
+
+  return (
+    <CommandOpenSidePanelPage
+      page={SidePanelPages.ViewRecord}
+      recordId={recordId}
+      objectNameSingular="company"
+      tab="company-tab-emails"
+      resetNavigationStack={false}
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
+  name: 'open-company-emails',
+  description: 'Opens the current company on its Emails tab',
+  component: OpenCompanyEmails,
+  isHeadless: true,
+});
+```
+
+## Вызов логической функции
+
+Front-компоненты выполняются в браузере в Web Worker, изолированном внутри iframe с непрозрачным источником (opaque-origin), в то время как [логические функции](/l/ru/developers/extend/apps/logic/logic-functions) выполняются на стороне сервера. Между ними нет прямого внутрипроцессного вызова — вместо этого front-компонент обращается к логической функции по HTTP.
+
+Логическая функция, объявленная с `httpRouteTriggerSettings`, доступна по HTTP по своему пути маршрута. `RestApiClient` рассматривает пути, начинающиеся с `/s/`, как маршруты приложения, разрешает их в URL, по которому обслуживаются ваши функции, и аутентифицирует их с помощью `TWENTY_APP_ACCESS_TOKEN`.
+
+> **В Twenty Cloud логические функции с HTTP-триггером обслуживаются на выделенном домене для каждого рабочего пространства** по адресу `https://\<your-workspace-subdomain>.withtwenty.com\<path>`. Для внешних вызовов скопируйте точный URL из настроек **HTTP trigger** функции или на вкладке **Settings** приложения.
+
+Безголовый front-компонент может выполнить вызов при монтировании через компонент `Command`, а затем автоматически размонтироваться:
+
+```tsx src/front-components/sync-prs.tsx
+import { RestApiClient } from 'twenty-client-sdk/rest';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Command } from 'twenty-sdk/front-component';
+
+const SyncPrs = () => {
+  const execute = async () => {
+    await new RestApiClient().post('/s/github/fetch-prs', {
+      owner: 'twentyhq',
+      repo: 'twenty',
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'sync-prs',
+  description: 'Triggers the fetch-prs logic function',
+  isHeadless: true,
+  component: SyncPrs,
+});
+```
+
+Путь, передаваемый в `RestApiClient`, — это значение `httpRouteTriggerSettings.path` логической функции с префиксом `/s`. Сохраните `isAuthRequired: true`; `TWENTY_APP_ACCESS_TOKEN`, который Twenty выпускает для вашего компонента, аутентифицирует запрос:
+
+```ts src/logic-functions/fetch-prs.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import type { RoutePayload } from 'twenty-sdk/logic-function';
+
+const handler = async (event: RoutePayload) => {
+  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
+  // ...fetch from GitHub and persist records...
+  return { ok: true };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '...',
+  name: 'fetch-prs',
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/github/fetch-prs',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+});
+```
+
+<Note>
+`TWENTY_APP_ACCESS_TOKEN` внедряется автоматически — см. [переменные приложения](#application-variables). Поскольку секретные переменные приложения никогда не раскрываются front-компонентам, храните ключи API и другую конфиденциальную логику в логической функции, а не во front-компоненте.
+</Note>
+
+### Вызов REST API Twenty
+
+Чтобы вызывать HTTP-маршруты приложения или читать и изменять записи Twenty из фронт-компонента, используйте `RestApiClient` из `twenty-client-sdk/rest`. Он отправляет пути вида `/s/...` на базовый URL функций вашего рабочего пространства, а все остальные пути, включая `/rest/...`, — на `TWENTY_API_URL`.
+
+Он всегда действует от имени человека, просматривающего страницу. `runAs: 'application'` — это параметр только для логической функции: компонент никогда не получает собственный токен вашего приложения, поэтому его запрос здесь вызывает ошибку. Поместите работу, требующую собственного доступа приложения, за логическую функцию и вызывайте вместо этого её.
+
+| Метод                             | Описание                                                          |
+| --------------------------------- | ----------------------------------------------------------------- |
+| `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-методом                         |
+| `resolveUrl(path, options?)`      | Разрешает путь в его полный URL без отправки запроса (для ссылок) |
+
+В `options` принимаются `headers`, `query` (объект с параметрами строки запроса; значения, равные null или undefined, пропускаются) и `AbortSignal` через `signal`. Объект `body`, не являющийся `FormData`, автоматически сериализуется в JSON. При получении `401` клиент один раз обновляет токен доступа через хост и повторяет запрос.
+
+Базовый URL и токен по умолчанию берутся из окружения. При необходимости передавайте переопределения в конструктор — например, в тестах:
+
+```ts
+const client = new RestApiClient({
+  baseUrl: 'https://myworkspace.twenty.com',
+  token: 'my-token',
+});
+```
+
+Неудачные запросы выбрасывают `RestApiClientError`, который содержит `status`, `statusText`, `url` и распарсенное `body`:
+
+```tsx
+import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';
+
+const client = new RestApiClient();
+
+try {
+  const people = await client.get('/rest/people', {
+    query: { limit: 10 },
+  });
+} catch (error) {
+  if (error instanceof RestApiClientError) {
+    console.error(error.status, error.body);
+  }
+}
+```
+
+## Доступ к контексту времени выполнения
+
+Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:
+
+```tsx src/front-components/record-info.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import {
+  useUserId,
+  useSelectedRecordIds,
+  useFrontComponentId,
+} from 'twenty-sdk/front-component';
+
+const RecordInfo = () => {
+  const userId = useUserId();
+  const [recordId] = useSelectedRecordIds();
+  const componentId = useFrontComponentId();
+
+  return (
+    <div>
+      <p>User: {userId}</p>
+      <p>Record: {recordId ?? 'No record context'}</p>
+      <p>Component: {componentId}</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+  name: 'record-info',
+  component: RecordInfo,
+});
+```
+
+Доступные хуки:
+
+| Хук                                           | Возвращает             | Описание                                                                                                  |
+| --------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `useUserId()`                                 | `string` или `null`    | ID текущего пользователя                                                                                  |
+| `useSelectedRecordIds()`                      | `string[]`             | Все выбранные идентификаторы записей (пустой массив, если ничего не выбрано)                              |
+| `useRecordId()`                               | `string` или `null`    | **Устарело.** Используйте `useSelectedRecordIds()` вместо этого                                           |
+| `useFrontComponentId()`                       | `string`               | ID этого экземпляра компонента                                                                            |
+| `useTimelineActivityId()`                     | `string` или `null`    | Идентификатор текущего действия на временной шкале при рендеринге пользовательской строки временной шкалы |
+| `useColorScheme()`                            | `'light'` или `'dark'` | Активная цветовая схема интерфейса хоста (значение `System` уже определено)                               |
+| `useFrontComponentExecutionContext(selector)` | различается            | Доступ к полному контексту выполнения с помощью функции-селектора                                         |
+
+## Переменные приложения
+
+Переменные приложения, определенные в [`defineApplication()`](/l/ru/developers/extend/apps/config/application) с `isSecret: false`, доступны внутри фронтенд-компонентов через утилиту `getApplicationVariable`:
+
+```tsx src/front-components/greeting.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getApplicationVariable } from 'twenty-sdk/front-component';
+
+const Greeting = () => {
+  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';
+
+  return <p>Hello, {recipientName}!</p>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'greeting',
+  component: Greeting,
+});
+```
+
+<Warning>
+Секретные переменные (`isSecret: true`) **не** доступны фронтенд-компонентам. Они доступны только в [логических функциях](/l/ru/developers/extend/apps/logic/logic-functions), которые выполняются на стороне сервера. Это предотвращает отправку в браузер конфиденциальных значений, таких как ключи API.
+</Warning>
+
+`getApplicationVariable` всегда возвращает **строку** (или `undefined`), независимо от объявленного для переменной `type`. Строка сериализуется единообразно в зависимости от типа (логические значения как `"true"` / `"false"`, числа как десятичные строки, массивы / объекты как JSON) в том же формате, который используется для логической функции `process.env` — разбирайте её самостоятельно (`Number(...)`, `JSON.parse(...)`, `=== 'true'`). См. [типы переменных](/l/ru/developers/extend/apps/config/application#variable-types).
+
+Следующие системные переменные всегда доступны через `process.env`:
+
+| Переменная                | Описание                                                                                                                                                                                                                            |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TWENTY_API_URL`          | Базовый URL основного API Twenty                                                                                                                                                                                                    |
+| `TWENTY_APP_ACCESS_TOKEN` | Кратковременный токен, область действия которого ограничена пересечением роли вошедшего в систему пользователя и роли вашего приложения, поэтому компонент никогда не сможет сделать больше, чем человек, который его просматривает |
+
+### `TWENTY_FUNCTIONS_URL`
+
+Twenty также внедряет `TWENTY_FUNCTIONS_URL` во фронт-компоненты и логические функции: это базовый URL, по которому обслуживаются HTTP-триггерные логические функции вашего приложения.
+
+Он существует, потому что этот URL не всегда совпадает с самим сервером Twenty. В Twenty Cloud маршруты приложения обслуживаются на выделенном домене для каждого рабочего пространства (`https://\<your-workspace-subdomain>.withtwenty.com` или основном общедоступном домене приложения, если он настроен), чтобы ответы, сформированные приложением, отдавались с изолированного источника, а не с источника приложения Twenty. Самостоятельно развёрнутые и локальные экземпляры обслуживают маршруты приложения с префиксом `/s` на самом сервере и могут вовсе не задавать эту переменную. Поскольку базовый URL различается для каждого рабочего пространства и экземпляра, ваш код не может жёстко прописать его — сервер внедряет правильное значение во время выполнения.
+
+Вам редко нужно читать его напрямую. Вызывайте свои маршруты через `RestApiClient` с путём, начинающимся с `/s/`, и клиент разрешит URL за вас: он убирает префикс `/s` и обращается к `TWENTY_FUNCTIONS_URL`, а если переменная не задана, использует `\<TWENTY_API_URL>/s`. Используйте `resolveUrl('/s/\<path>')`, чтобы получить абсолютный URL без отправки запроса, например для ссылки. Читайте переменную напрямую только при ручной сборке URL:
+
+```ts
+const routeUrl = `${process.env.TWENTY_FUNCTIONS_URL || `${process.env.TWENTY_API_URL}/s`}/documents/generate`;
+```
+
+## API взаимодействия с хостом
+
+Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций из `twenty-sdk`:
+
+| Функция                                            | Описание                                                                                                                                                                                |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigate(to, params?, queryParams?, options?)`    | Перейти на страницу в приложении                                                                                                                                                        |
+| `openSidePanelPage(params)`                        | Открыть боковую панель                                                                                                                                                                  |
+| `closeSidePanel()`                                 | Закрыть боковую панель                                                                                                                                                                  |
+| `openCommandConfirmationModal(params)`             | Показать диалог подтверждения                                                                                                                                                           |
+| `enqueueSnackbar(params)`                          | Показать всплывающее уведомление                                                                                                                                                        |
+| `unmountFrontComponent()`                          | Размонтировать компонент                                                                                                                                                                |
+| `updateProgress(progress)`                         | Обновить индикатор прогресса                                                                                                                                                            |
+| `uploadFile(file, { fieldMetadataId, fileName? })` | Загрузите `Blob` в поле FILES; возвращает `{ status: 'uploaded', file: { fileId, path, url, size, mimeType } }` или `{ status: 'failed', reason: 'invalid-params' \| 'upload-failed' }` |
+
+Пример, который использует API хоста для показа snackbar и закрытия боковой панели после завершения действия:
+
+```tsx src/front-components/archive-record.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { enqueueSnackbar, closeSidePanel, useSelectedRecordIds } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const ArchiveRecord = () => {
+  const [recordId] = useSelectedRecordIds();
+
+  const handleArchive = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      updateTask: {
+        __args: { id: recordId, data: { status: 'ARCHIVED' } },
+        id: true,
+      },
+    });
+
+    await enqueueSnackbar({
+      message: 'Record archived',
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Archive this record?</p>
+      <button onClick={handleArchive}>Archive</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
+  name: 'archive-record',
+  description: 'Archives the current record',
+  component: ArchiveRecord,
+});
+```
+
+### Хранилище
+
+`localStorage` и `sessionStorage` работают так же, как на обычной странице, с использованием стандартного синхронного API. Ваши ключи ограничены рамками установки приложения и учетной записью вошедшего пользователя: ни одно другое приложение не может их прочитать, а другой пользователь, вошедший в тот же браузер, начинает с пустого хранилища. Значения, записанные в `localStorage`, остаются на устройстве при перезагрузках; `sessionStorage` действует в течение браузерной сессии.
+
+```tsx src/front-components/note-draft.tsx
+import { useState } from 'react';
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const NoteDraft = () => {
+  const [draft, setDraft] = useState(() => localStorage.getItem('draft') ?? '');
+
+  const handleChange = (nextDraft: string) => {
+    setDraft(nextDraft);
+    localStorage.setItem('draft', nextDraft);
+  };
+
+  return (
+    <textarea value={draft} onChange={(event) => handleChange(event.target.value)} />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-def0-890123456789',
+  name: 'note-draft',
+  description: 'Keeps an unsaved note on this device',
+  component: NoteDraft,
+});
+```
+
+Twenty хранит значения от имени вашего приложения, поэтому запись применяется локально сразу же и сохраняется в фоновом режиме. Операции чтения никогда не блокируются ожиданием хоста. Ничто не синхронизируется: значения не следуют за пользователем в другой браузер или на другой компьютер, поэтому используйте [хранилище ключ-значение](/l/ru/developers/extend/apps/logic/key-value-store) логической функции для всего, что должно пережить смену устройства.
+
+Записи ограничены, и для каждого лимита считаются символы, а не байты: ключи могут содержать не более 512 символов, одно значение — не более 262144 символов, а каждое хранилище — не более 1048576 символов на приложение и пользователя. Запись, нарушающая лимит, выбрасывает `QuotaExceededError`, как и браузерный API.
+
+### Работа с несколькими записями
+
+Используйте `useSelectedRecordIds()` для обработки нескольких выбранных записей. Это полезно для массовых операций:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds } from 'twenty-sdk/front-component';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const BulkExport = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+
+  const handleExport = async () => {
+    const client = new CoreApiClient();
+
+    for (const recordId of selectedRecordIds) {
+      await client.mutation({
+        updateTask: {
+          __args: { id: recordId, data: { exported: true } },
+          id: true,
+        },
+      });
+    }
+
+    await enqueueSnackbar({
+      message: `Exported ${selectedRecordIds.length} records`,
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Export {selectedRecordIds.length} selected record(s)?</p>
+      <button onClick={handleExport}>Export</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+  name: 'bulk-export',
+  description: 'Export selected records',
+  component: BulkExport,
+});
+```
+
+Сделайте его доступным через [элемент командного меню](/l/ru/developers/extend/apps/layout/command-menu-items), доступный только при выборе записей:
+
+```ts src/command-menu-items/bulk-export.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
+  label: 'Bulk Export',
+  availabilityType: 'RECORD_SELECTION',
+  frontComponentUniversalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+});
+```
+
+## Публичные ресурсы
+
+Компоненты фронтенда могут получать доступ к файлам из каталога приложения `public/` с помощью `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'logo',
+  component: Logo,
+});
+```
+
+См. [раздел о публичных ресурсах](/l/ru/developers/extend/apps/config/public-assets) для подробностей.
+
+## Распространение зависимостей между фронт-компонентами
+
+По умолчанию, каждая передняя часть объединяет свою собственную копию импортируемых библиотек, так что приложение с пятью компонентами поставляет React пять раз. Объявление общих зависимостей в пакете вашего приложения. son\`, чтобы собрать эти библиотеки один раз и загрузить каждый компонент приложения из одного кэшированного файла:
+
+```json package.json
+{
+  "frontComponentSharedDependencies": ["react", "react-dom/client", "twenty-ui/input"]
+}
+```
+
+Затем каждый компонент импортирует его зависимости точно так же, как и раньше: ничего не изменяется в коде компонента:
+
+```tsx src/front-components/counter.tsx
+import { useState } from 'react';
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'counter',
+  component: Counter,
+});
+```
+
+Несколько важных моментов:
+
+* **Один общий набор зависимостей для каждого приложения.** Пакет построен из зависимостей вашего приложения, так что вы сохраняете полный контроль над версиями, которые вы поставляете.
+* **Перечислите точные спецификаторы, которые вы импортируете.** `twenty-ui/input` и `twenty-ui/display` являются двумя записями; только имя пакета не содержит подпусков. Список `react` автоматически охватывает `react/jsx-runtime`.
+* **Поделиться `react-dom/client` вместе с `react`.** Каждый компонент проделывает `createRoot`, поэтому оставив его, значит каждый компонент всё ещё объединяет React DOM.
+* \*\*Набор кэширован. \* Он обслуживается под content-hash URL с длительным неизменяемым кэшем, так что загружается один раз и повторно используется всеми компонентами приложения до тех пор, пока одна из зависимостей не изменится.
+* **Компоненты, импортирующие ни один из общих пакетов никогда не загружают его.**
+
+## Стилизация
+
+Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:
+
+* **Встроенные стили** — `style={{ color: 'red' }}`
+* **Twenty UI components** — собственная библиотека компонентов Twenty; см. раздел [Using Twenty UI components](#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`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1). Компоненты фронтенда могут использовать его для кнопок, тегов, статусных плашек, чипов, аватаров, иконок, типографики и токенов темы, которые автоматически соответствуют светлой и тёмной теме рабочего пространства.
+
+### Установка
+
+Добавьте пакет в своё приложение, зафиксировав его на версии, с которой поставляется ваш экземпляр Twenty:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` включается в ваш компонент фронтенда на этапе сборки, поэтому его достаточно иметь в зависимостях вашего приложения — во время выполнения ничего настраивать не нужно.
+
+### Импорт компонентов
+
+Импортируйте из соответствующего подпути, а не из корня пакета, чтобы в ваш бандл попали только те компоненты, которые вы используете:
+
+| Подпуть                     | Что экспортирует                                  |
+| --------------------------- | ------------------------------------------------- |
+| `twenty-ui/input`           | `Button` и элементы ввода формы                   |
+| `twenty-ui/data-display`    | `Tag`, `Status`, `Chip`, `Avatar` и другие        |
+| `twenty-ui/feedback`        | `Callout`, `Banner`, `Info` и другие              |
+| `twenty-ui/typography`      | `H1Title`, `H2Title`, `H3Title`, `Label` и другие |
+| `twenty-ui/icon`            | Компоненты `Icon*` (например, `IconCheck`)        |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables`              |
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
+
+const StyledWidget = () => {
+  return (
+    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
+      <Button title="Click me" onClick={() => alert('Clicked!')} />
+      <Tag text="Active" color="green" />
+      <Status color="green" text="Online" />
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+  name: 'styled-widget',
+  component: StyledWidget,
+});
+```
+
+### Иконки
+
+Импортируйте отдельные иконки из `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Каждая именованная иконка участвует в tree-shaking, поэтому импорт нескольких иконок почти не увеличит размер вашего бандла. Избегайте `IconsProvider`, `useIcons` и `iconsState` — они подключают весь набор иконок Tabler (несколько мегабайт).
+
+### Темизация и токены темы
+
+Компоненты Twenty UI автоматически подстраиваются под светлую и тёмную темы рабочего пространства — рендерер применяет активную цветовую схему на хосте, а компоненты вычисляют свои цвета относительно неё.
+
+Чтобы использовать те же дизайн‑токены в собственных встроенных стилях, вызовите хук `useTheme()`. Он возвращает токены темы Twenty (отступы, цвета, радиусы, шрифты), привязанные к активной теме, без необходимости настраивать `ThemeProvider` в вашем компоненте:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+  const theme = useTheme();
+
+  return (
+    <div
+      style={{
+        padding: theme.spacing[4],
+        background: theme.background.secondary,
+        color: theme.font.color.primary,
+      }}
+    >
+      Themed card
+    </div>
+  );
+};
+```
+
+Поскольку `useTheme()` — это хук, вы читаете токены внутри тела компонента, поэтому значения всегда соответствуют активной теме. Та же карта токенов также экспортируется как константа `themeCssVariables`, но в компонентах фронтенда предпочтительнее использовать `useTheme()` — модульная константа, разыменующая `themeCssVariables`, может быть `undefined`, пока извлекается манифест приложения.
+
+Чтобы явно разветвлять логику по активной цветовой схеме, считайте её с помощью `useColorScheme()` из `twenty-sdk/front-component`, который возвращает `'light'` или `'dark'`.
+
+## Нынешние ограничения
+
+Активно разрабатываются передние компоненты. Рендеринг, стилизация, обработка событий, измерение элементов и работа с хранилищем браузера работают хорошо. Все, что выходит *за рамки* этих возможностей (вызов DOM‑метода на ref, отслеживание изменения размеров элементов, порталирование за пределы вашего дерева), сегодня отсутствует или реализовано не полностью, и в большинстве случаев это тихо ломается: ни исключения, ни ошибки TypeScript, поскольку обвязка типизирована под полный DOM браузера.
+
+Если один из этих блоков вас, [откройте задачу](https://github.com/twentyhq/twenty/issues/new/choose), чтобы получить приоритет.
+
+### Макет и измерение
+
+Элементы могут измерять себя сами: хост отражает геометрию в песочницу, поэтому чтения выполняются локально, но могут отставать до одного кадра, а первое чтение никогда ранее не измеренного элемента возвращает нули. После записи выполните повторное чтение в колбэке `requestAnimationFrame` или в эффекте.
+
+| API                                                                                      | Что происходит                                                                                                                         |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `getBoundingClientRect()`, `offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, ... | Работают, из зеркала; присваивание `scrollTop` / `scrollLeft` не имеет эффекта                                                         |
+| `getClientRects()`, `window.matchMedia()`                                                | Бросает                                                                                                                                |
+| `window.innerWidth`, `innerHeight`, `devicePixelRatio`, `scrollX`, `scrollY`             | Работают, сообщая размеры области просмотра браузера; собственный размер вашего виджета — `document.body.clientWidth` / `clientHeight` |
+| `window.getComputedStyle()`                                                              | Возвращает только встроенные (inline) стили элемента и никогда не возвращает вычисленный хостом каскад                                 |
+| `ResizeObserver`, `IntersectionObserver`                                                 | `Справочная ошибка` (защита `typeof` делает работу)                                                                                    |
+| `MutationObserver`                                                                       | Работает, включая `subtree`, `attributeFilter`, старые значения и `takeRecords()`                                                      |
+
+Позиционирование с использованием `getBoundingClientRect` теперь работает, но всё, что отслеживает изменение размеров через `ResizeObserver` (recharts `ResponsiveContainer`, `autoUpdate` из Floating UI), по‑прежнему не работает. В любом случае отдавайте предпочтение CSS для верстки: ваша таблица стилей применяется к реальной странице, поэтому flexbox, grid, `aspect-ratio`, `clamp()` и `@container` работают как обычно, без задержки кадра.
+
+<Note>
+`requestAnimationFrame`, `fetch`, `setTimeout` и `queueMicrotask` работают без префикса `window.`. Только `window.requestAnimationFrame(...)` и брошенные друзья.
+</Note>
+
+### DOM access
+
+`ref` дает вам элемент песочницы, а не `HTMLElement`.
+
+| Что вы пишете                                                                                               | Что происходит                                                     | Использовать вместо                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()` | Бросает                                                            | Контролируемые компоненты; читать значения из `event.target`                                                                                                                         |
+| `element.classList.add(...)`                                                                                | Броски (`classList` `undefined`)                                   | Создайте строку `className` самостоятельно                                                                                                                                           |
+| `document.createTreeWalker()`                                                                               | Бросает                                                            | `querySelector()` / `querySelectorAll()` и `getElementById()` работают; `getElementsByClassName()` тоже работает, но возвращает статическую коллекцию, а не «живой» `HTMLCollection` |
+| `document.activeElement`                                                                                    | Всегда `неопределённые`                                            | Отслеживать фокус с с помощью «onFocus» / «onBlur»                                                                                                                                   |
+| `canvas`                                                                                                    | Отображает ничего, без ошибок                                      | SVG или рисуйте вне экрана и показывайте результат в элементе `img`                                                                                                                  |
+| `createPortal(node, document.body)`                                                                         | Отображает ничего, в то время как «isConnected» сообщает об успехе | Наслоения в строке `position: absolute` или передайте библиотеке свой собственный элемент контейнера                                                                                 |
+
+Портал зазор поэтому всплывающие окна Radix, Headless UI, MUI и react-select не отображаются по умолчанию. Большинство из них принимают реквизиты контейнера; указывайте их на отображаемый элемент.
+
+### События
+
+События мыши, указателя, касания, перетаскивания, клавиатуры, фокуса, `input`/`change`/`submit`, `scroll`/`wheel`/`contextmenu` и `animationend`/`transitionend` передаются хосту, плюс несколько на элемент: `load`/`error` на `img`, буфер обмена и композиция на `input`/`textarea`, медиа на `video`/`audio`, `toggle` на `details`/`dialog`. Все остальное (`onAuxClick`, `onSelect`, `onInvalid`, `onReset`, `onAnimationStart`, захват указателя, `onLoad` у `img`) отбрасывается без предупреждения.
+
+`document.addEventListener()` и `window. ddEventListener()` регистрируется без ошибок и никогда не стреляет, поэтому перетаскивание останавливается, как только указатель покидает начатый элемент. `event.preventDefault()` тоже не пересекается; форма представления, `dragover`/`drop` и ссылки уже охраняются для вас.
+
+### Атрибуты и стиль
+
+Каждый элемент передает свои собственные свойства хостовому DOM (`href` на `a`, `src`/`alt` на `img`, `value`/`placeholder`/`disabled` на `input` и так далее), плюс общий набор на каждом элементе: `id`, `className`, `style`, `title`, `tabIndex`, `role`, `draggable` и любой атрибут `aria-*` / `data-*` (через дефис, поэтому `ariaLabel` отбрасывается). Всё, что за пределами тихо отбрасывается, поэтому выражать пользовательское состояние как `data-*`.
+
+CSS компонента, будь то из `import './styles.css'`, CSS-in-JS или элемента `style`, внедряется в `head` хостовой страницы **без области видимости**. Таким образом, имена классов конфликтуют с собственным Twenty's (префикс их), и никогда не пишут пустые `div { ... }` селекторы), а `@media` совпадает с вашим окном браузера вместо виджета (используйте `@container` с вашим собственным `container-type`). Встроенные свойства не затронуты.
+
+### Хранилище и сеть
+
+`localStorage` и `sessionStorage` предоставляются Twenty, а не браузером: компонент выполняется в воркере с непрозрачным источником (origin), поэтому хост хранит значения от имени вашего приложения. См. раздел [storage](#storage) для получения информации об области действия и ограничениях. IndexedDB, cookies, Cache API и `BroadcastChannel` по-прежнему недоступны. Чтобы сохранять состояние между устройствами, вызовите [логическую функцию](/l/ru/developers/extend/apps/logic/logic-functions) и используйте ее [хранилище ключ-значение](/l/ru/developers/extend/apps/logic/key-value-store).
+
+`fetch` работает с сохранениями:
+
+* Звонки к Twenty API и маршрутам вашего приложения проксируются узлом, поэтому предпочитайте [`RestApiClient`](#calling-the-twenty-rest-api). В случае проксируемых вызовов `AbortSignal` и другие опции `RequestInit` удаляются, и поддерживаются только тела `string` и `URLSearchParams`.
+* Другие источники оставляют песчаник с `Origin: null`, так что сторонний API отвечает, только если он посылает `Access-Control-Allow-Origin: *`. Вызовите его из логической функции.
+* `fetch('/rest/people')` никогда не совпадает с двадцать API, потому что песочница не имеет URL страницы для разрешения относительного пути.
+
+### Захват мультимедиа
+
+`navigator.mediaDevices.getUserMedia()` и `MediaRecorder` работают внутри фронт-компонентов благодаря полифиллам песочницы, поэтому стандартный код записи выполняется без изменений, а `MediaRecorder.isTypeSupported` возвращает true для распространенных комбинаций контейнер/кодек. Подробные объекты ограничений `getUserMedia` принимаются, но не передаются дальше — хост выполняет захват с настройками по умолчанию для запрошенных типов — и одновременно во всех приложениях может быть активен только один захват. Сохраните записанный `Blob` с помощью хост-функции `uploadFile`.
+
+### Другие пробелы
+
+* **Содержимое файла.** Элемент `input` с типом `file` предоставляет вашему обработчику только метаданные файла, а не байты, поэтому `FileReader` недоступен. Чтобы загрузить `Blob`, который уже есть в вашем коде (например, созданный `MediaRecorder`), используйте хост-функцию `uploadFile`.
+* **Перетащите приложения.** Перетаскивайте события, но `event.dataTransfer` `неопределённый`.
+* **Узел встроенный** `fs`, `path` и `node:crypto` не срабатывают сборки, так что переместитесь с помощью [logic функции](/l/ru/developers/extend/apps/logic/logic-functions). Веб-криптовалюты, `fetch`, `TextEncoder` и `URL`.
+* **`iframe`** всегда повторно изолируется без `allow-same-origin`, поэтому встраиваемый контент, зависящий от собственной сессии, отображается как неавторизованный. У него также нет `onLoad`.