折叠

通过几个类和我们的 JavaScript 插件切换整个项目中内容的可见性。

本页目录

它是如何工作的

折叠 JavaScript 插件用于显示和隐藏内容。按钮或锚点用作触发器，它们映射到你切换的特定元素。折叠一个元素将会动画化 height 从其当前值到 0. 鉴于 CSS 处理动画的方式，你无法使用 padding 在一个 .collapse 元素。相反，使用该类作为独立的包装元素。

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

示例

点击下面的按钮，通过类的变化显示和隐藏另一个元素：

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

通常，我们建议使用一个 <button> 和 data-bs-target 属性。虽然从语义角度来看不推荐，但你也可以使用一个 <a> 与……联系 href 属性（和一个 role="button"）。在这两种情况下， 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 上给定的值。此外，现有的数据属性也能够存放如 data-bs-delay='{"show":0,"hide":150}' 的 JSON 值。

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

名称	类型	默认值	描述
`parent`	选择器, DOM 元素	`null`	如果提供了父元素，则当此可折叠项显示时，指定父元素下的所有可折叠元素都会被关闭。（类似于传统折叠面板行为——这依赖于`card`类）。该属性必须设置在目标可折叠区域。
`toggle`	boolean	`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 的 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...
})