Cмотреть на GitHub

Вне холста

Встраивайте в свой проект скрытые боковые навигационные панели, корзины для покупок и многое другое с помощью нескольких классов и нашего плагина JavaScript.

На этой странице

Как это работает

Offcanvas — это компонент боковой панели, который можно переключать с помощью JavaScript, чтобы он отображался слева, справа, сверху или снизу области просмотра. Кнопки или якоря используются в качестве триггеров, которые прикрепляются к определенным элементам, которые вы переключаете, а атрибуты data используются для вызова нашего JavaScript.

Offcanvas использует тот же код JavaScript, что и модальные окна. Концептуально они очень похожи, но представляют собой отдельные плагины.
Точно так же некоторые переменные источник Sass для стилей и размеров offcanvas наследуются от переменных модального окна.
При отображении offcanvas включает фон по умолчанию, на который можно щелкнуть, чтобы скрыть offcanvas.
Как и в модальных окнах, одновременно может отображаться только один неактивный холст.

Внимание! Учитывая, как CSS обрабатывает анимацию, Вы не можете использовать margin или translate в элементе .offcanvas. Вместо этого используйте класс как независимый элемент оболочки.

Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion. См. раздел с уменьшенным движением в нашей документации по специальным возможностям.

Примеры

Компоненты Offcanvas

Ниже приведен пример offcanvas, который отображается по умолчанию (через .show на .offcanvas). Offcanvas включает поддержку заголовка с кнопкой закрытия и дополнительный класс тела для некоторого начального заполнения. Мы рекомендуем по возможности включать заголовки offcanvas с действиями по отклонению или предоставлять явное действие по отклонению.

Здесь размещается контент для offcanvas. Вы можете разместить здесь практически любой компонент Bootstrap или пользовательские элементы.

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="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    Здесь размещается контент для offcanvas. Вы можете разместить здесь практически любой компонент Bootstrap или пользовательские элементы.
  </div>
</div>

Живая демонстрация

Используйте кнопки ниже, чтобы отображать и скрывать элемент offcanvas с помощью JavaScript, который переключает класс .show на элемент с классом .offcanvas.

.offcanvas скрывает содержимое (по умолчанию)
.offcanvas.show показывает содержимое

Вы можете использовать ссылку с атрибутом href или кнопку с атрибутом data-bs-target. В обоих случаях требуется data-bs-toggle="offcanvas".

Ссылка с помощью атрибута href

Какой-то текст в качестве заполнителя. В реальной жизни у вас могут быть элементы, которые Вы выбрали. Нравится, текст, изображения, списки и т. д.

html

<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Ссылка с помощью атрибута href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Кнопка с атрибутом 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="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Какой-то текст в качестве заполнителя. В реальной жизни у вас могут быть элементы, которые Вы выбрали. Нравится, текст, изображения, списки и т. д.
    </div>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown">
        Кнопка раскрывающегося списка
      </button>
      <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
        <li><a class="dropdown-item" href="#">Действие</a></li>
        <li><a class="dropdown-item" href="#">Другое действие</a></li>
        <li><a class="dropdown-item" href="#">Что-то еще здесь</a></li>
      </ul>
    </div>
  </div>
</div>

Темный offcanvas

Измените внешний вид offcanvases с помощью утилит, чтобы они лучше соответствовали различным контекстам, таким как темные панели навигации. Здесь мы добавляем .text-bg-dark к .offcanvas и .btn-close-white к .btn-close для правильной стилизации с темным offcanvas. Если у вас есть раскрывающиеся списки, рассмотрите возможность добавления .dropdown-menu-dark в .dropdown-menu.

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>

Прокрутка Body

Прокрутка элемента <body> отключена, когда видимы offcanvas и его фон. Используйте атрибут data-bs-scroll, чтобы включить прокрутку <body>.

Попробуйте прокрутить оставшуюся часть страницы, чтобы увидеть эту опцию в действии.

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Включить прокрутку тела</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 с прокруткой тела</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    <p>Попробуйте прокрутить оставшуюся часть страницы, чтобы увидеть эту опцию в действии.</p>
  </div>
</div>

Прокрутка тела и подложка

Вы также можете включить прокрутку <body> с видимым фоном.

Попробуйте прокрутить оставшуюся часть страницы, чтобы увидеть эту опцию в действии.

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Включить прокрутку и фон</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">Фон с прокруткой</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    <p>Попробуйте прокрутить оставшуюся часть страницы, чтобы увидеть эту опцию в действии.</p>
  </div>
</div>

Статический фон

Когда фон установлен на статический, offcanvas не будет закрываться при щелчке за его пределами.

