bootstrap_ref_js_collapse

Bootstrap 5 JS 折叠插件

JS 折叠插件 (collapse.js)

折叠（Collapse）JavaScript 插件允许你切换内容的可见性。它非常适合创建手风琴（accordions）和可展开的导航菜单。

Bootstrap 的 JavaScript 组件，包括 Collapse，通常包含在 bootstrap.bundle.min.js 中，这个文件也捆绑了 Popper.js（工具提示和弹出框的依赖项，但 Collapse 不需要直接依赖它）。过渡效果是 Bootstrap 核心 CSS/JS 的一部分。

折叠插件类

类描述示例

.collapse 默认隐藏内容。 尝试：添加到 <div> 元素使其可折叠。

.collapse.show 默认显示内容。（取代了旧的 .collapse.in） 尝试：添加到可折叠的 <div> 元素使其初始可见。

.collapsing 在过渡期间（打开或关闭时）由 Bootstrap 自动应用。 这个类由插件管理。

通过 `data-bs-*` 属性

你可以使用 data-bs-* 属性轻松控制可折叠元素，无需编写任何 JavaScript 代码。将 data-bs-toggle="collapse" 添加到按钮或链接，将 data-bs-target="#selector" 指向可折叠元素的 ID。可折叠元素本身必须带有 .collapse 类。若要使其默认打开，还需要添加 .show 类。

对于手风琴式的分组管理（组中一个项目打开时会关闭其他项目），将 data-bs-parent="#selector" 属性添加到每个可折叠项目触发器上，并指向一个共同的父元素。

实际应用：非常适合 FAQ（常见问题）部分，点击问题即可显示答案。

通过 JavaScript

使用 JavaScript 手动启用折叠功能：

// 初始化一个折叠元素
const myCollapseElement = document.getElementById('myCollapsibleElement');
const bsCollapse = new bootstrap.Collapse(myCollapseElement, {
  toggle: false // 设置为 false 可防止在初始化时切换状态
});

// 后续切换状态：
bsCollapse.toggle();

// 显示：
bsCollapse.show();

// 隐藏：
bsCollapse.hide();

// 销毁折叠实例：
bsCollapse.dispose();

// 对于所有折叠触发器：
const collapseTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="collapse"]'));
const collapseList = collapseTriggerList.map(function (collapseTriggerEl) {
  // 你可能希望从 data-bs-target 获取目标元素并初始化它
  // 这个例子只展示了从触发器初始化，这可能不是你直接操作所需的方式。
  // 最好是直接初始化可折叠元素。
  return new bootstrap.Collapse(collapseTriggerEl); // 或者更好的做法：new bootstrap.Collapse(document.querySelector(collapseTriggerEl.getAttribute('data-bs-target')))
});

// 常见障碍：确保初始化时指向正确的元素。总是初始化可折叠内容元素，而不仅仅是触发器。

折叠选项

选项可以通过 data-bs-* 属性或 JavaScript 传递。对于 data 属性，将选项名称附加到 data-bs- 后面，例如 data-bs-parent=""。

名称类型默认值描述 (Bootstrap 5)

parent selector | DOM element | jQuery object null 如果提供选择器或 DOM 节点，当此可折叠项显示时，指定父元素下的所有可折叠元素都将关闭。（这是手风琴行为的核心）。使用 data-bs-parent 属性。

toggle boolean true 在调用时切换可折叠元素（即，当通过 JavaScript 初始化且此选项为 true 时，将切换状态）。

折叠方法

下表列出了所有可用的折叠方法。这些方法在 Collapse 实例上调用（例如，bsCollapse.toggle()）。

方法描述

toggle() 切换可折叠元素显示或隐藏状态。

show() 显示可折叠元素。

hide() 隐藏可折叠元素。

dispose() 销毁元素的折叠功能。（移除 DOM 元素上存储的数据）

getInstance(element) 静态方法，允许你获取与 DOM 元素关联的折叠实例。

getOrCreateInstance(element, [config]) 静态方法，允许你获取与 DOM 元素关联的折叠实例，如果尚未初始化则创建新的实例。

折叠事件

Bootstrap 的折叠插件会触发一些事件，以便你可以挂钩到折叠功能。所有事件都在可折叠元素本身上触发（例如，<div class="collapse">）。

事件描述 Vanilla JS 示例

show.bs.collapse 当调用 show 实例方法时，此事件会立即触发。 myCollapsibleElement.addEventListener('show.bs.collapse', function () { /* 执行操作 */ })

shown.bs.collapse 当折叠元素对用户可见时（会等待 CSS 过渡完成），此事件会触发。 myCollapsibleElement.addEventListener('shown.bs.collapse', function () { /* 执行操作 */ })

