侧边栏

使用一些类和我们的 JavaScript 插件，在您的项目中为导航、购物车等构建隐藏的侧边栏。

在此页

怎么运行的

Offcanvas 是一个侧边栏组件，可以通过 JavaScript 切换为从视口的左侧、右侧、顶部或底部边缘显示。按钮或锚点用作附加到您切换的特定元素的触发器，data属性用于调用我们的 JavaScript。

Offcanvas 与模态对话框共享一些相同的 JavaScript 代码。从概念上讲，它们非常相似，但它们是独立的插件。
类似地，offcanvas 样式和尺寸的一些源 Sass变量是从模态变量继承的。
显示时，offcanvas 包括一个默认背景，可以单击它来隐藏 offcanvas。
与模态对话框类似，一次只能显示一个画布。

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

该组件的动画效果依赖于prefers-reduced-motion媒体查询。请参阅我们的辅助功能文档的减少运动部分。

例子

Offcanvas 组件

下面是默认显示的 offcanvas 示例（通过在.offcanvas添加.show）。Offcanvas 支持带有关闭按钮的标题和一些初始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 元素，该元素在带有.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滚动

当 offcanvas 及其遮罩可见时，将禁用滚动<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>

静态背景

当背景设置为静态时，在其外部单击时，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>

深色侧边栏

添加于 v5.2.0

使用实用程序更改画布外的外观，以更好地将它们与不同的上下文（如深色导航栏）相匹配。在这里，我们添加.text-bg-dark到.offcanvas和.btn-close-white到.btn-close使用深色画布进行适当的造型。如果您在其中有下拉菜单，请考虑也添加.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>

响应式

添加于 v5.2.0

响应式 offcanvas 类将内容从指定的断点向下隐藏在视口之外。在该断点之上，其中的内容将照常运行。例如，.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 组件没有默认位置，因此您必须添加下面的修改器类之一。

.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 面板在概念上是一个模态对话框，因此请务必将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-end隐藏右侧的画布
.offcanvas-top隐藏顶部的画布
.offcanvas-bottom隐藏底部的画布

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

通过数据属性

切换

将data-bs-toggle="offcanvas"和data-bs-target或href添加到元素以自动分配对一个 offcanvas 元素的控制。该data-bs-target属性接受一个 CSS 选择器来应用 offcanvas。请务必将类添加offcanvas到 offcanvas 元素。如果您希望它默认打开，请添加额外的类show。

关闭

可以使用offcanvas中按钮上的data属性来实现关闭，如下所示：

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

或在画布外的按钮上使用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 创作实践指南对话框（模态）模态对话框不匹配。这样做需要您自担风险。

通过 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}'.

名称	类型	默认	描述
`backdrop`	布尔值或字符串`static`	`true`	在 offcanvas 打开时在Body上应用背景。或者，指定`static`在单击时不关闭画布的背景。
`keyboard`	布尔值	`true`	按下退出键时关闭画布。
`scroll`	布尔值	`false`	在 offcanvas 打开时允许Body滚动。

方法

异步方法和转换

所有 API 方法都是异步的并开始一个转换。它们会在转换开始但结束之前立即返回给调用者。此外，将忽略对转换组件的方法调用。

有关详细信息，请参阅我们的 JavaScript 文档。

将您的内容激活为 offcanvas 元素。接受一个可选的选项object。

您可以使用构造函数创建一个 offcanvas 实例，例如：

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

方法	描述
`getInstance`	允许您获取与 DOM 元素关联的 offcanvas 实例的静态方法。
`getOrCreateInstance`	允许您获取与 DOM 元素关联的 offcanvas 实例的静态方法，或者创建一个新实例以防未初始化。
`hide`	隐藏画布外元素。在 offcanvas 元素实际被隐藏之前（即事件发生之前）返回给调用者。`hidden.bs.offcanvas`
`show`	显示 offcanvas 元素。在 offcanvas 元素实际显示之前（即事件发生之前）返回给调用者。`shown.bs.offcanvas`
`toggle`	将 offcanvas 元素切换为显示或隐藏。在 offcanvas 元素实际显示或隐藏之前返回给调用者（即在`shown.bs.offcanvas`or`hidden.bs.offcanvas`事件发生之前）。

事件

Bootstrap 的 offcanvas 类公开了一些用于连接到 offcanvas 功能的事件。

事件类型	描述
`hide.bs.offcanvas`	`hide`调用该方法后会立即触发此事件。
`hidden.bs.offcanvas`	当对用户隐藏了 offcanvas 元素时会触发此事件（将等待 CSS 转换完成）。
`hidePrevented.bs.offcanvas`	当显示 offcanvas 时会触发此事件，它的背景是`static`并且在 offcanvas 外部执行单击。当按下转义键且`keyboard`选项设置为时，也会触发该事件`false`。
`show.bs.offcanvas`	`show`调用实例方法时会立即触发此事件。
`shown.bs.offcanvas`	当 offcanvas 元素对用户可见时会触发此事件（将等待 CSS 转换完成）。

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