Перейти к основному контенту Перейти к навигации документации
Просмотреть на GitHub

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
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
html 
<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".

Link with href
Offcanvas
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
html 
<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.

html 
<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.

html 
<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
I will not close if you click outside of me.
html 
<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.

html 
<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.

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas

This is content within an .offcanvas-lg.

html 
<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
...
html 
<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
...
html 
<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
...
html 
<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 также поддерживается.

scss/_offcanvas.scss 
--#{$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 переменные

scss/_variables.scss 
$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, где последний заданный ключ-значение переопределяет другие.

НазваниеТипПо умолчаниюОписание
backdropboolean или строка statictrueПрименить фон к body, пока offcanvas открыт. Альтернативно, укажите static для фона, который не закрывает offcanvas при нажатии.
keyboardbooleantrueЗакрывает offcanvas при нажатии клавиши escape.
scrollbooleanfalseРазрешить прокрутку 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...
})