Offcanvas

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

内容提要

工作原理

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

Offcanvas 与 modals 共享一些相同的 JavaScript 代码。从概念上讲，它们非常相似，但它们是独立的插件。
类似地，一些用于 offcanvas 样式和尺寸的 source Sass 变量继承自 modal 的变量。
offcanvas 显示时，包含一个默认背景，单击该背景可以隐藏 offcanvas。
与 modals 类似，一次只能显示一个 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.

<div class="offcanvas offcanvas-start" 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 text-reset" 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.

<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 text-reset" 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" id="dropdownMenuButton" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
        <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>

位置

offcanvas 组件没有默认位置，因此您必须添加以下修饰符类之一；

.offcanvas-start 将 offcanvas 放置在视口的左侧（如上所示）
.offcanvas-end 将 offcanvas 放置在视口的右侧
.offcanvas-top 将 offcanvas 放置在视口的顶部
.offcanvas-bottom 将 offcanvas 放置在视口的底部

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

...

<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 id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

<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 id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

...

<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 text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

背景关闭(Backdrop)

当 offcanvas 及其背景显示时，<body> 元素将被禁用滚动。使用 data-bs-scroll 属性来关闭或启用 <body> 的滚动，使用 data-bs-backdrop 来关闭或启用背景关闭。

Try scrolling the rest of the page to see this option in action.

.....

Try scrolling the rest of the page to see this option in action.

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBackdrop" aria-controls="offcanvasWithBackdrop">Enable backdrop (default)</button>
<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" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Colored with scrolling</h5>
    <button type="button" class="btn-close text-reset" 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>
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasWithBackdrop" aria-labelledby="offcanvasWithBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBackdropLabel">Offcanvas with backdrop</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>.....</p>
  </div>
</div>
<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 text-reset" 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 面板在概念上是一个模态对话框，因此请务必将 aria-labelledby="..."（引用 offcanvas 标题）添加到 .offcanvas 上。请注意，您不需要添加 role="dialog"，因为我们已经通过 JavaScript 添加了它。

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-bottom 隐藏底部的offcanvas

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

通过数据属性

Toggle

添加 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>

或在 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 外部关闭与 WAI-ARIA 模式对话框设计模式不匹配。这样做需要您自担风险。

使用 JavaScript

手动启用：

var offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
  return new bootstrap.Offcanvas(offcanvasEl)
})

选项

选项可以通过数据属性或 JavaScript 传递。对于数据属性，将选项名称附加到 data-bs-，如 data-bs-backdrop=""。

名称	类型	默认值	描述
`backdrop`	boolean	`true`	在 offcanvas 打开时，在 body 上应用背景关闭(backdrop)
`keyboard`	boolean	`true`	当退出按钮按下时关闭 offcanvas。
`scroll`	boolean	`false`	在 offcanvas 打开时，允许 body 滚动。

方法

异步方法和过渡效果

所有 API 方法都是异步并启动transition。它们会在过渡开始后但在过渡结束之前返回给调用者。此外，正在过渡的组件上的调用方法，过渡将被忽略。

查看我们的 JavaScript 文档了解更多信息。

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

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

var myOffcanvas = document.getElementById('myOffcanvas')
var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)

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

事件

Bootstrap offcanvas 类公开了一些作为 offcanvas 功能内部的钩子的事件。

事件类型	描述
`show.bs.offcanvas`	此事件在调用 `show` 实例方法时立即触发。
`shown.bs.offcanvas`	当 offcanvas 元素对用户可见时触发此事件（将等待 CSS 过渡完成）。
`hide.bs.offcanvas`	当调用 `hide` 方法时，会立即触发此事件。
`hidden.bs.offcanvas`	当一个 offcanvas 元素对用户隐藏时触发此事件（将等待 CSS 转换完成）。

var myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', function () {
  // do something...
})