Я не закроюсь, если вы нажмете вне меня.

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
  Переключить статический 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="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Я не закроюсь, если вы нажмете вне меня.
    </div>
  </div>
</div>

Отзывчивый

Добавлено в версии 5.2.0

Отзывчивые классы offcanvas скрывают содержимое за пределами области просмотра от указанной контрольной точке и ниже. Выше этой контрольной точки содержимое внутри будет вести себя как обычно. Например, .offcanvas-lg hides content in an offcanvas below the lg breakpoint, but shows the content above the lg breakpoint.

Измените размер окна браузера, чтобы отображался адаптивный переключатель offcanvas.

Это содержимое в .offcanvas-lg.

html

<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Переключатель offcanvas</button>

<div class="alert alert-info d-none d-lg-block">Измените размер окна браузера, чтобы отображался адаптивный переключатель offcanvas.</div>

<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Отзывчивый offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    <p class="mb-0">Это содержимое в <code>.offcanvas-lg</code>.</p>
  </div>
</div>

Отзывчивые классы offcanvas доступны для каждой контрольной точке.

.offcanvas
.offcanvas-sm
.offcanvas-md
.offcanvas-lg
.offcanvas-xl
.offcanvas-xxl

Размещение

Для компонентов вне холста нет размещения по умолчанию, поэтому вы должны добавить один из классов модификаторов ниже.

.offcanvas-start помещает offcanvas слева от области просмотра (показано выше)
.offcanvas-end помещает offcanvas в правую часть области просмотра
.offcanvas-top помещает offcanvas в верхнюю часть области просмотра
.offcanvas-bottom помещает offcanvas в нижнюю часть области просмотра

Попробуйте верхний, правый и нижний примеры ниже.

...

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Переключить верхнюю часть 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 вверху</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Переключатель справа 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 справа</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

html

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Переключатель снизу 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 внизу</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

Доступность

Так как панель offcanvas концептуально является модальным диалогом, не забудьте добавить aria-labelledby="..." — ссылку на заголовок offcanvas - в .offcanvas. Обратите внимание, что Вам не нужно добавлять role="dialog", поскольку мы уже добавляем его через JavaScript.

CSS

Переменные

Добавлено в версии 5.2.0

Как часть развивающегося подхода Bootstrap к переменным CSS, offcanvas теперь использует локальные переменные CSS в .offcanvas для расширенной настройки в реальном времени. Значения переменных CSS задаются через Sass, поэтому настройка Sass по-прежнему поддерживается.

  --#{$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};

Переменные 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:                $modal-content-bg;
$offcanvas-color:                   $modal-content-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-bs-toggle="offcanvas" и data-bs-target или href, чтобы автоматически назначить управление одним элементом offcanvas. Атрибут data-bs-target принимает CSS-селектор для применения offcanvas. Не забудьте добавить класс offcanvas к элементу offcanvas. Если вы хотите, чтобы он был открыт по умолчанию, добавьте дополнительный класс show.

Отклонение

Отклонение может быть достигнуто с помощью атрибута data на кнопке внутри offcanvas, как показано ниже:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Закрыть"></button>

или на кнопке за пределами offcanvas с помощью data-bs-target, как показано ниже:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Закрыть"></button>

Хотя поддерживаются оба способа отклонения модального окна, имейте в виду, что удаление модального окна извне не соответствует шаблону проектирования модального диалога WAI-ARIA. Делайте это на свой страх и риск.

Через JavaScript

Включить вручную с помощью:

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))

Опции

Параметры можно передавать через атрибуты данных или JavaScript. Для атрибутов данных добавьте имя параметра к data-bs-, как в data-bs-animation="". Не забудьте изменить тип регистра имени параметра с 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}'.

Название	Тип	По умолчанию	Описание
`backdrop`	boolean or the string `static`	`true`	Применить фон на тело, пока открыт offcanvas. В качестве альтернативы укажите `static` для подложки, которая не закрывает экран при нажатии.
`keyboard`	boolean	`true`	Закрывает offcanvas при нажатии клавиши выхода
`scroll`	boolean	`false`	Разрешает прокрутку тела, когда открыт offcanvas

Методы

Асинхронные методы и переходы

Все методы API асинхронны и запускают переход. Они возвращаются к вызывающей стороне, как только переход начинается, но до его завершения. Кроме того, вызов метода переходного компонента будет проигнорирован.

Дополнительную информацию см. в нашей документации по JavaScript.

Активирует Ваш контент как элемент offcanvas. Принимает необязательные параметры object.

Вы можете создать экземпляр offcanvas с помощью конструктора, например:

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')

Метод	Описание
`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`	Это событие запускается, когда элемент вне холста был скрыт от пользователя (будет ожидать завершения переходов 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 => {
  // сделайте что-нибудь...
})