跳到主要内容 跳到文档导航

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

怎么运行的

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

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

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

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

例子

Offcanvas 组件

下面是默认显示的 offcanvas 示例(通过在.offcanvas添加.show)。Offcanvas 支持带有关闭按钮的标题和一些初始padding. 我们建议您尽可能在 offcanvas 标头中包含关闭操作,或者提供明确的关闭操作。

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

Offcanvas with body scrolling

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

Backdrop with scrolling

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 不会关闭。

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.

Offcanvas

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.
Responsive offcanvas

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 放在视口的底部

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

Offcanvas top
...
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>
Offcanvas right
...
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>
Offcanvas bottom
...
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-targethref添加到元素以自动分配对一个 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.offcanvasorhidden.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...
})