折叠(Collapse)组件

使用一些 CSS 类和我们的 JavaScript 插件来切换项目中内容的可见性。

内容提要

工作原理

折叠 JavaScript 插件用于显示和隐藏内容。按钮或 <a> 标签可来触发对应的特定元素的显示或隐藏。折叠一个元素会将 height 从其当前值设置为 0。鉴于 CSS 处理动画的方式，您不能在 .collapse 元素上使用 padding。应将此类用到独立的包裹元素上。

该组件的动画效果依赖于 prefers-reduced-motion 媒体查询。请参阅无障碍文档的减弱动画效果部分。

示例

单击下面的按钮以通过类更改显示和隐藏另一个元素：

内容隐藏的时候，应用 .collapse 类。
动画过程中应用 .collapsing 类。
显示内容的时候，应用 .collapse.show 类。

通常，我们建议使用按钮并添加 data-bs-target 属性。虽然从语义角度不推荐，但您也可以使用链接并设置 href 属性（和 role="button"）。在这两种情况下，都必需设置 data-bs-toggle="collapse" 。

Link with href

Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.

<p>
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
    Link with href
  </a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
    Button with data-bs-target
  </button>
</p>
<div class="collapse" id="collapseExample">
  <div class="card card-body">
    Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
  </div>
</div>

水平折叠

折叠插件还支持水平折叠。添加 .collapse-horizontal 修饰符类以使 width 过渡而不是 height 并在直接子元素上设置 width 。您可以任意自定义 Sass、使用内联样式或使用我们的宽度实用程序。

请注意，虽然下面的示例设置了 min-height 以避免在我们的文档中过度重绘，但这并不是明确要求的。 只有子元素上的 width 是必需的。

This is some placeholder content for a horizontal collapse. It's hidden by default and shown when triggered.

<p>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample">
    Toggle width collapse
  </button>
</p>
<div style="min-height: 120px;">
  <div class="collapse collapse-horizontal" id="collapseWidthExample">
    <div class="card card-body" style="width: 300px;">
      This is some placeholder content for a horizontal collapse. It's hidden by default and shown when triggered.
    </div>
  </div>
</div>

多个目标

<button > 或 <a> 可以通过在其 href 或 data-bs-target 属性中使用引用多个元素的选择器来显示和隐藏多个元素。多个 <button> 或 <a> 可以显示和隐藏一个元素，如果它们各自用它们的 href 或 data 引用它 -bs-target 属性

Toggle first element

Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.

Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.

<p>
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Toggle both elements</button>
</p>
<div class="row">
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample1">
      <div class="card card-body">
        Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample2">
      <div class="card card-body">
        Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
</div>

无障碍

请务必将 aria-expanded 添加到控制元素。此属性将与控件相关联的可折叠元素的当前状态明确传达给屏幕阅读器和类似的辅助技术。如果可折叠元素默认关闭，则控制元素上的属性应具有 aria-expanded="false" 值。如果您使用 show 类将可折叠元素设置为默认打开，请改为在控件上设置 aria-expanded="true"。该插件将根据可折叠元素是否已打开或关闭（通过 JavaScript，或者因为用户触发了另一个也绑定到同一个可折叠元素的控件元素）来自动切换控件上的此属性。如果控制元素的 HTML 元素不是按钮（例如，<a> 或 <div>），属性 role="button" 应该添加到元素中。

如果您的控件元素针对单个可折叠元素 - 即 data-bs-target 属性指向 id 选择器 - 您应该添加 aria-controls 属性到控制的元素，包含可折叠元素的 id。现代屏幕阅读器和类似的辅助技术利用此属性为用户提供额外的快捷方式，以直接导航到可折叠元素本身。

请注意，Bootstrap 的当前实现不涵盖 WAI-ARIA 创作实践 1.1 accordion 模式中描述的各种可选键盘交互。您需要自己将这些包含在自定义 JavaScript 中。

Sass

变量

$transition-collapse:         height .35s ease;
$transition-collapse-width:   width .35s ease;

