画布外（Offcanvas）

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

当前页

工作原理

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

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

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

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

示例

Offcanvas 组件

下面是一个默认显示的 offcanvas 示例（通过 .offcanvas 上的 .show）。Offcanvas 包括对带有关闭按钮的标题和用于某些初始padding的可选 body 类的支持。我们建议您尽可能在消除操作中包含 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元素，该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> 元素。使用 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>滚动。

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>

深色 offcanvas

在 v5.3.0 版本中弃用 Added in v5.2.0

使用实用程序更改画布外的外观，以更好地将它们与不同的上下文（如深色导航栏）相匹配。在这里，我们将.text-bg-dark添加到.offcanvas，将.btn-close-white添加到.btn-close，以便使用深色画布进行适当的样式设置。如果其中包含下拉列表，请考虑将 .dropdown-menu-dark添加到 .dropdown-menu。

小心！组件的深色变体在 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 类将视区外的内容从指定的断点隐藏并向下隐藏。在该断点上方，其中的内容将照常运行。例如，.offcanvas-lg隐藏内容在lg 断点下方的画布外，但显示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-end 将画布外放置在视口右侧
.offcanvas-top 将画布外放置在视口的顶部
.offcanvas-bottom 将画布外放置在视口的底部

尝试下面的顶部、右侧和底部示例。

...

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

变量

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"属性的关闭按钮，这将触发JavaScript功能。请务必将<button> 元素与它一起使用，以便在所有设备上正确执行行为。

通过数据属性

切换

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

解除

可以通过在 offcanvas 中的按钮上的data-bs-dismiss属性来实现关闭，如下所示：

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

选项

由于选项可以通过数据属性或 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`	boolean or the string `static`	`true`	在画布外打开时在身体上应用背景。或者，为单击时不会关闭画布外的背景指定`static` 。
`keyboard`	boolean	`true`	按下转义键时关闭画布外。
`scroll`	boolean	`false`	允许在画布外打开时滚动正文。

方法

所有 API 方法都是异步的，并且会启动转换。 它们在转换开始后但在转换结束之前立即返回给调用方。此外，对转换组件的方法调用将被忽略。在我们的 JavaScript 文档中了解更多信息。

将您的内容激活为画布外元素。接受可选选项 object。

您可以使用构造函数创建画布外实例，例如：

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

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

事件

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

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

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