折叠

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

此页面上的内容

工作原理

折叠 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"。

带有 href 的链接

折叠组件的一些占位符内容。此面板默认隐藏，但在用户激活相关触发器时显示。

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。

这是水平折叠的一些占位符内容。它默认隐藏，在触发时显示。

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 属性引用同一个元素，则它们可以显示和隐藏同一个元素。

切换第一个元素

此多折叠示例的第一个折叠组件的一些占位符内容。此面板默认隐藏，但在用户激活相关触发器时显示。

此多折叠示例的第二个折叠组件的一些占位符内容。此面板默认隐藏，但在用户激活相关触发器时显示。

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 创作实践指南手风琴模式中描述的各种可选键盘交互 - 你需要使用自定义 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，完成后将其删除

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

通过数据属性

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

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

通过 JavaScript

手动启用

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

选项

由于选项可以通过数据属性或 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 上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最终的配置对象是 data-bs-config、data-bs- 和 js 对象 的合并结果，其中最后给出的键值会覆盖其他键值。

名称	类型	默认值	描述
`parent`	选择器、DOM 元素	`null`	如果提供了父级，则在显示此可折叠项时，指定父级下的所有可折叠元素都将关闭。（类似于传统的手风琴行为 - 这取决于 `card` 类）。该属性必须设置在目标可折叠区域上。
`toggle`	布尔值	`true`	在调用时切换可折叠元素。

方法

所有 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 的折叠类公开了几个事件，用于挂接到折叠功能。

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