折叠（Collapse）

在项目中透过Boostrap的类别及JavaScript插件切换内容的可视性。

On this page

工作原理

JavaScript的摺叠插件被用于显示和隐藏内容。按钮、锚被用作为触发器，对应到需要被切换的元素上。折叠一个元素会将它的height从当前的值转换为0。基于CSS处理动画的方式，你不能在带有.collapse的元素上使用padding；相反的，应该把它作为独立的包装元素。

该元件的动画效果取决于prefers-reduced-motion media queries。

例子

点击以下按钮，透过改变Class来显示及隐藏另一个元素：

  • .collapse 隐藏内容。
  • .collapsing 会在转换的过程中被套用。
  • .collapse.show 显示内容。

可以使用带有href属性的连接或是带有data-bs-target属性的按钮。在这两种情形下， 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. 
<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>

多个目标

button或a标签可以用来显示与隐藏元素，需要在它们的data-bs-target或是href属性内部引用选择器。同一个元素可以被多个button或a控制以显示或隐藏，只要它们都有透过data-bs-target或是href对其进行引用。

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. 
<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当前的折叠应用未涵盖WAI-ARIA Authoring Practices 1.1 accordion pattern所描述的多种选择性的键盘操作，你需要自定义JavaScript来实现这些内容。WAI-ARIA Authoring Practices 1.1 accordion pattern

Sass

Variables

$transition-collapse:         height .35s ease;

Classes

Collapse transition classes can be found in scss/_transitions.scss as these are shared across multiple components (collapse and accordion).

.collapse {
        &:not(.show) {
        display: none;
        }
        }
        
        .collapsing {
        height: 0;
        overflow: hidden;
        @include transition($transition-collapse);
        }

用法

折叠插件使用一些类来处理这些繁杂工作。

  • .collapse 隐藏内容。
  • .collapse.show 显示内容。
  • .collapsing 会在转换开始时被加入，并在结束的时候被移除。

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

通过数据属性

只需将data-bs-toggle="collapse"以及data-bs-target加入元素即可自动指定控制一个或多个可折叠元素。data-bs-target属性接受CSS选择器以套用摺叠。请确保有在可折叠元素上添加collapse类别。如果希望它预设是打开的，加上额外的类别.show。

如果要在一个可折叠区域加入可折叠群组，加入data-bs-parent="#selector"数据属性。可以参考示例中的效果。

通过JavaScript

透过以下语法手动启用：

var collapseElementList = [].slice.call(document.querySelectorAll('.collapse'))
        var collapseList = collapseElementList.map(function (collapseEl) {
        return new bootstrap.Collapse(collapseEl)
        })

选项

选项可以透过数据属性或是JavaScript加入。对于数据属性，将选项名称加入data-bs-，如data-bs-parent=""。

Name Type Default Description
parent selector | jQuery object | DOM element false 如果加入了parent，则当可折叠物件为显示时，指定父项下的所有可折叠元素将被关闭。（类似于传统的折叠控件行为-这取决于card）。该属性必须在目标可折叠区域上设置。
toggle boolean true 切换可折叠元素

方法

异步方法和转换

所有API方法都是异步的，并开始转换。转换一开始就返回到调用方，但在转换结束之前返回。此外，对转换组件的方法调用将被忽略。

将内容启用为可折叠元素。接受一个选择性的选项 object。

可以透过建构函式建立一个摺叠示例，举例来说：

var myCollapse = document.getElementById('myCollapse')
        var bsCollapse = new bootstrap.Collapse(myCollapse, {
        toggle: false
        })
Method Description
toggle 将一个可折叠元素切换为显示或隐藏。在可折叠元素实际显示或隐藏之前返回给调用者。（即在shown.bs.collapse 或hidden.bs.collapse 事件发生之前）。
show 显示一个可折叠元素。在可折叠元素实际显示之前返回给调用者。（例如，shown.bs.collapse 事件发生前）.
hide 隐藏一个可折叠元素。在可折叠元素实际被隐藏之前返回给调用者。（例如，在hidden.bs.collapse 事件发生之前）。
dispose 销毁一个元素的折叠。（移除DOM元素上储存的数据）
getInstance 允许你获取与DOM元素关联之折叠示例的静态方法。

事件

ootstrap提供一些事件给折叠组件使用。

Event type Description
show.bs.collapse 当调用show示例方法时，会立即触发此事件。
shown.bs.collapse 当折叠元素显示为可见时，会触发此事件（将等待CSS转换完成）。
hide.bs.collapse 当调用hide方式时，会立即触发此事件。
hidden.bs.collapse 当折叠元素被隐藏时，会触发此事件（将等待CSS转换完成）。 
var myCollapsible = document.getElementById('myCollapsible')
        myCollapsible.addEventListener('hidden.bs.collapse', function () {
        // do something...
        })
返回顶部