Offcanvas

怎么运行的

¥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 shares some of the same JavaScript code as modals. Conceptually, they are quite similar, but they are separate plugins.

• 同样，offcanvas 样式和尺寸的一些 源 Sass 变量继承自 modal 变量。

  ¥Similarly, some source Sass variables for offcanvas’s styles and dimensions are inherited from the modal’s variables.

• 显示时，offcanvas 包含一个默认背景，可以单击该背景来隐藏 offcanvas。

  ¥When shown, offcanvas includes a default backdrop that can be clicked to hide the offcanvas.

• 与模态框类似，一次只能显示一张画布。

  ¥Similar to modals, only one offcanvas can be shown at a time.

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

¥Heads up! Given how CSS handles animations, you cannot use margin or translate on an .offcanvas element. Instead, use the class as an independent wrapping element.

示例

¥Examples

Offcanvas 组件

¥Offcanvas components

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

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

<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 hides content (default)

• .offcanvas.show 显示内容

  ¥.offcanvas.show shows content

你可以使用具有 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.

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

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

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

<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

使用工具更改画布的外观，以更好地将它们匹配到不同的上下文（例如深色导航栏）。在这里，我们将 .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.

<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

响应式 offcanvas 类隐藏指定断点及以下视口之外的内容。在该断点之上，其中的内容将如常运行。例如，.offcanvas-lg 隐藏 lg 断点下方的 offcanvas 中的内容，但显示 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.

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

¥Responsive offcanvas classes are available across for each breakpoint.

• .offcanvas

• .offcanvas-sm

• .offcanvas-md

• .offcanvas-lg

• .offcanvas-xl

• .offcanvas-xxl

放置

¥Placement

offcanvas 组件没有默认位置，因此你必须添加下面的修饰符类之一。

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

• .offcanvas-start 将 offcanvas 放置在视口的左侧（如上所示）

  ¥.offcanvas-start places offcanvas on the left of the viewport (shown above)

• .offcanvas-end 将 offcanvas 放置在视口右侧

  ¥.offcanvas-end places offcanvas on the right of the viewport

• .offcanvas-top 将 offcanvas 放置在视口顶部

  ¥.offcanvas-top places offcanvas on the top of the viewport

• .offcanvas-bottom 将 offcanvas 放置在视口的底部

  ¥.offcanvas-bottom places offcanvas on the bottom of the viewport

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

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

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

无障碍

¥Accessibility

由于 offcanvas 面板在概念上是一个模式对话框，因此请务必将 aria-labelledby="..."（引用 offcanvas 标题）添加到 .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

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

--#{$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

$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 hides the content

• .offcanvas.show 显示内容

  ¥.offcanvas.show shows the content

• .offcanvas-start 隐藏左侧的 offcanvas

  ¥.offcanvas-start hides the offcanvas on the left

• .offcanvas-end 隐藏右侧的 offcanvas

  ¥.offcanvas-end hides the offcanvas on the right

• .offcanvas-top 隐藏顶部的 offcanvas

  ¥.offcanvas-top hides the offcanvas on the top

• .offcanvas-bottom 隐藏底部的 offcanvas

  ¥.offcanvas-bottom hides the offcanvas on the 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 添加到元素以自动分配对一个 offcanvas 元素的控制。data-bs-target 属性接受 CSS 选择器来应用 offcanvas。确保将 offcanvas 类添加到 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>

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

方法

¥Methods

将你的内容激活为 offcanvas 元素。接受可选选项 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')

活动

¥Events

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

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

const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})