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

折叠面板

结合我们的 Collapse JavaScript 插件构建垂直折叠的折叠面板组件。

本页目录

它是如何工作的

折叠面板组件基于 折叠（Collapse） 插件实现可折叠功能。

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们的无障碍文档中的减少动画部分。

示例

点击下面的折叠面板以展开/折叠折叠面板内容。

要显示默认展开的折叠面板：

  • 为 .accordion-collapse 元素添加 .show 类。
  • 从 .accordion-button 元素上移除 .collapsed 类，并将其 aria-expanded 设置为 true。

这是第一个项目的折叠面板内容。 默认情况下它会显示，直到折叠插件添加我们用于样式化每个元素的适当类。这些类控制整体外观，以及通过 CSS 过渡效果的显示和隐藏。你可以通过自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中 .accordion-body，尽管过渡确实限制了溢出。

这是第二个项目的折叠面板内容。 默认情况下它是隐藏的，直到折叠插件添加我们用来为每个元素设置样式的适当类。这些类控制整体外观，以及通过 CSS 过渡实现的显示和隐藏。你可以使用自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中 .accordion-body，尽管这种过渡确实限制了溢出。

这是第三个项目的折叠面板内容。 默认情况下它是隐藏的，直到折叠插件添加我们用来为每个元素设置样式的适当类。这些类控制整体外观，以及通过 CSS 过渡实现的显示和隐藏。你可以使用自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中 .accordion-body，尽管这种过渡确实限制了溢出。
HTML
<div class="accordion" id="accordionExample">
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
        Accordion Item #1
      </button>
    </h2>
    <div id="collapseOne" class="accordion-collapse collapse show" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        <strong>This is the first item’s accordion body.</strong> It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
        Accordion Item #2
      </button>
    </h2>
    <div id="collapseTwo" class="accordion-collapse collapse" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        <strong>This is the second item’s accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
        Accordion Item #3
      </button>
    </h2>
    <div id="collapseThree" class="accordion-collapse collapse" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        <strong>This is the third item’s accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
</div>

无边框（Flush）

添加 .accordion-flush 移除一些边框和圆角，使折叠面板组件与其父容器边缘对齐。

此折叠面板的占位内容，用于演示 .accordion-flush 类。这是第一个项目的折叠面板内容。

此折叠面板的占位内容，用于演示 .accordion-flush 类。这是第二个项目的折叠面板内容区域。让我们想象这里填充了一些实际内容。

此折叠面板的占位内容，用于演示 .accordion-flush 类。这是第三项的折叠面板内容。这里在内容方面没有更令人兴奋的事情，只是填充空间，以使其至少在初看时，更像在真实应用中的样子。
HTML
<div class="accordion accordion-flush" id="accordionFlushExample">
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseOne" aria-expanded="false" aria-controls="flush-collapseOne">
        Accordion Item #1
      </button>
    </h2>
    <div id="flush-collapseOne" class="accordion-collapse collapse" data-bs-parent="#accordionFlushExample">
      <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the first item’s accordion body.</div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseTwo" aria-expanded="false" aria-controls="flush-collapseTwo">
        Accordion Item #2
      </button>
    </h2>
    <div id="flush-collapseTwo" class="accordion-collapse collapse" data-bs-parent="#accordionFlushExample">
      <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the second item’s accordion body. Let’s imagine this being filled with some actual content.</div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseThree" aria-expanded="false" aria-controls="flush-collapseThree">
        Accordion Item #3
      </button>
    </h2>
    <div id="flush-collapseThree" class="accordion-collapse collapse" data-bs-parent="#accordionFlushExample">
      <div class="accordion-body">Placeholder content for this accordion, which is intended to demonstrate the <code>.accordion-flush</code> class. This is the third item’s accordion body. Nothing more exciting happening here in terms of content, but just filling up the space to make it look, at least at first glance, a bit more representative of how this would look in a real-world application.</div>
    </div>
  </div>
</div>

始终打开

省略 data-bs-parent 每个属性 .accordion-collapse 在打开另一个项目时使折叠面板项目保持打开状态。

这是第一个项目的折叠面板内容。 默认情况下它会显示，直到折叠插件添加我们用于样式化每个元素的适当类。这些类控制整体外观，以及通过 CSS 过渡进行显示和隐藏。你可以通过自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中 .accordion-body，尽管过渡确实限制了溢出。

