Skip to main content Skip to docs navigation

Offcanvas

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

目录

怎么运行的

🌐 How it works

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

🌐 Offcanvas is a sidebar component that can be toggled via JavaScript to appear from the left, right, top, or bottom edge of the viewport. Buttons or anchors are used as triggers that are attached to specific elements you toggle, and data attributes are used to invoke our JavaScript.

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

注意！ 鉴于 CSS 处理动画的方式，你不能在 .offcanvas 元素上使用 margin 或 translate。相反，应将该类用作独立的封装元素。

The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation.

示例

🌐 Examples

Offcanvas 组件

🌐 Offcanvas components

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

🌐 Below is an offcanvas example that is shown by default (via .show on .offcanvas). Offcanvas includes support for a header with a close button and an optional body class for some initial padding. We suggest that you include offcanvas headers with dismiss actions whenever possible, or provide an explicit dismiss action.

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>

在线演示

🌐 Live demo

使用下面的按钮通过 JavaScript 显示和隐藏一个 offcanvas 元素，该元素会在具有 .offcanvas 类的元素上切换 .show 类。

🌐 Use the buttons below to show and hide an offcanvas element via JavaScript that toggles the .show class on an element with the .offcanvas class.

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

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

🌐 You can use a link with the href attribute, or a button with the data-bs-target attribute. In both cases, the data-bs-toggle="offcanvas" is required.

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 scrolling

当 offcanvas 及其背景可见时，<body> 元素的滚动被禁用。使用 data-bs-scroll 属性来启用 <body> 滚动。

🌐 Scrolling the <body> element is disabled when an offcanvas and its backdrop are visible. Use the data-bs-scroll attribute to enable <body> scrolling.

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 scrolling and backdrop

你也可以启用带有可见背景的 <body> 滚动。

🌐 You can also enable <body> scrolling with a visible backdrop.

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>

静态背景

🌐 Static backdrop

当背景设置为静态时，在画布外部单击时，画布不会关闭。

🌐 When backdrop is set to static, the offcanvas will not close when clicking outside of it.

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>

深色画布

🌐 Dark offcanvas

Deprecated in v5.3.0 Added in v5.2.0

使用工具更改边栏（offcanvas）的外观，以更好地将其匹配到不同的上下文，例如深色导航栏。在这里，我们将 .text-bg-dark 添加到 .offcanvas，将 .btn-close-white 添加到 .btn-close，以便在深色边栏中进行适当的样式设置。如果里面有下拉菜单，还可以考虑将 .dropdown-menu-dark 添加到 .dropdown-menu。

🌐 Change the appearance of offcanvases with utilities to better match them to different contexts like dark navbars. Here we add .text-bg-dark to the .offcanvas and .btn-close-white to .btn-close for proper styling with a dark offcanvas. If you have dropdowns within, consider also adding .dropdown-menu-dark to .dropdown-menu.

注意！ 随着颜色模式的引入，组件的深色变体在 v5.3.0 中已被弃用。不要手动添加上面提到的类，而应在根元素、父封装器或组件本身上设置 data-bs-theme="dark"。

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>

响应式

🌐 Responsive

Added in v5.2.0

响应式侧边栏类会在指定断点及以下隐藏视口外的内容。在该断点以上，内容将照常显示。例如，.offcanvas-lg 会在 lg 断点以下隐藏侧边栏中的内容，但在 lg 断点以上显示内容。每个断点都提供响应式侧边栏类。

🌐 Responsive offcanvas classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, .offcanvas-lg hides content in an offcanvas below the lg breakpoint, but shows the content above the lg breakpoint. Responsive offcanvas classes are available for each breakpoint.

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

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

🌐 To make a responsive offcanvas, replace the .offcanvas base class with a responsive variant and ensure your close button has an explicit data-bs-target.

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>

放置

🌐 Placement

画布外组件没有默认放置位置，因此你必须添加以下修饰符类之一。

