它是如何工作的
折叠 JavaScript 插件用于显示和隐藏内容。按钮或链接用作触发器，这些触发器映射到你切换的特定元素。该插件仅添加和移除 .show——CSS从…动画化尺寸 0 根据内容大小。鉴于 CSS 处理动画的方式，你无法使用 padding 在一个 .collapse 元素。相反，使用该类作为独立的包装元素。
动画需要 interpolate-size。不支持它的浏览器会立即打开和关闭元素。请参阅 过渡 以更改时间或将其移除。
此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们无障碍文档中的 减少动画部分。
示例
点击下面的按钮，通过类的变化显示和隐藏另一个元素：
.collapse隐藏内容.collapse.show显示内容
通常，我们建议使用一个 <button> 和 data-bs-target 属性。虽然从语义角度来看不推荐，但你也可以使用一个 <a> 与……联系 href 属性（和一个 role="button"）。在这两种情况下， data-bs-toggle="collapse" 是必需的。
<p class="d-inline-flex gap-1">
<a class="btn-solid theme-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
Link with href
</a>
<button class="btn-solid theme-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。你可以随意编写自己的自定义 Sass、使用内联样式或使用我们的 宽度工具。
请注意，虽然下面的示例中的 min-height 设置是为了避免我们文档中过多的重绘，但这并不是强制要求。只有子元素上的 width 是必需的。
<p>
<button class="btn-solid theme-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: 140px;">
<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 属性中引用同一个元素，它们也可以显示和隐藏该元素。
<p class="d-inline-flex gap-1">
<a class="btn-solid theme-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a>
<button class="btn-solid theme-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button>
<button class="btn-solid theme-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"添加到该元素。
折叠触发状态由 aria-expanded 表示。
如果你的控件元素针对单个可折叠元素——即 data-bs-target 属性指向一个 id 选择器——你应在控件元素上添加 aria-controls 属性，其中包含可折叠元素的 id。现代屏幕阅读器及类似辅助技术会使用此属性，为用户提供额外的快捷方式，直接导航到可折叠元素本身。
请注意，Bootstrap 当前的实现并未涵盖各种 可选 在……中描述的键盘交互 ARIA 编写规范指南 折叠面板模式 - 你将需要使用自定义 JavaScript 自行包含这些内容。
CSS
Sass 变量
// stylelint-disable custom-property-no-missing-var-function
$collapse-tokens: defaults(
(
--transition-collapse-property: "block-size, display",
--transition-collapse-duration: .35s,
--transition-collapse-timing: ease,
),
$collapse-tokens
);
// stylelint-enable custom-property-no-missing-var-function
课程
折叠过渡类可以在 scss/_transitions.scss 中找到，因为它们在多个组件（折叠和折叠面板）之间是共享的。
// The browser animates the size itself. `interpolate-size` lets the `0` of the
// closed state interpolate to the `auto` of the open one, and `display`
// transitions discretely, so the element stays laid out until the size reaches
// `0`. The animated axis is clipped, so the content cannot spill while it moves.
.collapse {
@include tokens($collapse-tokens);
overflow-y: clip;
@include transition-props(
var(--transition-collapse-property),
var(--transition-collapse-duration),
var(--transition-collapse-timing),
allow-discrete
);
// Browsers without `interpolate-size` open and close the element at once.
@media (prefers-reduced-motion: no-preference) {
interpolate-size: allow-keywords;
}
&:not(.show) {
display: none;
block-size: 0;
}
// A closed collapse is not rendered, so the open side needs a start value of
// its own. Without it the element appears at full size at once.
&.show {
@starting-style {
block-size: 0;
}
}
// Horizontal collapses animate the inline size instead. The open size is
// `fit-content`, so the element is as wide as its content, not as wide as its
// container.
&.collapse-horizontal {
--transition-collapse-property: inline-size, display;
inline-size: fit-content;
overflow-x: clip;
overflow-y: visible;
&:not(.show) {
inline-size: 0;
block-size: auto;
}
&.show {
@starting-style {
inline-size: 0;
}
}
}
}
用法
折叠插件使用两个类来处理繁重的工作：
.collapse隐藏内容.collapse.show显示内容
这些类可以在 _transitions.scss 中找到。插件切换 .show，然后等待 CSS 过渡完成，之后才触发 shown.bs.collapse 或 hidden.bs.collapse。
通过数据属性
只需在元素上添加data-bs-toggle="collapse"和data-bs-target即可自动分配一个或多个可折叠元素的控制权。data-bs-target属性接受一个 CSS 选择器以应用折叠效果。确保在可折叠元素上添加类collapse。如果希望默认展开，请添加额外的类show。
要为可折叠区域添加折叠面板式的组管理，请添加数据属性 data-bs-parent="#selector"。有关更多信息，请参阅 折叠面板页面。
| 属性 | 描述 |
|---|---|
data-bs-toggle="collapse" | 在触发元素上初始化折叠插件。 |
data-bs-target | 用于展开和折叠元素的 CSS 选择器。 |
data-bs-parent | 当设置在可折叠元素上时，关闭同一父元素下的兄弟折叠（折叠面板行为）。 |
通过 JavaScript
手动启用：
const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))
依赖项
如果你从源代码构建 Bootstrap 的 JS，折叠插件需要以下 JavaScript 文件：
| 文件 | 描述 |
|---|---|
js/src/collapse.ts | 主要坍塌组件 |
js/src/base-component.ts | 基础组件类 |
js/src/dom/data.ts | 元素数据存储 |
js/src/dom/event-handler.ts | 事件处理工具 |
js/src/dom/manipulator.ts | 数据属性操作 |
js/src/dom/selector-engine.ts | DOM选择器工具 |
js/src/util/config.ts | 配置基类 |
js/src/util/index.ts | 核心实用功能 |
选项
由于选项可以通过数据属性或 JavaScript 传递，你可以将选项名称附加到 data-bs-，就像在 data-bs-animation="{value}" 中一样。确保在通过数据属性传递选项时，将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。
所有组件都支持一个保留的数据属性 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 | 如果提供了 parent，那么当此可折叠项显示时，所有指定父元素下的可折叠元素将被关闭。（类似于传统折叠面板行为——这依赖于 card 类）。该属性必须设置在目标可折叠区域。 |
方法
显示或隐藏组件的方法会返回一个 Promise。 当过渡结束时，该 Promise 会被解析，所以 await 会在 shown.bs.* 或 hidden.bs.* 监听器运行的同一时刻继续。方法仍会立即返回，并且永远不会阻塞调用者。对已在过渡中的组件进行调用不会有任何效果，并会立即解析。在我们的 JavaScript 文档中了解更多。
将你的内容激活为可折叠元素。可以接受可选的选项 object。
构造函数保持你的标记声明的状态。添加.show以打开元素，不添加则保持元素关闭。调用show()、hide()或toggle()以更改状态。
const bsCollapse = new bootstrap.Collapse('#myCollapse')
bsCollapse.show()
| 方法 | 描述 |
|---|---|
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...
})