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

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

工作原理

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

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

注意!鉴于 CSS 处理动画的方式,您不能对 .offcanvas 元素使用 margintranslate。相反,将该类用作独立的包装元素。

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅 无障碍文档的减少运动部分

示例

侧边栏组件

下面是一个默认显示的侧边栏示例(通过 .offcanvas 上的 .show)。侧边栏支持带有关闭按钮的标题,以及用于一些初始 padding 的可选主体类。我们建议你尽可能在侧边栏标题中包含关闭操作,或提供明确的关闭操作。

离画布
侧边栏的内容放在这里。你几乎可以将任何 Bootstrap 组件或自定义元素放在这里。
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 显示和隐藏侧边栏元素,该 JavaScript 在具有 .offcanvas 类的元素上切换 .show 类。

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

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

带有 href 的链接
离画布
一些占位符文本。在实际生活中,你可以拥有你选择的元素。比如文本、图像、列表等。
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> 滚动。

带有主体滚动的侧边栏

尝试滚动页面的其余部分,以查看此选项的实际效果。

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

带有滚动的背景

尝试滚动页面的其余部分,以查看此选项的实际效果。

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>

静态背景

当背景设置为静态时,单击侧边栏外部不会关闭侧边栏。

离画布
如果您点击我的外部,我不会关闭。
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.3.0 已添加 v5.2.0

使用实用程序更改侧边栏的外观,以更好地匹配它们与不同上下文(如深色导航栏)的匹配。这里我们为 .offcanvas 添加 .text-bg-dark,为 .btn-close 添加 .btn-close-white,以便使用深色侧边栏进行适当的样式设置。如果您在内部有下拉菜单,请考虑还将 .dropdown-menu-dark 添加到 .dropdown-menu

注意!随着颜色模式的引入,组件的深色变体在 v5.3.0 中已弃用。不要手动添加上述类,而是在根元素、父包装器或组件本身上设置 data-bs-theme="dark"
离画布

在此处放置侧边栏内容。

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-lg 将在 lg 断点以下隐藏侧边栏中的内容,但在 lg 断点以上显示内容。

调整浏览器大小以显示响应式侧边栏切换。
响应式侧边栏

这是 .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>

辅助功能

由于侧边栏面板在概念上是一个模态对话框,请务必将 aria-labelledby="..."(引用侧边栏标题)添加到 .offcanvas。请注意,您无需添加 role="dialog",因为我们已通过 JavaScript 添加了它。

CSS

变量

已添加 v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分,侧边栏现在在 .offcanvas 上使用本地 CSS 变量,以增强实时自定义。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.show 显示内容
  • .offcanvas-start 在左侧隐藏侧边栏
  • .offcanvas-end 在右侧隐藏侧边栏
  • .offcanvas-top 在顶部隐藏侧边栏
  • .offcanvas-bottom 在底部隐藏侧边栏

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

通过数据属性

切换

data-bs-toggle="offcanvas"data-bs-targethref 添加到元素,以自动分配一个侧边栏元素的控制权。data-bs-target 属性接受一个 CSS 选择器,以将侧边栏应用于该选择器。请务必将 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>
虽然支持这两种关闭 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}'

最终的配置对象是 data-bs-configdata-bs-js 对象 的合并结果,其中最新给出的键值对覆盖其他键值对。

名称 类型 默认值 描述
backdrop 布尔值或字符串 static true 在 offcanvas 打开时在 body 上应用背景。或者,为不会在点击时关闭 offcanvas 的背景指定 static
keyboard 布尔值 true 在按下 ESC 键时关闭 offcanvas。
scroll 布尔值 false 在 offcanvas 打开时允许 body 滚动。

方法

所有 API 方法都是异步的,并启动一个过渡。它们在过渡开始后立即返回给调用者,但在过渡结束之前。此外,将忽略对正在过渡的组件的方法调用。 在我们的 JavaScript 文档中了解更多信息。

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

您可以使用构造函数创建 offcanvas 实例,例如

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
方法 描述
dispose 销毁元素的侧边栏。
getInstance 静态方法,允许你获取与 DOM 元素关联的侧边栏实例。
getOrCreateInstance 静态方法,允许你获取与 DOM 元素关联的侧边栏实例,或者在未初始化的情况下创建一个新的实例。
hide 隐藏侧边栏元素。在侧边栏元素实际隐藏之前返回给调用者(即在 hidden.bs.offcanvas 事件发生之前)。
show 显示侧边栏元素。在侧边栏元素实际显示之前返回给调用者(即在 shown.bs.offcanvas 事件发生之前)。
toggle 切换侧边栏元素为显示或隐藏。在侧边栏元素实际显示或隐藏之前返回给调用者(即在 shown.bs.offcanvashidden.bs.offcanvas 事件发生之前)。

事件

Bootstrap 的侧边栏类公开了一些事件,用于连接到侧边栏功能。

事件类型 描述
hide.bs.offcanvas 当调用 hide 方法时立即触发此事件。
hidden.bs.offcanvas 当侧边栏元素对用户隐藏时触发此事件(将等待 CSS 过渡完成)。
hidePrevented.bs.offcanvas 当侧边栏显示、其背景为 static 并且在侧边栏外部单击时触发此事件。当按下 ESC 键且 keyboard 选项设置为 false 时也会触发此事件。
show.bs.offcanvas 当调用 show 实例方法时立即触发此事件。
shown.bs.offcanvas 当侧边栏元素对用户可见时触发此事件(将等待 CSS 过渡完成)。
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})