跳到主要内容 跳到文档导航
Check
in English

坍塌

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

这个怎么运作

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

该组件的动画效果依赖于 prefers-reduced-motion媒体查询。请参阅 我们可访问性文档的减少运动部分

例子

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

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

通常,我们建议使用带有data-bs-target属性的按钮。虽然从语义角度不推荐,但您也可以使用带有href属性(和 a role="button")的链接。在这两种情况下,data-bs-toggle="collapse"都是必需的。

Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
html
<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设置 a 。width随意编写您自己的自定义 Sass、使用内联样式或使用我们的宽度实用程序

请注意,虽然下面的示例有一 min-height组以避免我们的文档中过度重绘,但这并不是明确要求的。 只有widthon 子元素是必需的。

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>or可以通过<a>在其hrefordata-bs-target属性中使用选择器引用多个元素来显示和隐藏多个元素。多个<button>or<a>可以显示和隐藏一个元素,如果它们每个都用它们的hrefordata-bs-target属性引用它

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>
  <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 中。

萨斯

变量

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

课程

Collapse 过渡类可以在其中找到,scss/_transitions.scss因为它们在多个组件(collapse 和手风琴)之间共享。

.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"和 adata-bs-target即可自动分配对一个或多个可折叠元素的控制。该data-bs-target属性接受一个 CSS 选择器来应用折叠。确保将类添加collapse到可折叠元素。如果您希望它默认打开,请添加附加类show

要将手风琴式的组管理添加到可折叠区域,请添加 data 属性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并且单独的数据属性将覆盖给定的值 on data-bs-config。此外,现有数据属性能够容纳 JSON 值,例如data-bs-delay='{"show":0,"hide":150}'.

姓名 类型 默认 描述
parent 选择器,DOM 元素 null 如果提供了 parent,则在显示此可折叠项时,将关闭指定父项下的所有可折叠元素。(类似于传统的手风琴行为 - 这取决于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 将可折叠元素切换为显示或隐藏。在可折叠元素实际显示或隐藏之前(即在or事件发生之前)返回给调用者。shown.bs.collapsehidden.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...
})