🌐 There’s no default placement for offcanvas components, so you must add one of the modifier classes below.

  • .offcanvas-start 将 offcanvas 放置在视口的左侧（如上所示）
  • .offcanvas-end 将侧滑面板放置在视口右侧
  • .offcanvas-top 将离屏放置在视口的顶部
  • .offcanvas-bottom 将离屏内容放置在视口底部

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

🌐 Try the top, right, and bottom examples out below.

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>

无障碍

🌐 Accessibility

由于侧边面板在概念上是一个模态对话框，请确保将 aria-labelledby="..."——引用侧边面板标题——添加到 .offcanvas。请注意，你不需要添加 role="dialog"，因为我们已经通过 JavaScript 添加了它。

🌐 Since the offcanvas panel is conceptually a modal dialog, be sure to add aria-labelledby="..."—referencing the offcanvas title—to .offcanvas. Note that you don’t need to add role="dialog" since we already add it via JavaScript.

CSS

变量

🌐 Variables

Added in v5.2.0

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

🌐 As part of Bootstrap’s evolving CSS variables approach, offcanvas now uses local CSS variables on .offcanvas for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

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

🌐 Sass variables

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;

用法

🌐 Usage

offcanvas 插件利用一些类和属性来处理繁重的工作：

🌐 The offcanvas plugin utilizes a few classes and attributes to handle the heavy lifting:

  • .offcanvas 隐藏内容
  • .offcanvas.show 显示内容
  • .offcanvas-start 隐藏左侧的侧边栏
  • .offcanvas-end 隐藏右侧的侧边栏
  • .offcanvas-top 在顶部隐藏了侧边栏
  • .offcanvas-bottom 隐藏底部的侧边栏

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

🌐 Add a dismiss button with the data-bs-dismiss="offcanvas" attribute, which triggers the JavaScript functionality. Be sure to use the <button> element with it for proper behavior across all devices.

通过数据属性

🌐 Via data attributes

切换

🌐 Toggle

向元素添加 data-bs-toggle="offcanvas" 和 data-bs-target 或 href，以自动分配对一个离屏元素的控制。data-bs-target 属性接受一个 CSS 选择器来应用离屏元素。确保向离屏元素添加类 offcanvas。如果希望其默认打开，请添加额外的类 show。

🌐 Add data-bs-toggle="offcanvas" and a data-bs-target or href to the element to automatically assign control of one offcanvas element. The data-bs-target attribute accepts a CSS selector to apply the offcanvas to. Be sure to add the class offcanvas to the offcanvas element. If you’d like it to default open, add the additional class show.

退出

🌐 Dismiss

Dismissal can be achieved with the data-bs-dismiss attribute on a button within the offcanvas as demonstrated below: 

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

or on a button outside the offcanvas using the additional data-bs-target as demonstrated below: 

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>

虽然支持以两种方式关闭侧边栏，但请记住，从侧边栏外部关闭不符合ARIA 编写规范指南对话框（模态）模式。请自行承担风险。

通过 JavaScript

🌐 Via JavaScript

手动启用：

🌐 Enable manually with:

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))

选项

🌐 Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

名称类型默认值描述
backdrop布尔或字符串 statictrue当侧边栏打开时在页面主体上应用背景。或者，指定 static 使用点击不会关闭侧边栏的背景。
keyboard布尔true当按下 Escape 键时关闭侧边栏。
scroll布尔false侧边栏打开时允许页面主体滚动。

方法

🌐 Methods

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started, but before it ends. In addition, a method call on a transitioning component will be ignored. Learn more in our JavaScript docs.

将你的内容激活为离开画布元素。可接收可选的选项 object。

🌐 Activates your content as an offcanvas element. Accepts an optional options object.

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

🌐 You can create an offcanvas instance with the constructor, for example:

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

事件

🌐 Events

Bootstrap 的 offcanvas 类公开了一些事件，用于连接到 offcanvas 功能。

🌐 Bootstrap’s offcanvas class exposes a few events for hooking into offcanvas functionality.

事件类型描述
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...
})