折叠（Collapse）

只需几个类和我们的 JavaScript 插件，就能在整个项目中切换内容的可见性。

On this page

工作原理

折叠 JavaScript 插件用于显示和隐藏内容。按钮或锚点可用作触发器，映射到您切换的特定元素。折叠元素时，height 会从当前值动画为 0。考虑到 CSS 处理动画的方式，你不能在.collapse元素上使用padding。相反，请将该类用作独立的包装元素。

该组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们的可访问性文档中的缩减动作部分.

示例

点击下面的按钮，通过更改类来显示或隐藏另一个元素：

.collapse 隐藏内容
.collapsing 在过渡期间应用
.collapse.show 显示内容

一般来说，我们建议使用带有 data-bs-target 属性的 <button>。虽然从语义的角度来看并不推荐，但您也可以使用带有 href 属性（和 role="button"）的 <a> 链接。在这两种情况下，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.

html

<p class="d-inline-flex gap-1">
  <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.

html

<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> 元素可以通过在其 data-bs-target 或 href 属性中使用选择器来引用多个元素，从而显示或隐藏多个元素。相反，如果多个 <button> 或 <a> 元素都使用 data-bs-target 或 href 属性引用同一个元素，那么它们就可以显示和隐藏同一个元素。

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.

html

<p class="d-inline-flex gap-1">
  <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 当前的实现并不包括 ARIA 创作实践指南 accordion 模式中描述的各种可选键盘交互 - 您需要使用自定义 JavaScript 自行包含这些交互。

CSS

Sass 变量

scss/_variables.scss

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

类

折叠过渡类可在 scss/_transitions.scss 中找到，因为这些类在多个组件（折叠和手风琴）中共享。

scss/_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 会在过渡开始时添加，并在过渡结束时移除

These classes can be found in _transitions.scss.

通过数据属性

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

要为可折叠区域添加类似手风琴的分组管理，请添加数据属性 data-bs-parent="#selector" 。更多信息请参阅accordion 页面。

通过 JavaScript

通过以下方式手动启用

const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))

选项

由于可以通过 data 属性或 JavaScript 传递选项，因此可以在 data-bs- 中附加选项名称，如 data-bs-animation=“{value}”。通过data 属性传递选项时，请确保将选项名称的大小写类型从“camelCase”改为“kebab-case”。例如，使用 data-bs-custom-class=“beautifier” 而不是 data-bs-customClass=“beautifier”。

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

Name	Type	Default	Description
`parent`	selector, DOM element	`null`	如果提供了父元素，则在显示此可折叠项时，指定父元素下的所有可折叠元素都将关闭。(类似于传统的手风琴行为–这取决于 `card` 类）。必须在目标可折叠区域上设置该属性。
`toggle`	boolean	`true`	在调用时切换可折叠元素。

方法

所有 API 方法都是异步的，并且会启动一个过渡，它们会在过渡开始后、结束前返回给调用者。此外，对过渡组件的方法调用将被忽略。更多信息，请参阅 JavaScript 文档

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

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

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
  toggle: false
})

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

事件

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

Event type	Description
`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...
})