Skip to content

The open alternative to Salesforce, designed for AI.

14.6 KB
Raw Blame
---
title: Начало работы
description: Установите Twenty UI в React-приложении и используйте его компоненты и темы.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## Обзор

Twenty UI — это React-библиотека пользовательского интерфейса с открытым исходным кодом от Twenty. Она предоставляет базовые примитивы, общие компоненты, значки и токены темы с готовым CSS, поэтому вашему приложению не требуется компилятор CSS-in-JS.

## Установить

Для существующего React-приложения установите библиотеку. Требуется React 19.

```bash
yarn add twenty-ui
```

[Редактор кода](/ru/ui/components/code-editor/code-editor) имеет отдельную точку входа: `twenty-ui/components/code-editor`. Другим компонентам Monaco не требуется. Чтобы использовать редактор кода, перед его монтированием установите необязательные одноранговые зависимости и настройте воркеры Monaco для вашего сборщика:

```bash
yarn add @monaco-editor/react monaco-editor
```

Если вы создаёте приложение Twenty, следуйте инструкциям в разделе [Использование компонентов Twenty UI](/ru/developers/extend/apps/layout/front-components#using-twenty-ui-components). Средство рендеринга фронт-компонентов предоставляет тему рабочего пространства и настраивается иначе, чем автономное браузерное приложение. Используйте `twenty-ui`, `twenty-sdk` и `twenty-client-sdk` одной версии.

## Загрузите стили и предоставьте тему

Один раз импортируйте таблицу стилей компонентов и таблицу стилей темы в точке входа вашего приложения. `ThemeProvider` применяет класс активной темы и делает значения темы доступными для компонентов.

```tsx
import { Field, Input } from 'twenty-ui/primitives/input';
import { ThemeProvider } from 'twenty-ui/theme';

import 'twenty-ui/style.css';
import 'twenty-ui/theme-light.css';

export const App = () => (
  <ThemeProvider colorScheme="light">
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Input name="email" type="email" placeholder="[email protected]" />
      <Field.Description>Use your work email address.</Field.Description>
    </Field.Root>
  </ThemeProvider>
);
```

Таблица стилей компонентов включает глобальный сброс стилей. Проверьте его влияние при добавлении Twenty UI в существующее приложение.

## Переопределение стилей

Twenty UI помещает стили компонентов и сброс в каскадный слой `twenty-ui`. Стили, которые вы пишете вне слоя, например `className`, CSS-модуль или правило CSS-in-JS, переопределяют правила из слоёв независимо от специфичности селектора или порядка импорта. Таблицы стилей темы и необязательные глобальные правила Monaco для редактора остаются вне слоёв.

Глобальные сбросы элементов в вашем приложении также находятся вне слоёв, поэтому они будут переопределять компоненты Twenty UI. Объявите для них слой до загрузки таблицы стилей Twenty UI:

```css
@layer reset, twenty-ui;

@layer reset {
  button {
    font: inherit;
  }
}
```

При использовании Tailwind CSS v4 разместите Twenty UI между базовым и служебным слоями Tailwind:

```css
@layer theme, base, twenty-ui, components, utilities;
```

## Выберите точку входа

Импортируйте компоненты из их общедоступного подпути, чтобы импорты оставались целенаправленными:

Примитивы — это базовые элементы управления, включая составные элементы управления, такие как Select,
Popover и AlertDialog. Общие компоненты объединяют примитивы в повторяющиеся
шаблоны дизайна и повторно используемые строительные блоки приложения. Оба получают данные и обратные вызовы
от приложения.

Используйте [MainButton](/ru/ui/components/input/main-button) для основных действий и
[LightButton](/ru/ui/components/input/light-button) для второстепенных действий. Оба
поступают из `twenty-ui/components/input` и используют общий базовый
контракт взаимодействия [Button](/ru/ui/primitives/input/button). Маршрутизация и макет
страницы остаются в приложении.

У каждого примитива и семейства общих компонентов есть соответствующая общедоступная точка входа, например
`twenty-ui/primitives/input` и `twenty-ui/components/settings`. Агрегированные точки входа
`twenty-ui/primitives` и `twenty-ui/components` экспортируют соответствующие семейства.
Корневая точка входа `twenty-ui` повторно экспортирует примитивы, общие компоненты, значки, токены темы
и утилиты. Ресурсы, вспомогательные средства тестирования и необязательный редактор кода имеют отдельные точки входа.

| Импорт                               | Содержимое                                                                                                  |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `twenty-ui/assets`                   | Логотипы и статические ресурсы                                                                              |
| `twenty-ui/components`               | Все семейства общих компонентов, кроме необязательного редактора                                            |
| `twenty-ui/components/data-display`  | Группы аватаров, блоки команд, деревья JSON, метрики и плитки значков                                       |
| `twenty-ui/components/feedback`      | Выноски, встроенные баннеры и уведомления                                                                   |
| `twenty-ui/components/input`         | Предустановки кнопок, специализированные поля ввода, средства выбора и сегментированные элементы управления |
| `twenty-ui/components/layout`        | Разделы, списки с переполнением и переходы значков                                                          |
| `twenty-ui/components/navigation`    | Раскрывающиеся списки, композиции меню и действия вкладок                                                   |
| `twenty-ui/components/settings`      | Строки настроек с элементами управления и подписями                                                         |
| `twenty-ui/components/code-editor`   | Редактор кода, заголовок редактора и вспомогательные функции темы редактора                                 |
| `twenty-ui/primitives`               | Все семейства примитивов                                                                                    |
| `twenty-ui/primitives/accessibility` | Скрытые элементы и вспомогательные средства взаимодействия с клавиатурой                                    |
| `twenty-ui/primitives/data-display`  | Аватары, бейджи, чипы, теги, образцы цветов и индикаторы состояния                                          |
| `twenty-ui/primitives/feedback`      | Баннеры, индикаторы прогресса, загрузчики и скелетоны                                                       |
| `twenty-ui/primitives/input`         | Кнопки и элементы управления формы                                                                          |
| `twenty-ui/primitives/layout`        | Разворачивание, разделители, направление и изменение размера                                                |
| `twenty-ui/primitives/navigation`    | Навигационные цепочки, элементы списков и вкладки                                                           |
| `twenty-ui/primitives/surfaces`      | Карточки, диалоговые окна, всплывающие элементы и подсказки                                                 |
| `twenty-ui/primitives/typography`    | Текст, заголовки, сочетания клавиш и текст с переполнением                                                  |
| `twenty-ui/icon`                     | [Иконки и динамический поиск](/ru/ui/icons)                                                                    |
| `twenty-ui/testing`                  | [Декораторы и макеты Storybook](/ru/ui/testing)                                                                |
| `twenty-ui/theme`                    | Поставщик темы, хуки и ссылки на переменные CSS                                                             |
| `twenty-ui/utilities`                | Хуки и общие утилиты                                                                                        |

Импортируйте отдельные иконки, например `IconCheck`, из `twenty-ui/icon`. Динамический поставщик иконок включает полный каталог иконок, поэтому используйте его только для интерфейсов, которым требуется искать иконки во время выполнения.

## Адаптивные хуки

Импортируйте `useIsMobile`, `useIsTouchDevice` и `useMediaQuery` из `twenty-ui/utilities`.

| Хук                    | Запрос                                                            | Использовать                                                       |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| `useIsMobile()`        | `MOBILE_MEDIA_QUERY`, вплоть до `MOBILE_VIEWPORT` включительно    | Выберите компактный макет.                                         |
| `useIsTouchDevice()`   | `TOUCH_DEVICE_MEDIA_QUERY`, `(hover: none) and (pointer: coarse)` | Выберите поведение сенсорного взаимодействия независимо от ширины. |
| `useMediaQuery(query)` | Любой медиазапрос, поддерживаемый `window.matchMedia`             | Подпишитесь на пользовательский медиазапрос.                       |

Константы запросов поступают из `twenty-ui/utilities`; `MOBILE_VIEWPORT` поступает из `twenty-ui/theme`. Подписки совместно используют один `MediaQueryList` для каждого запроса и обновляются при изменении его соответствия. Хуки возвращают `false` во время серверного рендеринга, первого рендеринга гидратации и когда `window.matchMedia` недоступен.

В [фронт-компоненте Twenty](/ru/developers/extend/apps/layout/front-components#current-limitations) запросы ширины ориентируются на контейнер виджета. Поэтому `useIsMobile` ориентируется на ширину виджета, а `useIsTouchDevice` — на основное устройство ввода. Используйте [переопределения историй](/ru/ui/testing#media-query-overrides), чтобы протестировать эти состояния в Storybook.

## Продолжить

* [Темизация](/ru/ui/theming): используйте семантические токены и локальные переопределения.
* [Тёмный режим](/ru/ui/dark-mode): переключайтесь между светлой и тёмной палитрами.

## Просмотреть библиотеку

* [Примитивы](/ru/ui/primitives/overview): базовые элементы управления, сгруппированные по семействам, с примерами использования и справочными материалами по API.
* [Компоненты](/ru/ui/components/overview): общие пресеты дизайна и многократно используемые строительные блоки приложения, составленные из примитивов.

<PageBanner illustration="card-page-ui-library" />