这是第二个项目的折叠面板内容。 默认情况下它是隐藏的，直到折叠插件添加我们用来为每个元素设置样式的适当类。这些类控制整体外观，以及通过 CSS 过渡实现的显示和隐藏。你可以使用自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中。 .accordion-body，尽管过渡确实限制了溢出。

这是第三个项目的折叠面板内容。 默认情况下它是隐藏的，直到折叠插件添加我们用来为每个元素设置样式的适当类。这些类控制整体外观，以及通过 CSS 过渡实现的显示和隐藏。你可以通过自定义 CSS 或覆盖我们的默认变量来修改其中的任何内容。同样值得注意的是，几乎任何 HTML 都可以放在其中 .accordion-body，尽管过渡确实限制了溢出。
HTML
<div class="accordion" id="accordionPanelsStayOpenExample">
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseOne" aria-expanded="true" aria-controls="panelsStayOpen-collapseOne">
        Accordion Item #1
      </button>
    </h2>
    <div id="panelsStayOpen-collapseOne" class="accordion-collapse collapse show">
      <div class="accordion-body">
        <strong>This is the first item’s accordion body.</strong> It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseTwo" aria-expanded="false" aria-controls="panelsStayOpen-collapseTwo">
        Accordion Item #2
      </button>
    </h2>
    <div id="panelsStayOpen-collapseTwo" class="accordion-collapse collapse">
      <div class="accordion-body">
        <strong>This is the second item’s accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#panelsStayOpen-collapseThree" aria-expanded="false" aria-controls="panelsStayOpen-collapseThree">
        Accordion Item #3
      </button>
    </h2>
    <div id="panelsStayOpen-collapseThree" class="accordion-collapse collapse">
      <div class="accordion-body">
        <strong>This is the third item’s accordion body.</strong> It is hidden by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions. You can modify any of this with custom CSS or overriding our default variables. It’s also worth noting that just about any HTML can go within the <code>.accordion-body</code>, though the transition does limit overflow.
      </div>
    </div>
  </div>
</div>

无障碍访问

请阅读 折叠可访问性部分 以获取更多信息。

CSS

变量

在 v5.2.0 中添加

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

scss/_折叠面板.scss
--#{$prefix}accordion-color: #{$accordion-color};
--#{$prefix}accordion-bg: #{$accordion-bg};
--#{$prefix}accordion-transition: #{$accordion-transition};
--#{$prefix}accordion-border-color: #{$accordion-border-color};
--#{$prefix}accordion-border-width: #{$accordion-border-width};
--#{$prefix}accordion-border-radius: #{$accordion-border-radius};
--#{$prefix}accordion-inner-border-radius: #{$accordion-inner-border-radius};
--#{$prefix}accordion-btn-padding-x: #{$accordion-button-padding-x};
--#{$prefix}accordion-btn-padding-y: #{$accordion-button-padding-y};
--#{$prefix}accordion-btn-color: #{$accordion-button-color};
--#{$prefix}accordion-btn-bg: #{$accordion-button-bg};
--#{$prefix}accordion-btn-icon: #{escape-svg($accordion-button-icon)};
--#{$prefix}accordion-btn-icon-width: #{$accordion-icon-width};
--#{$prefix}accordion-btn-icon-transform: #{$accordion-icon-transform};
--#{$prefix}accordion-btn-icon-transition: #{$accordion-icon-transition};
--#{$prefix}accordion-btn-active-icon: #{escape-svg($accordion-button-active-icon)};
--#{$prefix}accordion-btn-focus-box-shadow: #{$accordion-button-focus-box-shadow};
--#{$prefix}accordion-body-padding-x: #{$accordion-body-padding-x};
--#{$prefix}accordion-body-padding-y: #{$accordion-body-padding-y};
--#{$prefix}accordion-active-color: #{$accordion-button-active-color};
--#{$prefix}accordion-active-bg: #{$accordion-button-active-bg};

Sass 变量

