Перейти к основному содержанию

Обзор

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

Установить

Для существующего React-приложения установите библиотеку. Требуется React 19.
Редактор кода имеет отдельную точку входа: twenty-ui/components/code-editor. Другим компонентам Monaco не требуется. Чтобы использовать редактор кода, перед его монтированием установите необязательные одноранговые зависимости и настройте воркеры Monaco для вашего сборщика:
Если вы создаёте приложение Twenty, следуйте инструкциям в разделе Использование компонентов Twenty UI. Средство рендеринга фронт-компонентов предоставляет тему рабочего пространства и настраивается иначе, чем автономное браузерное приложение. Используйте twenty-ui, twenty-sdk и twenty-client-sdk одной версии.

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

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

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

Twenty UI помещает стили компонентов и сброс в каскадный слой twenty-ui. Стили, которые вы пишете вне слоя, например className, CSS-модуль или правило CSS-in-JS, переопределяют правила из слоёв независимо от специфичности селектора или порядка импорта. Таблицы стилей темы и необязательные глобальные правила Monaco для редактора остаются вне слоёв. Глобальные сбросы элементов в вашем приложении также находятся вне слоёв, поэтому они будут переопределять компоненты Twenty UI. Объявите для них слой до загрузки таблицы стилей Twenty UI:
При использовании Tailwind CSS v4 разместите Twenty UI между базовым и служебным слоями Tailwind:

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

Импортируйте компоненты из их общедоступного подпути, чтобы импорты оставались целенаправленными: Примитивы — это базовые элементы управления, включая составные элементы управления, такие как Select, Popover и AlertDialog. Общие компоненты объединяют примитивы в повторяющиеся шаблоны дизайна и повторно используемые строительные блоки приложения. Оба получают данные и обратные вызовы от приложения. Используйте MainButton для основных действий и LightButton для второстепенных действий. Оба поступают из twenty-ui/components/input и используют общий базовый контракт взаимодействия Button. Маршрутизация и макет страницы остаются в приложении. У каждого примитива и семейства общих компонентов есть соответствующая общедоступная точка входа, например twenty-ui/primitives/input и twenty-ui/components/settings. Агрегированные точки входа twenty-ui/primitives и twenty-ui/components экспортируют соответствующие семейства. Корневая точка входа twenty-ui повторно экспортирует примитивы, общие компоненты, значки, токены темы и утилиты. Ресурсы, вспомогательные средства тестирования и необязательный редактор кода имеют отдельные точки входа. Импортируйте отдельные иконки, например IconCheck, из twenty-ui/icon. Динамический поставщик иконок включает полный каталог иконок, поэтому используйте его только для интерфейсов, которым требуется искать иконки во время выполнения.

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

Импортируйте useIsMobile, useIsTouchDevice и useMediaQuery из twenty-ui/utilities. Константы запросов поступают из twenty-ui/utilities; MOBILE_VIEWPORT поступает из twenty-ui/theme. Подписки совместно используют один MediaQueryList для каждого запроса и обновляются при изменении его соответствия. Хуки возвращают false во время серверного рендеринга, первого рендеринга гидратации и когда window.matchMedia недоступен. В фронт-компоненте Twenty запросы ширины ориентируются на контейнер виджета. Поэтому useIsMobile ориентируется на ширину виджета, а useIsTouchDevice — на основное устройство ввода. Используйте переопределения историй, чтобы протестировать эти состояния в Storybook.

Продолжить

  • Темизация: используйте семантические токены и локальные переопределения.
  • Тёмный режим: переключайтесь между светлой и тёмной палитрами.

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

  • Примитивы: базовые элементы управления, сгруппированные по семействам, с примерами использования и справочными материалами по API.
  • Компоненты: общие пресеты дизайна и многократно используемые строительные блоки приложения, составленные из примитивов.