> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Примитивы

> Базовые элементы управления для создания интерфейсов с Twenty UI.

## Обзор

Примитивы — это базовые элементы управления в Twenty UI. Они включают поля ввода, элементы отображения, навигацию и составные элементы управления, такие как Select, Popover и AlertDialog. Каждый примитив получает данные и функции обратного вызова из вашего приложения.

Импортируйте примитивы из точки входа семейства, например `twenty-ui/primitives/input`. Совокупная точка входа `twenty-ui/primitives` также экспортирует все семейства примитивов. Сведения об установке и настройке темы см. в разделе [Начало работы](https://docs.twenty.com/ru/ui/getting-started.md).

[Компоненты](https://docs.twenty.com/ru/ui/components/overview) объединяют эти примитивы в общие предустановки дизайна и многократно используемые строительные блоки приложений.

## Управление состоянием

Используйте неконтролируемое состояние, когда компонент может самостоятельно управлять своими взаимодействиями. Свойство по умолчанию задаёт начальное состояние. Используйте контролируемое состояние, когда приложению требуется согласовать это состояние с другими элементами управления, навигацией или данными приложения.

| Состояние | Неконтролируемое начальное состояние | Контролируемое состояние | Функция обратного вызова при изменении |
| - | - | - | - |
| Ввод, выбор или активная вкладка | `defaultValue` | `значение` | `onValueChange` |
| Флажок или переключатель | `defaultChecked` | `checked` | `onCheckedChange` |
| Видимость всплывающего окна | `defaultOpen` | `открыть` | `onOpenChange` |

В контролируемом режиме передайте текущее состояние и обновляйте его в функции обратного вызова при изменении. В неконтролируемом режиме вы всё равно можете отслеживать изменения, не беря на себя управление состоянием. Добавление одной лишь функции обратного вызова не делает компонент контролируемым.

Выберите режим для каждого состояния и сохраняйте его на протяжении всего жизненного цикла компонента. Свойства по умолчанию инициализируют состояние; их последующее изменение не заменяет текущее состояние. Не передавайте одновременно свойство по умолчанию и контролируемое свойство для одного и того же состояния.

Некоторые компоненты имеют более одного независимого состояния. Например, [Select](https://docs.twenty.com/ru/ui/primitives/input/select.md#open-state) может иметь контролируемое значение и неконтролируемую видимость всплывающего окна.

Состояние относится к части, которая управляет взаимодействием. Настраивайте выбор радиокнопки в [RadioGroup](https://docs.twenty.com/ru/ui/primitives/input/radio-group.md), а не в каждом Radio. Компоненты отображения, такие как Text, не имеют контролируемого или неконтролируемого режима. [Toast](https://docs.twenty.com/ru/ui/components/feedback/toast.md) делегирует управление своей видимостью и удалением приложению.

## Композиция

Составные примитивы предоставляют части, такие как `Select.Root`, `Select.Trigger` и `Select.Popup`. Держите связанные части под одним корневым элементом в дереве компонентов, чтобы они совместно использовали состояние и отношения доступности. Раздел анатомии каждого компонента определяет обязательные части и необязательное содержимое.

Слоты, такие как `InputGroup.startElement` и `ListItem.actions`, принимают узлы React в качестве свойств. Они добавляют содержимое в макет компонента. Части и слоты — это разные API; используйте имена, указанные в руководстве по компоненту.

### Композиция всплывающего окна

Select, Popover и Autocomplete предоставляют отдельные части `Portal`, `Positioner` и `Popup`:

| Часть | Назначение |
| - | - |
| `Portal` | Целевой контейнер и монтирование |
| `Positioner` | Размещение, якорь, смещения и обработка коллизий |
| `Popup` | Содержимое, поведение фокуса, нативные атрибуты и ref |
| `Arrow` | Необязательная стрелка внутри всплывающего окна |

Размещайте Popup внутри Positioner, а Positioner — внутри Portal. Размещайте содержимое внутри Popup и при необходимости явно добавляйте Arrow. Портал может перемещать отрисованный DOM в другой контейнер, сохраняя иерархию компонентов и контекст. См. [темизацию](https://docs.twenty.com/ru/ui/theming.md#scope-an-override) для получения сведений об ограниченных контейнерах портала.

Каждая отрисованная часть сохраняет собственные нативные атрибуты, цель ref и композицию рендеринга. [Autocomplete](https://docs.twenty.com/ru/ui/primitives/input/autocomplete) также сохраняет установленные вышестоящие части коллекции, группировки, сетки, фильтрации и статуса.

[Dialog](https://docs.twenty.com/ru/ui/primitives/surfaces/dialog.md) и [AlertDialog](https://docs.twenty.com/ru/ui/primitives/surfaces/alert-dialog.md) предоставляют отдельные части `Portal`, `Backdrop`, `Viewport` и `Popup`. Настройте монтирование и назначение в Portal, внешний вид наложения в Backdrop и Viewport, а также размер содержимого и фокус в Popup. Каждая часть сохраняет собственные нативные атрибуты, цель ref и композицию рендеринга. Эти API диалогов предназначены для автономного UI и хоста Twenty. Компоненты Front используют [API диалогов хоста SDK](https://docs.twenty.com/ru/developers/extend/apps/layout/front-components.md#host-communication-api).

### Пользовательские компоненты

Для частей, поддерживающих `render`, передайте совместимый элемент или компонент, чтобы заменить элемент по умолчанию. Например, `Popover.Trigger` может использовать `Button` из Twenty UI, сохраняя поведение триггера.

Пользовательская обёртка должна передавать предоставленные props и ref интерактивному элементу. Это сохраняет обработчики событий, атрибуты доступности, позиционирование и восстановление фокуса. В этом примере они передаются через `Button`, который прикрепляет их к своей нативной кнопке.

```tsx theme={null}
import { type ComponentPropsWithRef } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Popover } from 'twenty-ui/primitives/surfaces';

type HelpButtonProps = ComponentPropsWithRef<typeof Button>;

const HelpButton = ({ ref, ...props }: HelpButtonProps) => (
  <Button {...props} ref={ref} variant="outline" />
);

export const ImportHelp = () => (
  <Popover.Root>
    <Popover.Trigger render={<HelpButton>Import help</HelpButton>} />
    <Popover.Portal>
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Import a CSV file</Popover.Title>
          <Popover.Description>
            Use a header row to identify your columns.
          </Popover.Description>
          <Popover.Close render={<Button>Got it</Button>} />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Portal>
  </Popover.Root>
);
```

Передайте кнопку через `render` и сохраняйте каждое действие как отдельный интерактивный элемент управления. При добавлении собственного поведения сохраняйте обработчики и ref, предоставленные вашей обёртке. Ref должен достигать элемента, получающего фокус.

Используйте нативную кнопку для частей, подобных кнопке. Для частей, предоставляющих `nativeButton`, устанавливайте `nativeButton={false}`, только если отрисованный элемент не является нативной кнопкой. Пользовательский компонент, который в итоге отрисовывает кнопку, например `HelpButton`, сохраняет поведение кнопки по умолчанию.

## Просмотр примитивов

Каждая страница содержит примеры использования, рекомендации по взаимодействию и сгенерированную справку по API.

| Семейство | Примитивы |
| - | - |
| Доступность | [Визуально скрытый](https://docs.twenty.com/ru/ui/primitives/accessibility/visually-hidden.md) |
| Отображение данных | [Аватар](https://docs.twenty.com/ru/ui/primitives/data-display/avatar.md), [Чип](https://docs.twenty.com/ru/ui/primitives/data-display/chip.md), [Образец цвета](https://docs.twenty.com/ru/ui/primitives/data-display/color-sample.md), [Бейдж](https://docs.twenty.com/ru/ui/primitives/data-display/badge.md), [Статус](https://docs.twenty.com/ru/ui/primitives/data-display/status.md), [Тег](https://docs.twenty.com/ru/ui/primitives/data-display/tag.md) |
| Обратная связь | [Banner](https://docs.twenty.com/ru/ui/primitives/feedback/banner.md), [Loader](https://docs.twenty.com/ru/ui/primitives/feedback/loader.md), [Progress](https://docs.twenty.com/ru/ui/primitives/feedback/progress.md), [ProgressBar](https://docs.twenty.com/ru/ui/primitives/feedback/progress-bar.md), [ProgressRing](https://docs.twenty.com/ru/ui/primitives/feedback/progress-ring.md), [Skeleton](https://docs.twenty.com/ru/ui/primitives/feedback/skeleton.md) |
| Формы | [Автозаполнение](https://docs.twenty.com/ru/ui/primitives/input/autocomplete), [Кнопка](https://docs.twenty.com/ru/ui/primitives/input/button.md), [Группа кнопок](https://docs.twenty.com/ru/ui/primitives/input/button-group.md), [Флажок](https://docs.twenty.com/ru/ui/primitives/input/checkbox.md), [Поле](https://docs.twenty.com/ru/ui/primitives/input/field.md), [Ввод](https://docs.twenty.com/ru/ui/primitives/input/input.md), [Группа ввода](https://docs.twenty.com/ru/ui/primitives/input/input-group.md), [Числовое поле](https://docs.twenty.com/ru/ui/primitives/input/number-field.md), [Переключатель](https://docs.twenty.com/ru/ui/primitives/input/radio.md), [Группа переключателей](https://docs.twenty.com/ru/ui/primitives/input/radio-group.md), [Выбор](https://docs.twenty.com/ru/ui/primitives/input/select.md), [Ползунок](https://docs.twenty.com/ru/ui/primitives/input/slider.md), [Переключатель](https://docs.twenty.com/ru/ui/primitives/input/switch.md), [Текстовая область](https://docs.twenty.com/ru/ui/primitives/input/textarea.md) |
| Макет | [Сворачиваемый элемент](https://docs.twenty.com/ru/ui/primitives/layout/collapsible.md), [Разделитель](https://docs.twenty.com/ru/ui/primitives/layout/separator.md), [Маркер изменения размера](https://docs.twenty.com/ru/ui/primitives/layout/resize-handle.md), [Поставщик направления](https://docs.twenty.com/ru/ui/primitives/layout/direction-provider.md) |
| Навигация | [Навигационная цепочка](https://docs.twenty.com/ru/ui/primitives/navigation/breadcrumb.md), [Элемент списка](https://docs.twenty.com/ru/ui/primitives/navigation/list-item.md), [Вкладки](https://docs.twenty.com/ru/ui/primitives/navigation/tabs.md) |
| Области отображения | [Диалог предупреждения](https://docs.twenty.com/ru/ui/primitives/surfaces/alert-dialog.md), [Карточка](https://docs.twenty.com/ru/ui/primitives/surfaces/card.md), [Диалог](https://docs.twenty.com/ru/ui/primitives/surfaces/dialog.md), [Всплывающее окно](https://docs.twenty.com/ru/ui/primitives/surfaces/popover.md), [Подсказка](https://docs.twenty.com/ru/ui/primitives/surfaces/tooltip.md) |
| Типографика | [Заголовок](https://docs.twenty.com/ru/ui/primitives/typography/heading.md), [Переполняющий текст с подсказкой](https://docs.twenty.com/ru/ui/primitives/typography/overflowing-text-with-tooltip.md), [Поставщик режима подсказки для переполняющего текста](https://docs.twenty.com/ru/ui/primitives/typography/overflowing-text-tooltip-mode-provider), [Сочетание клавиш](https://docs.twenty.com/ru/ui/primitives/typography/shortcut.md), [Текст](https://docs.twenty.com/ru/ui/primitives/typography/text.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.