# Sheet ## Кратко `Sheet` (шторка) — [составной компонент](https://vega-ui.dev/ru/docs/glossary/#составной-компонент-compound-component) для оверлеев в виде панели, обычно прикреплённых к низу экрана или рассчитанных в первую очередь на мобильные устройства, с частями для триггера, содержимого и ручки. `SheetClose` превращает вашу собственную кнопку в кнопку закрытия; заголовки и раскладка — обычная разметка, которую вы собираете сами. `SheetContent` рендерит нативный ``, открытый через `showModal()`, поэтому браузер помещает его в верхний слой (top layer), делает остальную страницу инертной и рисует подложку. Это оверлей семейства, ориентированный на касания и панели, особенно когда важны точки привязки (snap points) или появление снизу. ## Импорт ```tsx import { Sheet, SheetTrigger, SheetContent, SheetClose, SheetHandle, type SheetProps, } from '@vega-ui/react'; ``` ## Экспортируемые типы - `SheetProps` - `SheetTriggerProps` - `SheetHandleProps` - `SheetContentProps` - `SheetCloseProps` ## Минимальная композиция ```tsx import { useId, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function MinimalComposition() { const titleId = useId(); return (
Order summary
2 × Flat white, 1 × Almond croissant · $13.40
); } ``` ## Обязательные части - `Sheet`: корневое состояние и провайдер контекста - `SheetTrigger`: поверхность действия открытия - `SheetContent`: поверхность модальной шторки ## Необязательные части - `SheetHandle`: элемент для перетаскивания и жестов - `SheetClose`: закрывает шторку по клику; оборачивает вашу собственную кнопку через `asChild` ## Ваша собственная разметка - заголовок, `id` которого передаётся в `SheetContent` как `aria-labelledby` (или `aria-label` на `SheetContent`); у шторки обязательно должно быть имя - кнопки, которые отвечают на шторку, внутри `
` - прокручиваемая область: элемент с `overflow: auto` ## Порядок композиции 1. `Sheet` 2. `SheetTrigger` 3. `SheetContent` 4. `SheetHandle` 5. Ваш заголовок, необязательный `SheetClose` и тело ## Варианты - Раскладки нижней шторки и обычные раскладки панели - Открытие через триггер и [контролируемое](https://vega-ui.dev/ru/docs/glossary/#контролируемый-controlled) состояние открытия - Шторки с точками привязки и полностью открытые шторки - `closedBy` на `SheetContent`: закрывается любым действием, только по `Escape` или вовсе не закрывается пользователем - Затемнённая или прозрачная подложка (`overlay` на `SheetContent`); шторка в любом случае остаётся модальной - Подача с приоритетом мобильных устройств и использование панели на разных устройствах ## Миграция с 2.x `SheetHeader` и `SheetMain` удалены: библиотека оставляет только части с поведением, которое нельзя выразить обычной разметкой. Отступы, которые они давали, теперь есть у `SheetContent`. - `SheetHeader` → `Heading` с `id`, на который ссылается `aria-labelledby` на `SheetContent` - `SheetMain` → обычное содержимое или элемент с `overflow: auto` для прокручиваемой области - Новое: `SheetClose` — часть закрытия без собственных стилей (раньше у Sheet не было кнопки закрытия) - `useSheetContext()` больше не возвращает `contentId`, а `SheetTrigger` больше не выставляет `aria-controls` ## Пограничные случаи - Проверяйте жесты на сенсорных устройствах. - Точки привязки нужно проверять на реальной высоте содержимого. - Вложенным оверлеям нужны проверки восстановления фокуса и наложения. - Незакрываемым шторкам нужны особенно понятные пути выхода. ## Частые ошибки - `SheetContent` без `aria-labelledby` или `aria-label`. - Обращение со шторкой как с модальным диалогом для десктопа. - Точки привязки без проверки удобства содержимого на каждой остановке. - Жесты, фокус и закрытие не проверены вместе. ## Примеры ### Базовый #### Базовый: шторка «Поделиться» с заголовком и кнопкой закрытия Шторка подстраивается под содержимое и закрывается круглой кнопкой, свайпом вниз, кликом по подложке или `Escape`. Заголовок даёт ей имя через `aria-labelledby`, адрес описывает её через `aria-describedby`, а результат копирования объявляется строкой с `role="status"`. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { CopyIcon, MailIcon, MessageCircleIcon, XIcon } from '@vega-ui/icons'; const link = 'https://maps.example.com/p/blue-harbor-cafe'; export default function SheetWithHeadingAndCloseButton() { const titleId = useId(); const descriptionId = useId(); const [copied, setCopied] = useState(false); const copy = async () => { await navigator.clipboard.writeText(link); setCopied(true); }; return ( setCopied(false)}>
Share Blue Harbor Cafe
12 Quay Street · Open until 22:00 {copied ? 'The link is on your clipboard.' : ''} ); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: точка привязки в вашем состоянии С `activeSnapPoint` и `onChangeActiveSnapPoint` точка привязки живёт в вашем состоянии, поэтому кнопки «Peek», «Half» и «Full» двигают шторку, а перетаскивание обновляет нажатую кнопку. `height: 100%` делает шторку высотой с окно, чтобы работали все три точки. ```tsx import { useId, useState } from 'react'; import { Button, Heading, Sheet, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; const snapPoints: Array<`${number}px` | number> = ['180px', 0.5, 1]; const snapLabels = ['Peek', 'Half', 'Full']; const stops = ['Central Station', 'Market Square', 'Harbour Bridge', 'Old Town', 'University', 'Science Park', 'Airport']; export default function ControlledSnapPoint() { const titleId = useId(); const [snapPoint, setSnapPoint] = useState(0); return ( setSnapPoint(0)}> Bus 42 · next in 4 min
{snapLabels.map((label, index) => ( ))}
    {stops.map((stop, index) => (
  1. {stop} {4 + index * 3} min
    2. ))}
); } ``` #### Контролируемый/с состоянием: выбор, который закрывает шторку `open` шторки контролируемый, поэтому выбор слота доставки в одном обработчике сохраняет его и закрывает шторку. Триггер показывает текущий выбор, а внутри шторки его отмечает `aria-pressed`. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Heading, Icon, IconButton, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const slots = [ { id: 'asap', label: 'As soon as possible', detail: '25–35 min · $2.99' }, { id: '1830', label: 'Today, 18:30–19:00', detail: '$1.99' }, { id: '1900', label: 'Today, 19:00–19:30', detail: '$1.99' }, { id: '1930', label: 'Today, 19:30–20:00', detail: 'Free' }, ]; export default function MobileLikePickerSurface() { const titleId = useId(); const [open, setOpen] = useState(false); const [slot, setSlot] = useState(slots[0]); const choose = (next: typeof slots[number]) => { setSlot(next); setOpen(false); }; return (
Delivery time
{slots.map((item) => ( ))}
); } ``` ### Форма/интеграция #### Форма/интеграция: форма отзыва `` с числовым полем, ограниченным `min`, `max` и `step`, и необязательной заметкой. Браузер проверяет чаевые, валидная отправка читается через `FormData` и закрывает шторку; на телефоне шторка поднимается над экранной клавиатурой. ```tsx import { useId, useState, type CSSProperties, type FormEvent } from 'react'; import { Button, Heading, Icon, IconButton, Label, Sheet, SheetClose, SheetContent, SheetHandle, SheetTrigger, Text, TextArea, TextField, TextFieldInput, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function SheetWithFormContent() { const titleId = useId(); const tipId = useId(); const noteId = useId(); const [summary, setSummary] = useState(''); const onSubmit = (event: FormEvent) => { const data = new FormData(event.currentTarget); const note = String(data.get('note')).trim(); setSummary(`Tip $${data.get('tip')}${note ? ` · “${note}”` : ''}`); }; return (
How was your delivery?