跳到主要内容
在 GitHub 查看原文

画布外菜单

通过几个类和我们的JavaScript插件，将隐藏的侧边栏构建到你的项目中，用于导航、购物车等功能。

本页目录

它是如何工作的

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

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

小心！ 鉴于 CSS 处理动画的方式，你无法在 .offcanvas 元素上使用 margin 或 translate。请改用该元素作为独立的包装元素。

此组件的动画效果取决于 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 显示和隐藏可切换的画布外元素（在 .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>

静态背景

当 backdrop 设置为 static 时，点击其外部时 offcanvas 不会关闭。

侧边栏
如果你点击我之外的地方，我不会关闭。
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 中添加

使用工具类更改侧边栏的外观，以便更好地将其匹配到不同的环境，例如深色导航栏。在这里，我们将.text-bg-dark添加到.offcanvas，并将.btn-close-white添加到.btn-close，以便在深色侧边栏中正确样式。如果内部有下拉菜单，也可以考虑将.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 类会在指定的断点及其以下隐藏视口之外的内容。在该断点以上，其中的内容将按常规行为显示。例如，.offcanvas-lg 在 lg 断点以下隐藏 offcanvas 内容，但在 lg 断点以上显示内容。每个断点都有可用的响应式 offcanvas 类。

  • .offcanvas
  • .offcanvas-sm
  • .offcanvas-md
  • .offcanvas-lg
  • .offcanvas-xl
  • .offcanvas-xxl

要制作响应式侧边栏，请将.offcanvas基础类替换为响应式变体，并确保你的关闭按钮具有明确的data-bs-target。

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

这是其中的内容 .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-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 现在在 .offcanvas 上使用本地 CSS 变量，以增强实时自定义能力。CSS 变量的值通过 Sass 设置，因此仍然支持 Sass 自定义。

scss/_侧边栏.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 元素添加类 offcanvas。如果希望默认打开，添加额外的类 show。

解雇

解雇可以通过 data-bs-dismiss 按钮上的属性 在侧边栏内 如下所示：

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

虽然两种关闭侧边栏的方法都受到支持，但请记住，从侧边栏外部关闭并不符合 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 上给定的值。此外，现有的数据属性也能够存放如 data-bs-delay='{"show":0,"hide":150}' 的 JSON 值。

最终的配置对象是data-bs-config、data-bs-和js object合并的结果，其中最新提供的键值会覆盖其他键值。

名称类型默认值描述
backdrop布尔值 或 字符串 statictrue在 offcanvas 打开时在页面主体添加背景。或者，指定 static 以使用点击时不关闭 offcanvas 的背景。
keyboardbooleantrue按下 Esc 键时关闭 offcanvas。
scrollbooleanfalse在 offcanvas 打开时允许页面主体滚动。

方法

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

将你的内容作为脱离画布元素激活。可以接受可选的选项 object。

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

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
方法描述
dispose销毁元素的侧边栏。
getInstance静态 一种允许你获取与 DOM 元素关联的 offcanvas 实例的方法。
getOrCreateInstance静态 一种方法，允许你获取与 DOM 元素关联的 offcanvas 实例，或者在未初始化的情况下创建一个新的实例。
hide隐藏一个离画布元素。 在边栏元素实际被隐藏之前就返回给调用者 （即在……之前 hidden.bs.offcanvas 事件发生)。
show显示一个侧边栏元素。 在边栏元素实际显示之前返回给调用者 （即在……之前 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...
})