scss/_variables.scss
$accordion-padding-y:                     1rem;
$accordion-padding-x:                     1.25rem;
$accordion-color:                         var(--#{$prefix}body-color);
$accordion-bg:                            var(--#{$prefix}body-bg);
$accordion-border-width:                  var(--#{$prefix}border-width);
$accordion-border-color:                  var(--#{$prefix}border-color);
$accordion-border-radius:                 var(--#{$prefix}border-radius);
$accordion-inner-border-radius:           subtract($accordion-border-radius, $accordion-border-width);

$accordion-body-padding-y:                $accordion-padding-y;
$accordion-body-padding-x:                $accordion-padding-x;


$accordion-button-padding-y:              $accordion-padding-y;
$accordion-button-padding-x:              $accordion-padding-x;
$accordion-button-color:                  var(--#{$prefix}body-color);
$accordion-button-bg:                     var(--#{$prefix}accordion-bg);
$accordion-transition:                    $btn-transition, border-radius .15s ease;
$accordion-button-active-bg:              var(--#{$prefix}primary-bg-subtle);
$accordion-button-active-color:           var(--#{$prefix}primary-text-emphasis);


// fusv-disable
$accordion-button-focus-border-color:     $input-focus-border-color; // Deprecated in v5.3.3
// fusv-enable
$accordion-button-focus-box-shadow:       $btn-focus-box-shadow;


$accordion-icon-width:                    1.25rem;
$accordion-icon-color:                    $body-color;
$accordion-icon-active-color:             $primary-text-emphasis;
$accordion-icon-transition:               transform .2s ease-in-out;
$accordion-icon-transform:                rotate(-180deg);


$accordion-button-icon:         url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='#{$accordion-icon-color}' stroke-linecap='round' stroke-linejoin='round'><path d='m2 5 6 6 6-6'/></svg>");
$accordion-button-active-icon:  url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='#{$accordion-icon-active-color}' stroke-linecap='round' stroke-linejoin='round'><path d='m2 5 6 6 6-6'/></svg>");

用法

折叠插件使用几个类来处理繁重的工作：

  • .collapse 隐藏内容
  • .collapse.show 显示内容
  • .collapsing 在过渡开始时添加，完成时移除

这些类可以在_transitions.scss中找到。

通过数据属性

只需在元素上添加data-bs-toggle="collapse"和data-bs-target即可自动分配一个或多个可折叠元素的控制权。data-bs-target属性接受一个 CSS 选择器以应用折叠效果。确保在可折叠元素上添加类collapse。如果希望默认展开，请添加额外的类show。

要向可折叠区域添加折叠面板组管理，请添加数据属性data-bs-parent="#selector"。

通过 JavaScript

手动启用：

const accordionCollapseElementList = document.querySelectorAll('#myAccordion .collapse')
const accordionCollapseList = [...accordionCollapseElementList].map(accordionCollapseEl => new bootstrap.Collapse(accordionCollapseEl))

选项

由于选项可以通过数据属性或 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合并的结果，其中最新提供的键值会覆盖其他键值。

名称类型默认值描述
parent选择器, DOM 元素null如果提供了父元素，则当此可折叠项显示时，指定父元素下的所有可折叠元素都会被关闭。（类似于传统折叠面板行为——这依赖于card类）。该属性必须设置在目标可折叠区域。
togglebooleantrue调用时切换可折叠元素。

方法

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

将你的内容激活为可折叠元素。可以接受可选的选项 object。

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

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
  toggle: false
})
方法描述
dispose销毁元素的折叠。（移除 DOM 元素上存储的数据）
getInstance静态方法，允许你获取与 DOM 元素关联的折叠实例，你可以这样使用它： bootstrap.Collapse.getInstance(element).
getOrCreateInstance静态方法，返回与 DOM 元素关联的折叠实例，如果未初始化则创建一个新的实例。你可以这样使用它： bootstrap.Collapse.getOrCreateInstance(element).
hide隐藏可折叠的元素。 在可折叠元素实际被隐藏之前返回给调用者 （例如，在……之前 hidden.bs.collapse 事件发生)。
show显示一个可折叠的元素。 在可折叠元素实际显示之前返回给调用者 （例如，在……之前 shown.bs.collapse 事件发生)。
toggle切换可折叠元素以显示或隐藏。 在可折叠元素实际显示或隐藏之前返回给调用者 （即在……之前 shown.bs.collapse 或 hidden.bs.collapse 事件发生)。

事件

Bootstrap 的 collapse 类提供了一些事件，用于挂钩到 collapse 功能。

事件类型描述
hide.bs.collapse当调用 hide 方法时，此事件会立即触发。
hidden.bs.collapse当折叠元素对用户隐藏时触发此事件（将等待 CSS 过渡完成）。
show.bs.collapse当调用 show 实例方法时，此事件会立即触发。
shown.bs.collapse当折叠元素对用户可见时触发此事件（将等待 CSS 过渡完成）。
const myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', event => {
  // do something...
})