类

折叠过渡类可以在 css/transitions.scss 中找到，因为它们在多个组件（折叠和手风琴）之间共享。

.collapse {
  &:not(.show) {
    display: none;
  }
}

.collapsing {
  height: 0;
  overflow: hidden;
  @include transition($transition-collapse);

  &.collapse-horizontal {
    width: 0;
    height: auto;
    @include transition($transition-collapse-width);
  }
}

用法

崩溃插件利用几个类来处理繁重的工作：

.collapse 隐藏内容
.collapse.show 显示内容
.collapsing 在过渡开始时添加，并在过渡结束时删除

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

通过 `data` 属性

只需将 data-bs-toggle="collapse" 和 data-bs-target 添加到元素中，即可自动分配对一个或多个可折叠元素的控制。 data-bs-target 属性接受一个 CSS 选择器来应用折叠。请务必将类 collapse 添加到可折叠元素。如果您希望它默认打开，请添加附加类 show。

要将手风琴式的组管理添加到可折叠区域，请添加数据属性 data-bs-parent="#selector"。有关详细信息，请参阅手风琴页面。

使用 JavaScript

使用下面的代码手动启用：

var collapseElementList = [].slice.call(document.querySelectorAll('.collapse'))
var collapseList = collapseElementList.map(function (collapseEl) {
  return new bootstrap.Collapse(collapseEl)
})

选项(Options)

选项可以通过数据属性或 JavaScript 传递。对于数据属性，将选项名称附加到 data-bs-，如 data-bs-parent=""。

名称	类型	默认值	描述
`parent`	selector \| jQuery object \| DOM element	`false`	如果提供了父(parent)，则在显示此可折叠项时，将关闭指定父项下的所有可折叠元素。（类似于传统的手风琴行为 - 这取决于 `card` 类）。该属性必须在可折叠区域上设置。
`toggle`	boolean	`true`	在调用时切换可折叠元素

方法(Methods)

异步方法和过渡

所有 API 方法都是异步的并启动过渡。它们会在过渡开始后但在过渡结束之前返回给调用者。此外，转换组件上的方法调用将被忽略。

有关更多信息，请参阅我们的 JavaScript 文档。

激活可折叠元素。接受可选选项object。

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

var myCollapse = document.getElementById('myCollapse')
var bsCollapse = new bootstrap.Collapse(myCollapse, {
  toggle: false
})

方法	描述
`toggle`	将可折叠元素切换为显示或隐藏。在可折叠元素实际显示或隐藏之前返回调用者（即在`shown.bs.collapse`或`hidden.bs.collapse` 事件发生之前）。
`show`	显示可折叠元素。在可折叠元素实际显示之前返回调用者（例如，在 `shown.bs.collapse` 事件发生之前）。
`hide`	隐藏可折叠元素。在可折叠元素实际隐藏之前返回调用者（例如，在 `hidden.bs.collapse` 事件发生之前）。
`dispose`	销毁元素的折叠。（删除 DOM 元素上存储的数据）
`getInstance`	允许您获取与 DOM 元素关联的折叠实例的静态方法，您可以像这样使用它：`bootstrap.Collapse.getInstance(element)`
`getOrCreateInstance`	静态方法，它返回与 DOM 元素关联的折叠实例，或者在未初始化的情况下创建一个新实例。你可以像这样使用它：`bootstrap.Collapse.getOrCreateInstance(element)`

事件(Events)

Bootstrap 折叠类公开了一些在折叠功能内部某一特定时刻触发的事件。

事件类型	描述
`show.bs.collapse`	此事件在调用 `show` 实例方法时立即触发。
`shown.bs.collapse`	当折叠元素对用户可见时触发此事件（将等待 CSS 过渡完成）。
`hide.bs.collapse`	当调用 `hide` 方法时，会立即触发此事件。
`hidden.bs.collapse`	当对用户隐藏折叠元素时会触发此事件（将等待 CSS 过渡完成）。

var myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', function () {
  // do something...
})