在GitHub查看

侧边栏

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

在此页

怎么运行的

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

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

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

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

例子

Offcanvas 组件

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

offcanvas 的内容在这里。您可以在此处放置几乎任何 Bootstrap 组件或自定义元素。

网页格式

<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隐藏内容（默认）
.offcanvas.show显示内容

您可以使用带有href属性的链接，或带有属性的按钮data-bs-target。在这两种情况下，data-bs-toggle="offcanvas"都是必需的。

链接到 href

一些文本作为占位符。在现实生活中，您可以拥有自己选择的元素。例如，文本、图像、列表等。

网页格式

<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 及其背景可见时，将禁用滚动元素。使用该data-bs-scroll属性启用<body>滚动。

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

网页格式

<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>使用可见背景启用滚动。

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

网页格式

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

如果你在我外面点击，我不会关闭。

网页格式

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

在此处放置画布内容。

网页格式

<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隐藏断点下方 offcanvas 中的lg内容，但显示lg断点上方的内容。

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

这是一个.offcanvas-lg.

网页格式

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

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

...

网页格式

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

...

网页格式

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

...

网页格式

<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="..."—referenced the offcanvas title— 添加到.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"and a data-bs-targetor添加href到元素以自动分配对一个 offcanvas 元素的控制。该data-bs-target属性接受一个 CSS 选择器来应用 offcanvas。请务必将类添加offcanvas到 offcanvas 元素。如果您希望它默认打开，请添加额外的类show。

解雇

可以使用offcanvasdata中按钮上的属性来实现解雇，如下所示：

<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 打开时在身体上应用背景。或者，指定`static`在单击时不关闭画布的背景。
`keyboard`	布尔值	`true`	按下退出键时关闭画布。
`scroll`	布尔值	`false`	在 offcanvas 打开时允许身体滚动。

方法

异步方法和转换

所有 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.offcanvas`or`hidden.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...
})

侧边栏

怎么运行的

例子

Offcanvas 组件

侧边栏

现场演示

侧边栏

身体滚动

带有身体滚动的 Offcanvas

身体滚动和背景

滚动背景

静态背景

侧边栏

深色侧边栏

侧边栏

反应灵敏

响应式画布

放置

侧边栏上衣

侧边栏右

侧边栏底

辅助功能

CSS

变量

Sass 变量

用法

通过数据属性

切换

解雇

通过 JavaScript

选项

方法

异步方法和转换

事件