hide.bs.collapse 当调用 hide 方法时，此事件会立即触发。 myCollapsibleElement.addEventListener('hide.bs.collapse', function () { /* 执行操作 */ })

hidden.bs.collapse 当折叠元素对用户隐藏时（会等待 CSS 过渡完成），此事件会触发。 myCollapsibleElement.addEventListener('hidden.bs.collapse', function () { /* 执行操作 */ })

学习技巧：使用这些事件来触发其他操作，例如在显示某个部分时动态加载内容，或者更改触发按钮上的图标。

简单折叠示例

以下示例展示了如何通过一个按钮切换另一个元素内容的展开和折叠状态：

<button class="btn btn-info" type="button" data-bs-toggle="collapse" data-bs-target="#demoContent" aria-expanded="false" aria-controls="demoContent">
  Simple collapsible
</button>

<div class="collapse" id="demoContent">
  <div class="card card-body mt-2">
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  </div>
</div>

<!-- 若要使其默认打开，请将 #demoContent div 上的 class="collapse" 改为 class="collapse show" -->

手风琴（使用 Bootstrap 5 卡片和手风琴组件）

以下示例展示了一个简单的手风琴。Bootstrap 5 提供了专门的手风琴类，它们构建于折叠插件和卡片组件之上。

<div class="accordion" id="accordionExample">
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingOne">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
        Collapsible Group Item #1
      </button>
    </h2>
    <div id="collapseOne" class="accordion-collapse collapse show" aria-labelledby="headingOne" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        **This is the first item's accordion body.** It is shown by default, until the collapse plugin adds the appropriate classes that we use to style each element. These classes control the overall appearance, as well as the showing and hiding via CSS transitions.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingTwo">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
        Collapsible Group Item #2
      </button>
    </h2>
    <div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        **This is the second item's accordion body.** It is hidden by default. The <code>.accordion-button</code> gets an arrow icon automatically via CSS, which rotates when collapsed/expanded.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingThree">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
        Collapsible Group Item #3
      </button>
    </h2>
    <div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        **This is the third item's accordion body.** This item is also hidden by default.
      </div>
    </div>
  </div>
</div>

<!-- 资源：有关手风琴的更多信息，请访问 https://getbootstrap.com/docs/5.3/components/accordion/ -->

展开和折叠切换图标与文本（现代方法）

Bootstrap 5 的 .accordion-button 会自动处理一个默认的chevron图标。如果对于非手风琴的折叠功能，你需要自定义图标或更改文本，可以使用 JavaScript 事件监听器。Glyphicons 不再是 Bootstrap 的一部分；考虑使用 Bootstrap Icons (SVGs) 或其他图标库。

<!-- 自定义切换按钮和内容的 HTML -->
<button id="customToggleButton" class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#customCollapseContent" aria-expanded="false" aria-controls="customCollapseContent">
  <!-- Bootstrap 图标（示例，请确保已包含 Bootstrap Icons CSS/SVG sprite） -->
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-chevron-down me-2" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>
  <span>Open</span>
</button>
<div class="collapse" id="customCollapseContent">
  <div class="card card-body mt-2">
    Content here.
  </div>
</div>

<script>
document.addEventListener('DOMContentLoaded', function () {
  const collapseElement = document.getElementById('customCollapseContent');
  const buttonElement = document.getElementById('customToggleButton');
  const buttonIcon = buttonElement.querySelector('svg'); // 或你的图标元素
  const buttonTextSpan = buttonElement.querySelector('span');

  collapseElement.addEventListener('show.bs.collapse', function () {
    buttonTextSpan.textContent = 'Close';
    if (buttonIcon) {
        // 示例：旋转图标或更改为不同的图标
        buttonIcon.style.transform = 'rotate(180deg)';
        // 对于 Bootstrap Icons，你可以通过交换类名来使用不同的图标：
        // buttonIcon.classList.remove('bi-chevron-down');
        // buttonIcon.classList.add('bi-chevron-up');
    }
  });

  collapseElement.addEventListener('hide.bs.collapse', function () {
    buttonTextSpan.textContent = 'Open';
    if (buttonIcon) {
        buttonIcon.style.transform = 'rotate(0deg)';
        // buttonIcon.classList.remove('bi-chevron-up');
        // buttonIcon.classList.add('bi-chevron-down');
    }
  });
});
</script>

<!-- 注意：图标 SVG 仅为示例。为了更清晰地管理图标，请考虑使用 Bootstrap Icons：https://icons.getbootstrap.com/ -->