Drawer

<sf-drawer> — боковая панель рабочего места, рядом с которой страница остаётся доступной: подсказка у формы, библиотека блоков и свойства в редакторе страниц. Закреплённая панель (docked) становится колонкой и сдвигает страницу, немодальная (modal="false") ложится поверх без затемнения. Модальную боковую панель — с затемнением и удержанием фокуса — делает модальное окно с position="inline-start" или position="inline-end".

Пример

HTML

<div data-sf-overlay-container>
  <div class="flex flex-col gap-2 p-3 radius-3 bg-surface-container">
    <div class="flex flex-wrap gap-2">
      <button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1" data-drawer="toggle" aria-controls="drawer-example-help">
        <span class="sf-button-text-container">Подсказка</span>
      </button>
    </div>
    <label class="sf-input sf-input--size-1 sf-input--bordered flex flex-col">
      <span class="sf-input-label flex"><span class="sf-input-text">Название страницы</span></span>
      <span class="sf-input-field items-cross-center transition flex">
        <input type="text" name="title" value="Весенняя распродажа">
      </span>
    </label>
    <p class="m-0">Откройте подсказку и продолжайте печатать: панель ложится поверх, но без затемнения, и поле остаётся доступным.</p>
  </div>
  <sf-drawer id="drawer-example-help" modal="false" placement="inline-end" size="1/2" title="Подсказка">
    <p class="m-0">Название показывается во вкладке браузера и в результатах поиска.</p>
  </sf-drawer>
</div>

CSS

/* Пример держит свои панели: они открываются внутри этого блока
   (data-sf-overlay-container) на его высоту. */
[data-sf-overlay-container] {
  min-block-size: 24rem;
}

Применение

Открытие и закрытие

Кнопка открывает панель без своего кода: data-drawer="toggle", open или close и aria-controls с id панели. open на <sf-drawer> показывает панель сразу. Кнопку закрытия в шапке панель рисует сама: show-close="false" убирает её, close-placement="outside" ставит снаружи у края, close-label меняет её имя. close-on-esc и close-on-overlay управляют закрытием по Escape и по затемнению.

Модальный режим по умолчанию оставлен только для совместимости и помечен устаревшим. Новой панели всегда задавайте modal="false" или docked.

Закреплённая панель

docked превращает панель в колонку role="region" рядом со страницей: без затемнения, блокировки прокрутки и удержания фокуса. Контейнер страницы помечается data-sf-drawer-dock-host; Framework задаёт ему отступы по сумме ширин открытых закреплённых панелей слева и справа, обе стороны одновременно.

HTML

<div data-sf-overlay-container>
  <div class="flex flex-col gap-2 p-3 radius-3 bg-surface-container" data-sf-drawer-dock-host>
    <div class="flex flex-wrap gap-2">
      <button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1" data-drawer="toggle" aria-controls="drawer-example-blocks">
        <span class="sf-button-text-container">Блоки</span>
      </button>
      <button type="button" class="sf-button sf-button--default sf-button--primary sf-button--size-1" data-drawer="toggle" aria-controls="drawer-example-properties">
        <span class="sf-button-text-container">Свойства</span>
      </button>
    </div>
    <h3 class="m-0">Страница в редакторе</h3>
    <p class="m-0">Откройте обе панели. На широком экране страница сдвигается и остаётся видна целиком; на узком панель ложится поверх.</p>
    <p class="m-0">Затемнения нет, фокус не удерживается: страницей можно пользоваться, пока панели открыты.</p>
    <p class="m-0">Чтобы увидеть сдвиг страницы, откройте пример на весь экран.</p>
  </div>
  <sf-drawer id="drawer-example-blocks" docked placement="inline-start" size="1/2" title="Блоки">
    <p class="m-0">Библиотека блоков.</p>
  </sf-drawer>
  <sf-drawer id="drawer-example-properties" docked placement="inline-end" size="1/2" title="Свойства">
    <p class="m-0">Свойства выбранного блока.</p>
  </sf-drawer>
</div>

CSS

/* Пример держит свои панели: они открываются внутри этого блока
   (data-sf-overlay-container) на его высоту. */
[data-sf-overlay-container] {
  min-block-size: 24rem;
}

Отдавать ли место странице, решает ширина хоста data-sf-drawer-dock-host: при 48rem и шире закреплённая панель сдвигает страницу, уже — ложится поверх. Компонент следит за шириной хоста и пересчитывает это при её изменении; если хоста на странице нет, решает ширина окна. Хост в примере уже 48rem, поэтому панели ложатся поверх; чтобы увидеть, как страница сдвигается, откройте проверку адаптивности примера на ширине Desktop.

Ширины открытых панелей публикуются как --sf-drawer-dock-inline-start и --sf-drawer-dock-inline-end, высоту шапки над панелями задаёт --sf-drawer-dock-block-start.

Сторона и размер

placement — inline-start или inline-end; сторона отражается при письме справа налево. size берёт ступень общей шкалы 1/2, 1, 2 или full — во всю ширину. width задаёт точную ширину, если ступеней мало, z-index — слой.

Стопка панелей

