Обзор
Примитивы — это базовые элементы управления в Twenty UI. Они включают поля ввода, элементы отображения, навигацию и составные элементы управления, такие как Select, Popover и AlertDialog. Каждый примитив получает данные и функции обратного вызова из вашего приложения. Импортируйте примитивы из точки входа семейства, напримерtwenty-ui/primitives/input. Совокупная точка входа twenty-ui/primitives также экспортирует все семейства примитивов. Сведения об установке и настройке темы см. в разделе Начало работы.
Компоненты объединяют эти примитивы в общие предустановки дизайна и многократно используемые строительные блоки приложений.
Управление состоянием
Используйте неконтролируемое состояние, когда компонент может самостоятельно управлять своими взаимодействиями. Свойство по умолчанию задаёт начальное состояние. Используйте контролируемое состояние, когда приложению требуется согласовать это состояние с другими элементами управления, навигацией или данными приложения.
В контролируемом режиме передайте текущее состояние и обновляйте его в функции обратного вызова при изменении. В неконтролируемом режиме вы всё равно можете отслеживать изменения, не беря на себя управление состоянием. Добавление одной лишь функции обратного вызова не делает компонент контролируемым.
Выберите режим для каждого состояния и сохраняйте его на протяжении всего жизненного цикла компонента. Свойства по умолчанию инициализируют состояние; их последующее изменение не заменяет текущее состояние. Не передавайте одновременно свойство по умолчанию и контролируемое свойство для одного и того же состояния.
Некоторые компоненты имеют более одного независимого состояния. Например, Select может иметь контролируемое значение и неконтролируемую видимость всплывающего окна.
Состояние относится к части, которая управляет взаимодействием. Настраивайте выбор радиокнопки в RadioGroup, а не в каждом Radio. Компоненты отображения, такие как Text, не имеют контролируемого или неконтролируемого режима. Toast делегирует управление своей видимостью и удалением приложению.
Композиция
Составные примитивы предоставляют части, такие какSelect.Root, Select.Trigger и Select.Popup. Держите связанные части под одним корневым элементом в дереве компонентов, чтобы они совместно использовали состояние и отношения доступности. Раздел анатомии каждого компонента определяет обязательные части и необязательное содержимое.
Слоты, такие как InputGroup.startElement и ListItem.actions, принимают узлы React в качестве свойств. Они добавляют содержимое в макет компонента. Части и слоты — это разные API; используйте имена, указанные в руководстве по компоненту.
Композиция всплывающего окна
Select, Popover и Autocomplete предоставляют отдельные частиPortal, Positioner и Popup:
Размещайте Popup внутри Positioner, а Positioner — внутри Portal. Размещайте содержимое внутри Popup и при необходимости явно добавляйте Arrow. Портал может перемещать отрисованный DOM в другой контейнер, сохраняя иерархию компонентов и контекст. См. темизацию для получения сведений об ограниченных контейнерах портала.
Каждая отрисованная часть сохраняет собственные нативные атрибуты, цель ref и композицию рендеринга. Autocomplete также сохраняет установленные вышестоящие части коллекции, группировки, сетки, фильтрации и статуса.
Dialog и AlertDialog предоставляют отдельные части
Portal, Backdrop, Viewport и Popup. Настройте монтирование и назначение в Portal, внешний вид наложения в Backdrop и Viewport, а также размер содержимого и фокус в Popup. Каждая часть сохраняет собственные нативные атрибуты, цель ref и композицию рендеринга. Эти API диалогов предназначены для автономного UI и хоста Twenty. Компоненты Front используют API диалогов хоста SDK.
Пользовательские компоненты
Для частей, поддерживающихrender, передайте совместимый элемент или компонент, чтобы заменить элемент по умолчанию. Например, Popover.Trigger может использовать Button из Twenty UI, сохраняя поведение триггера.
Пользовательская обёртка должна передавать предоставленные props и ref интерактивному элементу. Это сохраняет обработчики событий, атрибуты доступности, позиционирование и восстановление фокуса. В этом примере они передаются через Button, который прикрепляет их к своей нативной кнопке.
render и сохраняйте каждое действие как отдельный интерактивный элемент управления. При добавлении собственного поведения сохраняйте обработчики и ref, предоставленные вашей обёртке. Ref должен достигать элемента, получающего фокус.
Используйте нативную кнопку для частей, подобных кнопке. Для частей, предоставляющих nativeButton, устанавливайте nativeButton={false}, только если отрисованный элемент не является нативной кнопкой. Пользовательский компонент, который в итоге отрисовывает кнопку, например HelpButton, сохраняет поведение кнопки по умолчанию.