Offcanvas
Создавайте скрытые боковые панели в вашем проекте для навигации, корзин покупок и многого другого с помощью нескольких классов и нашего JavaScript плагина.
Как это работает
Offcanvas — это компонент боковой панели, который можно переключать с помощью JavaScript, чтобы он появлялся с левого, правого, верхнего или нижнего края области просмотра. Кнопки или ссылки используются в качестве триггеров, которые прикрепляются к конкретным элементам, которые вы переключаете, а атрибуты data используются для вызова нашего JavaScript.
- Offcanvas использует некоторый из того же JavaScript кода, что и модальные окна. Концептуально они довольно похожи, но это отдельные плагины.
- Аналогично, некоторые исходные Sass переменные для стилей и размеров offcanvas наследуются от переменных модального окна.
- При отображении offcanvas включает фон по умолчанию, на который можно нажать, чтобы скрыть offcanvas.
- Подобно модальным окнам, одновременно может отображаться только один offcanvas.
Внимание! Учитывая то, как CSS обрабатывает анимации, вы не можете использовать margin или translate для элемента .offcanvas. Вместо этого используйте класс как независимый оборачивающий элемент.
Анимационный эффект этого компонента зависит от медиа-запроса prefers-reduced-motion. См. раздел о сокращенном движении в нашей документации по доступности.
Примеры
Компоненты Offcanvas
Ниже приведен пример offcanvas, который отображается по умолчанию (через .show на .offcanvas). Offcanvas включает поддержку заголовка с кнопкой закрытия и дополнительный класс body для некоторого начального padding. Мы рекомендуем включать заголовки offcanvas с действиями закрытия, когда это возможно, или предоставлять явное действие закрытия.
Offcanvas
<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
</div>
</div> Живая демонстрация
Используйте кнопки ниже, чтобы показать и скрыть элемент offcanvas через JavaScript, который переключает класс .show на элементе с классом .offcanvas.
.offcanvasскрывает содержимое (по умолчанию).offcanvas.showпоказывает содержимое
Вы можете использовать ссылку с атрибутом href или кнопку с атрибутом data-bs-target. В обоих случаях требуется data-bs-toggle="offcanvas".
Offcanvas
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
Button with data-bs-target
</button>
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<div>
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
</div>
<div class="dropdown mt-3">
<button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
Dropdown button
</button>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Action</a></li>
<li><a class="dropdown-item" href="#">Another action</a></li>
<li><a class="dropdown-item" href="#">Something else here</a></li>
</ul>
</div>
</div>
</div> Прокрутка body
Прокрутка элемента <body> отключена, когда offcanvas и его фон видны. Используйте атрибут data-bs-scroll, чтобы включить прокрутку <body>.
Offcanvas with body scrolling
Try scrolling the rest of the page to see this option in action.
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>
<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<p>Try scrolling the rest of the page to see this option in action.</p>
</div>
</div> Прокрутка body и фон
Вы также можете включить прокрутку <body> с видимым фоном.
Backdrop with scrolling
Try scrolling the rest of the page to see this option in action.
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>
<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<p>Try scrolling the rest of the page to see this option in action.</p>
</div>
</div> Статический фон
Когда фон установлен как статический, offcanvas не будет закрываться при нажатии вне его.
Offcanvas
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
Toggle static offcanvas
</button>
<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<div>
I will not close if you click outside of me.
</div>
</div>
</div> Темный offcanvas
Устарело в v5.3.0 Добавлено в v5.2.0Измените внешний вид offcanvas с помощью утилит, чтобы лучше соответствовать различным контекстам, таким как темные навигационные панели. Здесь мы добавляем .text-bg-dark к .offcanvas и .btn-close-white к .btn-close для правильного стиля с темным offcanvas. Если у вас есть выпадающие списки внутри, рассмотрите также добавление .dropdown-menu-dark к .dropdown-menu.
Внимание! Темные варианты для компонентов были объявлены устаревшими в v5.3.0 с введением цветовых режимов. Вместо ручного добавления классов, упомянутых выше, установите data-bs-theme="dark" на корневом элементе, родительской обертке или самом компоненте.
Offcanvas
Place offcanvas content here.
<div class="offcanvas offcanvas-start show text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5>
<button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<p>Place offcanvas content here.</p>
</div>
</div> Адаптивность
Добавлено в v5.2.0Адаптивные классы offcanvas скрывают содержимое за пределами области просмотра от указанной контрольной точки и ниже. Выше этой контрольной точки содержимое внутри будет вести себя как обычно. Например, .offcanvas-lg скрывает содержимое в offcanvas ниже контрольной точки lg, но показывает содержимое выше контрольной точки lg. Адаптивные классы offcanvas доступны для каждой контрольной точки.
.offcanvas.offcanvas-sm.offcanvas-md.offcanvas-lg.offcanvas-xl.offcanvas-xxl
Чтобы сделать адаптивный offcanvas, замените базовый класс .offcanvas на адаптивный вариант и убедитесь, что ваша кнопка закрытия имеет явный data-bs-target.
Responsive offcanvas
This is content within an .offcanvas-lg.
<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button>
<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div>
<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p>
</div>
</div> Размещение
Для компонентов offcanvas нет размещения по умолчанию, поэтому вы должны добавить один из модификаторных классов ниже.
.offcanvas-startразмещает offcanvas слева от области просмотра (показано выше).offcanvas-endразмещает offcanvas справа от области просмотра.offcanvas-topразмещает offcanvas сверху области просмотра.offcanvas-bottomразмещает offcanvas снизу области просмотра
Попробуйте примеры сверху, справа и снизу ниже.
Offcanvas top
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button>
<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
...
</div>
</div> Offcanvas right
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>
<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
...
</div>
</div> Offcanvas bottom
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>
<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body small">
...
</div>
</div> Доступность
Поскольку панель offcanvas концептуально является модальным диалогом, обязательно добавьте aria-labelledby="..." — ссылающийся на заголовок offcanvas — к .offcanvas. Обратите внимание, что вам не нужно добавлять role="dialog", поскольку мы уже добавляем это через JavaScript.
CSS
Переменные
Добавлено в v5.2.0В рамках развивающегося подхода Bootstrap к CSS переменным, offcanvas теперь использует локальные CSS переменные на .offcanvas для улучшенной настройки в реальном времени. Значения для CSS переменных устанавливаются через Sass, поэтому настройка Sass также поддерживается.
--#{$prefix}offcanvas-zindex: #{$zindex-offcanvas};
--#{$prefix}offcanvas-width: #{$offcanvas-horizontal-width};
--#{$prefix}offcanvas-height: #{$offcanvas-vertical-height};
--#{$prefix}offcanvas-padding-x: #{$offcanvas-padding-x};
--#{$prefix}offcanvas-padding-y: #{$offcanvas-padding-y};
--#{$prefix}offcanvas-color: #{$offcanvas-color};
--#{$prefix}offcanvas-bg: #{$offcanvas-bg-color};
--#{$prefix}offcanvas-border-width: #{$offcanvas-border-width};
--#{$prefix}offcanvas-border-color: #{$offcanvas-border-color};
--#{$prefix}offcanvas-box-shadow: #{$offcanvas-box-shadow};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};
Sass переменные
$offcanvas-padding-y: $modal-inner-padding;
$offcanvas-padding-x: $modal-inner-padding;
$offcanvas-horizontal-width: 400px;
$offcanvas-vertical-height: 30vh;
$offcanvas-transition-duration: .3s;
$offcanvas-border-color: $modal-content-border-color;
$offcanvas-border-width: $modal-content-border-width;
$offcanvas-title-line-height: $modal-title-line-height;
$offcanvas-bg-color: var(--#{$prefix}body-bg);
$offcanvas-color: var(--#{$prefix}body-color);
$offcanvas-box-shadow: $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg: $modal-backdrop-bg;
$offcanvas-backdrop-opacity: $modal-backdrop-opacity;
Использование
Плагин offcanvas использует несколько классов и атрибутов для выполнения основной работы:
.offcanvasскрывает содержимое.offcanvas.showпоказывает содержимое.offcanvas-startскрывает offcanvas слева.offcanvas-endскрывает offcanvas справа.offcanvas-topскрывает offcanvas сверху.offcanvas-bottomскрывает offcanvas снизу
Добавьте кнопку закрытия с атрибутом data-bs-dismiss="offcanvas", который запускает функциональность JavaScript. Обязательно используйте с ней элемент <button> для правильного поведения на всех устройствах.
Через атрибуты data
Переключение
Добавьте data-bs-toggle="offcanvas" и data-bs-target или href к элементу, чтобы автоматически назначить управление одним элементом offcanvas. Атрибут data-bs-target принимает CSS селектор для применения offcanvas. Обязательно добавьте класс offcanvas к элементу offcanvas. Если вы хотите, чтобы он был открыт по умолчанию, добавьте дополнительный класс show.
Закрытие
Закрытие может быть достигнуто с помощью атрибута data-bs-dismiss на кнопке внутри offcanvas, как показано ниже:
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
или на кнопке вне offcanvas с использованием дополнительного data-bs-target, как показано ниже:
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button> Хотя оба способа закрытия offcanvas поддерживаются, имейте в виду, что закрытие извне offcanvas не соответствует шаблону диалога (модального окна) ARIA Authoring Practices Guide. Делайте это на свой страх и риск.
Через JavaScript
Включить вручную с помощью:
const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))
Опции
Поскольку опции могут передаваться через атрибуты данных или JavaScript, вы можете добавить имя опции к data-bs-, например, data-bs-animation="{value}". Обязательно изменяйте стиль написания имени опции с “camelCase” на “kebab-case” при передаче опций через атрибуты данных. Например, используйте data-bs-custom-class="beautifier" вместо data-bs-customClass="beautifier".
Начиная с Bootstrap 5.2.0, все компоненты поддерживают экспериментальный зарезервированный атрибут данных data-bs-config, который может содержать простую конфигурацию компонента в виде строки JSON. Когда элемент имеет атрибуты data-bs-config='{"delay":0, "title":123}' и data-bs-title="456", окончательное значение title будет 456, а отдельные атрибуты данных переопределяют значения, указанные в data-bs-config. Кроме того, существующие атрибуты данных могут содержать значения JSON, такие как data-bs-delay='{"show":0,"hide":150}'.
Окончательный объект конфигурации — это объединенный результат data-bs-config, data-bs- и js object, где последний заданный ключ-значение переопределяет другие.
| Название | Тип | По умолчанию | Описание |
|---|---|---|---|
backdrop | boolean или строка static | true | Применить фон к body, пока offcanvas открыт. Альтернативно, укажите static для фона, который не закрывает offcanvas при нажатии. |
keyboard | boolean | true | Закрывает offcanvas при нажатии клавиши escape. |
scroll | boolean | false | Разрешить прокрутку body, пока offcanvas открыт. |
Методы
Все API методы являются асинхронными и запускают переход. Они возвращаются к вызывающему коду сразу после начала перехода, но до его завершения. Кроме того, вызов метода на компоненте, который уже находится в процессе перехода, будет проигнорирован. Узнайте больше в нашей документации по JavaScript.
Активирует ваше содержимое как элемент offcanvas. Принимает необязательный object опций.
Вы можете создать экземпляр offcanvas с помощью конструктора, например:
const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
| Метод | Описание |
|---|---|
dispose | Уничтожает offcanvas элемента. |
getInstance | Статический метод, который позволяет получить экземпляр offcanvas, связанный с DOM элементом. |
getOrCreateInstance | Статический метод, который позволяет получить экземпляр offcanvas, связанный с DOM элементом, или создать новый в случае, если он не был инициализирован. |
hide | Скрывает элемент offcanvas. Возвращается к вызывающему до того, как элемент offcanvas фактически скрыт (т.е. до возникновения события hidden.bs.offcanvas). |
show | Показывает элемент offcanvas. Возвращается к вызывающему до того, как элемент offcanvas фактически показан (т.е. до возникновения события shown.bs.offcanvas). |
toggle | Переключает элемент offcanvas между показанным или скрытым. Возвращается к вызывающему до того, как элемент offcanvas фактически показан или скрыт (т.е. до возникновения события shown.bs.offcanvas или hidden.bs.offcanvas). |
События
Класс offcanvas Bootstrap предоставляет несколько событий для подключения к функциональности offcanvas.
| Тип события | Описание |
|---|---|
hide.bs.offcanvas | Это событие запускается немедленно, когда был вызван метод hide. |
hidden.bs.offcanvas | Это событие запускается, когда элемент offcanvas был скрыт от пользователя (будет ждать завершения CSS переходов). |
hidePrevented.bs.offcanvas | Это событие запускается, когда offcanvas показан, его фон является static и выполняется нажатие вне offcanvas. Событие также запускается, когда нажата клавиша escape и опция keyboard установлена в false. |
show.bs.offcanvas | Это событие запускается немедленно, когда вызывается метод экземпляра show. |
shown.bs.offcanvas | Это событие запускается, когда элемент offcanvas стал видимым для пользователя (будет ждать завершения CSS переходов). |
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
// do something...
})