VGSidebar

Боковая панель

API и события

Методы, отмена закрытия, очистка экземпляра и справочник.

Панели открываются поверх текущей страницы. Их разметка размещена в конце body, вне контейнеров с transform и overflow. Код каждого примера используется и в самой демонстрации. Кнопки и тема — OKAUX 1.0.2, поведение панелей — VGSidebar.

Параметры и Data API

backdrop / overflow / keyboard
По умолчанию true. Подложка, блокировка скролла страницы и закрытие по Escape соответственно. keyboard: false не запрещает dismiss и клик по фону.
hash
По умолчанию false. При открытии добавляет #id в историю. Начальное открытие по хэшу выполняется на DOMContentLoaded.
animation
enable: false, in: 'animate__rollIn', out: 'animate__rollOut', delay: 800. Для enable: true нужны CSS-классы анимации; delay управляет завершением закрытия.
ajax
route: '', target: '', method: 'get', loader: false, once: false, output: true. Поддержаны GET/POST/DELETE; data передаёт параметры, timeout откладывает запрос. Для POST требуется CSRF вашего приложения.
Приоритет
Параметры конструктора объединяются с data-атрибутами панели. show(relatedTarget) дополнительно читает data-атрибуты триггера. Поддерживаются data-params, JSON data-ajax и вложенные атрибуты вроде data-ajax-route.

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

getOrCreateInstance(element, params) / getInstance(element)
Повторно используйте существующий экземпляр. Передача params в getOrCreateInstance не перенастраивает уже созданный экземпляр.
show(relatedTarget) / hide() / toggle(relatedTarget)
Открытие, закрытие и переключение. show/shown получают event.relatedTarget. Методы не возвращают Promise: завершение отслеживается событиями.
dispose()
Освобождение экземпляра после закрытия. Сначала дождитесь vg.sidebar.hidden, затем dispose. Не используйте dispose вместо hide и не удаляйте экземпляр с незавершённым AJAX-запросом.
vg.sidebar.show / vg.sidebar.hide
Отменяемые события. event.preventDefault() блокирует изменение состояния панели, но не сетевой запрос, начатый перед show.
vg.sidebar.shown / vg.sidebar.hidden
Уведомления после открытия и закрытия. shown не означает завершение AJAX.
vg.sidebar.loaded
event.stats: 'success' или 'error'; event.data: транспортный ответ { code, response }. Для нашего JSON endpoint HTML находится в event.data.response.response. Поля находятся на событии, не в event.detail.
hidePrevented.vg.sidebar
Фактическое имя события при Escape и keyboard: false. Отмена hide через preventDefault сама по себе это событие не вызывает.
getOpenSidebars(excludeElement) / getBackdropElement()
Открытые DOM-панели и последняя подложка с владельцем sidebar. Несколько панелей могут делить одну подложку; это не стек модальных диалогов с отдельным фокусом.

CSS-переменные

--vg-sidebar-horizontal-width / -horizontal-height
По умолчанию 400px / 100vh для left и right. На ширине до 576px библиотека задаёт ширину 100%. В демо ширина ограничена min(26rem, 100vw), высота — 100dvh.
--vg-sidebar-vertical-width / -vertical-height
По умолчанию 100vw / 30vh для top и bottom. В демо высота min(24rem, 80dvh).
--vg-sidebar-header-height / -footer-height / -padding
По умолчанию 60px / 70px / 1rem. Высота body вычисляется из высот header и footer. Если footer отсутствует, задайте его высоту 0px.
--vg-sidebar-bg-color / -color / -border / -box-shadow
Фон, текст, разделители и тень. Используйте семантические токены темы вместо фиксированных цветов.
--vg-sidebar-z-index / -transition
Слой панели и переход положения. Подложка имеет собственный слой. Не помещайте панель внутрь нового stacking context.
Тема
Один источник — OKAUX data-theme / okaux.theme. Адаптер vgapp/theme уже подключён к этому селектору; демо не создаёт отдельный переключатель.

VGSidebar не реализует focus trap и возврат фокуса как полноценный modal-dialog. Примеры не объявляют aria-modal. Для модальных задач с требованиями управления фокусом оценивайте подходящий компонент отдельно.