l-1

WEB教程

主页/Bootstrap V5.3 中文手册/组件集合 Components/Offcanvas 侧边栏

Bootstrap V5.3 中文手册

Offcanvas 侧边栏

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

运作方式

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

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

小心！鉴于 CSS 处理动画的方式，您不能在元素上使用 或。相反，请将类用作独立的包装元素。margintranslate.offcanvas

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

例子

画布外组件

下面是一个默认显示的画布外示例（通过 on ）。Offcanvas 包括对带有关闭按钮的标头的支持，以及一些初始 .建议尽可能在关闭作中包含 offcanvas 标头，或提供显式关闭作。.show.offcanvaspadding

画布外
画布外的内容在这里。您可以在此处放置几乎任何 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 显示和隐藏画布外元素，该元素在具有类的元素上切换类。.show.offcanvas

  • .offcanvas隐藏内容（默认）
  • .offcanvas.show显示内容

您可以使用带有属性的链接，或使用带有属性的按钮。在这两种情况下，都是必需的。hrefdata-bs-targetdata-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>

带有正文滚动的 Offcanvas

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

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

使用实用程序更改画布外的外观，以更好地将它们与不同的上下文（如深色导航栏）相匹配。在这里，我们添加 和 以使用深色画布进行适当的造型。如果其中有下拉列表，请考虑将 添加到 。.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-lglglg

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

要制作响应式 offcanvas，请将基类替换为响应式变体，并确保您的关闭按钮具有显式 ..offcanvasdata-bs-target

调整浏览器大小以显示响应式画布外切换。
Responsive offcanvas

这是 ..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-start将 offcanvas 放置在视口的左侧（如上所示）
  • .offcanvas-end将 offcanvas 放置在视口的右侧
  • .offcanvas-top将 offcanvas 放置在视口的顶部
  • .offcanvas-bottom将画布外放置在视口底部

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

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>
画布右
…
[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 面板在概念上是一个模态对话框，因此请务必将 （引用 offcanvas 标题） 添加到 。请注意，您不需要添加，因为我们已经通过 JavaScript 添加了它。aria-labelledby="...".offcanvasrole="dialog"

CSS系统

变量

在 v5.2.0 中添加

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，offcanvas 现在使用本地 CSS 变量来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。.offcanvas

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
  • .offcanvas-end隐藏右侧的画布外
  • .offcanvas-top将画布外隐藏在顶部
  • .offcanvas-bottom隐藏底部的画布外

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

通过数据属性

切换

添加 和 或 以自动分配对一个画布外元素的控制权。该属性接受一个 CSS 选择器来应用 offcanvas。请务必将类添加到 offcanvas 元素中。如果您希望它默认打开，请添加其他类。data-bs-toggle="offcanvas"data-bs-targethrefdata-bs-targetoffcanvasshow

解雇

关闭可以通过 offcanvas 中按钮上的属性来实现，如下所示：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 传递，因此您可以将选项名称附加到 ，如 。通过数据属性传递选项时，请确保将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用 代替 。data-bs-data-bs-animation="{value}"data-bs-custom-class="beautifier"data-bs-customClass="beautifier"

从 Bootstrap 5.2.0 开始，所有组件都支持实验性保留数据属性，该属性可以将简单的组件配置作为 JSON 字符串容纳。当元素具有 和 属性时，最终值将是 ，并且单独的数据属性将覆盖 上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 .data-bs-configdata-bs-config='{"delay":0, "title":123}'data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

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

名字类型违约描述
backdropboolean 或字符串statictrue在画布外打开时在身体上应用背景。或者，指定单击时不关闭画布外的背景。static
keyboard布尔true按下 Escape 键时关闭画布外。
scroll布尔false允许在 offcanvas 打开时滚动正文。

方法

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

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

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

const bsOffcanvas = new bootstrap.Offcanvas('#myOffcanvas')
方法描述
dispose销毁元素的画布外。
getInstance静态方法，允许您获取与 DOM 元素关联的 offcanvas 实例。
getOrCreateInstance静态方法，允许您获取与 DOM 元素关联的 offcanvas 实例，或创建一个新实例，以防它未初始化。
hide隐藏画布外元素。在 offcanvas 元素实际隐藏之前（即事件发生之前）返回给调用者。hidden.bs.offcanvas
show显示画布外元素。在 offcanvas 元素实际显示之前（即事件发生之前）返回给调用者。shown.bs.offcanvas
toggle将画布外元素切换为显示或隐藏。在 offcanvas 元素实际显示或隐藏之前（即在 or 事件发生之前）返回给调用者。shown.bs.offcanvashidden.bs.offcanvas

事件

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

事件类型描述
hide.bs.offcanvas调用该方法后，会立即触发此事件。hide
hidden.bs.offcanvas当 offcanvas 元素对用户隐藏时，将触发此事件（将等待 CSS 转换完成）。
hidePrevented.bs.offcanvas当画布外显示时，将触发此事件，其背景为，并在画布外执行单击。当按下转义键并将选项设置为 时，也会触发该事件。statickeyboardfalse
show.bs.offcanvas调用实例方法时，此事件会立即触发。show
shown.bs.offcanvas当 offcanvas 元素对用户可见时，将触发此事件（将等待 CSS 转换完成）。
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})

声明：该Bootstrap v5.3 内容来自Bootstrap v5.3官方网站；中文翻译是使用Microsoft Edge浏览器免费翻译而来，且部分存在结合了Deepseek及人工翻译。