Если у одного края открыто несколько панелей, по умолчанию они лежат вплотную и верхняя закрывает нижнюю. Атрибут stack-offset задаёт, насколько каждая нижняя панель выглядывает: верхняя отступает от края на глубину стопки, умноженную на stack-offset, и сохраняет свою ширину. Глубину панель считает сама по открытым незакреплённым панелям у того же края. Задайте одно значение на всех панелях стопки, например stack-offset="var(--sf-space-4)".

Отступ шапки и содержимого

Заголовок и содержимое панели стоят на одной вертикальной оси: у шапки и тела один внутренний отступ. Чтобы сделать его шире, задайте атрибут gutter, например gutter="var(--sf-space-3)", или переменную --sf-drawer-gutter в теме. Не добавляйте собственный отступ внутри тела: заголовок останется на прежней оси, и части разъедутся. Классы частей задают overlay-class, panel-class, header-class, body-class и close-class, переменные самой панели — panel-style.

Панель внутри блока

Обычно панель выводится в конце body и стоит над всей страницей. Если <sf-drawer> находится внутри элемента с атрибутом data-sf-overlay-container, панель выводится внутри этого элемента и встаёт по его границам: элемент получает contain: layout, а высота панели — его высота. Модальная панель внутри такого блока не блокирует прокрутку страницы. Так область редактора или пример документации держат свой Drawer, не открывая его поверх всей страницы; оба примера на этой странице устроены так. Тот же атрибут держит внутри блока и модальное окно. Прежнее имя атрибута data-sf-drawer-container читается для совместимости до 2026-12-01 (запись журнала attribute-overlay-container).

HTML

<div data-sf-overlay-container class="h-e6">
  <sf-drawer id="preview" open modal="false" title="Подсказка">…</sf-drawer>
</div>

Высоту блока задаёт страница: панель занимает ровно её.

Методы и события

open(), close(), toggle(), getState() и setState(state) управляют тем же экземпляром. События drawer:before-open и drawer:before-close можно отменить; drawer:after-open и drawer:after-close приходят после завершённого перехода, drawer:ready и drawer:update — после отрисовки.

События drawer:* всплывают до document, как остальные события sf-*. Панель, которая их отправила, указана в event.detail.drawer. Помощники onBeforeOpen(), onAfterOpen(), onBeforeClose() и onAfterClose() получают только события своей панели; обычный слушатель на внешней панели услышит и вложенную, поэтому проверяйте event.detail.drawer.

JavaScript

const drawer = document.querySelector('#drawer-example-help');

drawer.onBeforeClose((event) => {
  if (hasUnsavedChanges()) event.preventDefault();
});

document.addEventListener('drawer:after-open', (event) => {
  analytics.track('panel-open', event.detail.drawer.id);
});

Доступность

Панели нужно доступное имя: title становится видимым заголовком и именем, label задаёт имя без заголовка.
Немодальная и закреплённая панели не удерживают фокус и не блокируют страницу: Tab проходит из панели на страницу и обратно. При открытии фокус остаётся на кнопке; после закрытия возвращается туда, где был до открытия.
Escape закрывает верхнюю панель, но не перехватывает Escape, который уже обработал редактор или перетаскивание. Пока внутри открыта всплывающая панель (sf-popover), Escape закрывает сначала её.
Кнопка закрытия на русской странице называется «Закрыть панель».
Положение учитывает направление текста, анимация отключается при prefers-reduced-motion.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.


Тег	`<sf-drawer>`
Назначение	Боковая панель рабочей области, при которой страница остаётся доступной: закреплённая колонка или немодальная панель. Модальные боковые панели относятся к sf-modal; модальный режим Drawer устарел.
Контракт	`smart.drawer`, версия `1.3.0`
Поставка	выпуск Framework `ui-106d5901f8c3`
Жизненный цикл	экспериментальный: API может меняться между выпусками
Готовность	принят в продукт
Заготовка до прихода кода	нет: атрибут `data-sf-skeleton` не пишется; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

template — string, по умолчанию default.
open — boolean, по умолчанию false.
placement — string, по умолчанию right, значения: left, right, inline-start, inline-end.
overlay — boolean, по умолчанию true.
modal — boolean, по умолчанию true.
docked — boolean, по умолчанию false.
size — string, по умолчанию 1, значения: 1/2, 1, 2, full.
close-on-esc — boolean, по умолчанию true.
close-on-overlay — boolean, по умолчанию true.
preserve-scroll-gap — boolean, по умолчанию true.
show-close — boolean, по умолчанию true.
close-placement — string, по умолчанию inside, значения: inside, outside.
title — string, по умолчанию пусто.
label — string, по умолчанию пусто.
close-label — string, по умолчанию пусто. Пусто — текст на языке страницы (по-английски «Close drawer»).
width — string, по умолчанию пусто.
stack-offset — string, по умолчанию пусто. Насколько каждая нижняя панель выступает из-под верхней у того же края, в виде длины (например, var(--sf-space-4)). Панель отстоит от своего края на глубину × смещение, где глубина — число открытых незакреплённых панелей под ней у этого края. Пустое значение: панели лежат вровень.
gutter — string, по умолчанию пусто. Общий горизонтальный отступ шапки и тела в виде длины (например, var(–sf-space-3)), чтобы заголовок и содержимое начинались на одной оси. Пусто — собственный отступ drawer, space-1. Тема может задать –sf-drawer-gutter.
z-index — string, по умолчанию пусто.
overlay-class — string, по умолчанию пусто.
panel-class — string, по умолчанию пусто.
panel-style — string, по умолчанию пусто. Объявления, задаваемые на самой панели, для читаемых ею пользовательских свойств — фона, радиуса, тени. Если потребитель окрашивает содержимое в цвет, отличный от панели, заголовок и поля остаются другого цвета.
header-class — string, по умолчанию пусто.
body-class — string, по умолчанию пусто.
close-class — string, по умолчанию пусто.

