View on GitHub

滑动导航（Offcanvas）

只需几个类和我们的 JavaScript 插件，就能在项目中为导航、购物车等设置隐藏侧边栏。

On this page

工作原理

Offcanvas 是一个侧边栏组件，可以通过 JavaScript 进行切换，从视窗的左、右、上或下边缘显示。按钮或锚点可用作触发器，与您切换的特定元素相连，而 data 属性可用于调用我们的 JavaScript。

Offcanvas 与模态共享一些相同的 JavaScript 代码。从概念上讲，它们非常相似，但它们是独立的插件。
同样，用于 offcanvas 样式和尺寸的一些 source Sass 变量也继承自模式变量。
显示时，offcanvas 包含一个默认背景，点击该背景可隐藏 offcanvas。
与模态类似，一次只能显示一个 offcanvas。

注意！ 考虑到 CSS 处理动画的方式，您不能在 .offcanvas 元素上使用 margin 或 translate。相反，请将该类用作独立的包装元素。

该组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们的可访问性文档中的缩减动作部分.

示例

侧边栏组件

下面是一个默认显示的 offcanvas 示例（通过 .offcanvas 上的 .show）。Offcanvas 支持带有关闭按钮的页眉和可选的 body 类，可用于一些初始 padding。我们建议您尽可能在 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>

在线演示

使用下面的按钮，通过 JavaScript 在带有 .offcanvas 类的元素上切换 .show 类来显示和隐藏侧边栏元素。

.offcanvas 隐藏内容 (默认)
.offcanvas.show 显示内容

您可以使用带有 href 属性的链接，或带有 data-bs-target 属性的按钮。在这两种情况下，都需要使用 data-bs-toggle="offcanvas" 属性。

Link with href

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> 元素。使用 data-bs-scroll 属性可启用 <body> 滚动。

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> 滚动。

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>

静态背景

当背景设置为静态时，在侧边栏外点击时不会关闭侧边栏。

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>

深色侧边栏

Deprecated in v5.3.0 Added in v5.2.0

使用实用程序更改 offcanvases 的外观，使其更好地匹配不同的上下文，如深色导航栏。在这里，我们在 .offcanvas 中添加了 .text-bg-dark，在 .btn-close 中添加了 .btn-close-white，以便在深色 offcanvas 中使用适当的样式。如果您在其中使用下拉菜单，也可以考虑在.dropdown-menu中添加.dropdown-menu-dark。

注意！ 随着颜色模式的引入，组件的深色变体在 v5.3.0 中已被弃用。与其手动添加上述类，不如在根元素、父包装器或组件本身设置 data-bs-theme="dark" 。

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>

响应式

Added in v5.2.0 响应式侧边栏类可从指定的断点向下隐藏视口外的内容。在该断点之上，视口内的内容将照常显示。例如，.offcanvas-lg 会隐藏lg断点以下的 offcanvas 中的内容，但会显示lg断点以上的内容。

Resize your browser to show the responsive offcanvas toggle.

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-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">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>

...

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>

...

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 面板在概念上是一个模态对话框，因此请务必在 .offcanvas 中添加 aria-labelledby="..." 引用 offcanvas 标题。请注意，您不需要添加 role="dialog" ，因为我们已经通过 JavaScript 添加了。

CSS

变量

Added in v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，offcanvas 现在使用 .offcanvas上的本地 CSS 变量来增强实时自定义功能。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-end 隐藏右侧的侧边栏
.offcanvas-top 隐藏顶部的侧边栏
.offcanvas-bottom 隐藏底部的侧边栏

添加一个带有 data-bs-dismiss="offcanvas" 属性的 dismiss 按钮，以触发 JavaScript 功能。请务必将 <button> 元素与之配合使用，以便在所有设备上正常运行。

通过数据属性

切换

在元素中添加 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>

虽然这两种解散侧边栏的方式都受支持，但请记住，从侧边了外部解散不符合ARIA 创作实践指南对话框（模式）模式。请自行承担风险。

通过 JavaScript

手动启用：

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

选项

由于可以通过 data 属性或 JavaScript 传递选项，因此可以在 data-bs- 中附加选项名称，如 data-bs-animation=“{value}”。通过data 属性传递选项时，请确保将选项名称的大小写类型从“camelCase”改为“kebab-case”。例如，使用 data-bs-custom-class=“beautifier” 而不是 data-bs-customClass=“beautifier”。

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

Name	Type	Default	Description
`backdrop`	boolean or the string `static`	`true`	在关闭侧边栏打开时在主体上应用背景。或者，指定 `static` 以获得在点击时不会关闭 offcanvas 的背景。
`keyboard`	boolean	`true`	按下 Escape 键时关闭画外工具栏。
`scroll`	boolean	`false`	允许在打开 offcanvas 时滚动主体。

方法

所有 API 方法都是异步的，并且会启动一个过渡，它们会在过渡开始后、结束前返回给调用者。此外，对过渡组件的方法调用将被忽略。更多信息，请参阅 JavaScript 文档

将内容激活为侧边栏元素。接受一个可选的选项 object。例如，您可以使用构造函数创建一个 offcanvas 实例：

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

Method	Description
`dispose`	销毁元素的 offcanvas。
`getInstance`	静态方法，用于获取与 DOM 元素相关联的 offcanvas 实例。
`getOrCreateInstance`	静态方法，用于获取与 DOM 元素相关联的 offcanvas 实例，或在未初始化的情况下创建一个新实例。
`hide`	隐藏侧边栏元素。在 offcanvas 元素实际隐藏之前（即在 `hidden.bs.offcanvas` 事件发生之前）返回给调用者。
`show`	显示侧边栏元素。在实际显示侧边栏元素之前（即在发生 `shown.bs.offcanvas` 事件之前）返回给调用者。
`toggle`	将侧边栏元素切换为显示或隐藏。在侧边栏元素实际显示或隐藏之前（即在发生 `shown.bs.offcanvas` 或 `hidden.bs.offcanvas` 事件之前）返回给调用者。

事件

Bootstrap 的 offcanvas 类提供了一些事件，用于连接到 offcanvas 功能。

Event type	Description
`hide.bs.offcanvas`	当调用 “隐藏 ”方法时，会立即触发该事件。
`hidden.bs.offcanvas`	当用户隐藏侧边栏元素时（将等待 CSS 过渡完成），将触发此事件。
`hidePrevented.bs.offcanvas`	当显示 offcanvas、其背景为 `static` 且在 offcanvas 外部执行单击时，将触发该事件。当按下 escape 键且键盘选项设置为 `false` 时，也会触发该事件。
`show.bs.offcanvas`	调用 `show` 实例方法时，该事件立即触发。
`shown.bs.offcanvas`	当用户看到侧边栏元素时（将等待 CSS 过渡完成），将触发此事件。

const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})