Прежние имена:

Имя	Прежнее имя	Состояние	Убирается после
`size="1/2"`	`size="small"`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="1"`	`size="medium"`	работает, отмечается в `SF.deprecations`	2026-12-01
`size="2"`	`size="large"`	работает, отмечается в `SF.deprecations`	2026-12-01
`placement="inline-start"`	`placement="left"`	работает, отмечается в `SF.deprecations`	2026-12-01
`placement="inline-end"`	`placement="right"`	работает, отмечается в `SF.deprecations`	2026-12-01

Методы

open(options?: object) — возвращает object. Открывает Drawer или выводит его на передний план, если он уже открыт. Отправляет drawer:before-open (отменяемое) и затем drawer:after-open, если options.emit не равно false. Возвращает элемент.
close(options?: object) — возвращает object. Закрывает Drawer и возвращает фокус элементу, который его открыл. Отправляет drawer:before-close (отменяемое) и drawer:after-close, если options.emit не равно false. Возвращает элемент.
toggle() — возвращает object. Вызывает close(), если открыто, иначе open(). Возвращает элемент.
setState(state?: object) — возвращает object. Ключ open вызывает open() или close(); остальные ключи передаются в базовый setState как атрибуты хост-элемента. Возвращает элемент.
getState() — возвращает object. Возвращает текущий контекст шаблона вместе с состоянием открытия.
onBeforeOpen(handler: function, options?: object|boolean) — возвращает object. Добавляет на хост-элементе обработчик drawer:before-open, который срабатывает только на собственные события этого Drawer. Возвращает элемент.
onAfterOpen(handler: function, options?: object|boolean) — возвращает object. Добавляет на хост-элементе обработчик drawer:after-open, который срабатывает только на собственные события этого Drawer. Возвращает элемент.
onBeforeClose(handler: function, options?: object|boolean) — возвращает object. Добавляет на хост-элементе обработчик drawer:before-close, который срабатывает только на собственные события этого Drawer. Возвращает элемент.
onAfterClose(handler: function, options?: object|boolean) — возвращает object. Добавляет на хост-элементе обработчик drawer:after-close, который срабатывает только на собственные события этого Drawer. Возвращает элемент.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

drawer:ready — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Поверхность портала готова. Всплывает и является composed; detail.drawer — drawer, отправивший событие.
drawer:update — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Поверхность портала обновлена. Всплывает и является composed; detail.drawer — drawer, отправивший событие.
drawer:before-open — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Отменяемое намерение перед открытием. Всплывает и является composed; detail.drawer — панель, отправившая событие.
drawer:after-open — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Drawer открыт. Всплывает и является composed; detail.drawer — drawer, отправивший событие.
drawer:before-close — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Отменяемое намерение перед закрытием. Всплывает и является composed; detail.drawer — панель, отправившая событие.
drawer:after-close — detail: { component?: any, drawer?: any, drawerId?: string, root?: any }. Drawer закрыт. Всплывает и является composed; detail.drawer — drawer, отправивший событие.

Доступность

Роль: диалог (dialog).
Доступное имя: обязательно.
Клавиши: Tab, Shift+Tab, Escape.
Фокус: Модальная панель Drawer переносит фокус внутрь, удерживает Tab в верхнем экземпляре и возвращает фокус на доступный открывший элемент. Немодальная панель Drawer не удерживает фокус и не блокирует страницу. Закреплённая панель Drawer — именованный столбец с role=region: без ловушки фокуса и блокировки прокрутки; Escape закрывает верхний экземпляр.

Минимальная разметка

HTML

<div data-sf-drawer-dock-host>…</div><sf-drawer id="blocks" docked open placement="inline-start" size="1/2" title="Blocks"><p>Content</p></sf-drawer>

Источник

simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/drawer
simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-drawer

См. также

Модальное окно — модальная боковая панель и диалог.
Popover — небольшая панель у кнопки.

Навигация

Главное

Документация

Содержание

Drawer

Пример

Применение

Открытие и закрытие

Закреплённая панель

Сторона и размер

Стопка панелей

Отступ шапки и содержимого

Панель внутри блока

Методы и события

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Настройки

Drawer

Пример

Применение

Открытие и закрытие

Закреплённая панель

Сторона и размер

Стопка панелей

Отступ шапки и содержимого

Панель внутри блока

Методы и события

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Поиск по документации