View on GitHub

折疊 (Collapse)

在專案中透過 Boostrap 的類別及 JavaScript 插件切換內容的可視性。

六角學院的 Bootstrap 5 課程上線囉，立即與萬人一同學習最專業、最深入的 Bootstrap 5 課程。

On this page

如何運作

JavaScript 的摺疊插件被用於顯示和隱藏內容。按鈕、錨點被用作為觸發器，對應到需要被切換的元素上。折疊一個元素會將它的 height 從當前的值轉換為 0。基於 CSS 處理動畫的方式，你不能在帶有 .collapse 的元素上使用 padding; 相反的，應該把它作為獨立的包裝元素。

該元件的動畫效果取決於 prefers-reduced-motion media queries。請參考 reduced motion section of our accessibility documentation

範例

點擊以下按鈕，透過改變 Class 來顯示及隱藏另一個元素：

.collapse 隱藏內容。
.collapsing 會在轉換的過程中被套用。
.collapse.show 顯示內容。

通常，我們建議使用帶有 data-bs-target 屬性的按鈕。從語義的角度來看，雖然不建議這樣做，但您也可以使用帶有 href 屬性 (和 role="button" ) 的連結。在這兩種情況下，都需要 data-bs-toggle="collapse"。

Link with href

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>

水平

Collapse 也支持水平折疊。添加 .collapse-horizontal 類別來轉換 width 而不是 height，並在子元素上設定 width。隨意撰寫你自己的自定義 Sass、使用行內樣式或是我們的 width 通用類別.

請注意，雖然下面的範例設定了 min-height，但這只是避免在我們的文檔中過度重繪，並不是明確要求的。 只需要子元素的 width 就好。

This is some placeholder content for a horizontal collapse. It's hidden by default and shown when triggered.

<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 對其進行引用。

Toggle first element

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 來實現這些內容。

Sass

Variables

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

Classes

Collapse transition 類別可以在 scss/_transitions.scss 中找到，因為它們在多個元件之間共享 (collapse 和 accordion)。

.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);
  }
}

用法

折疊插件使用一些 Class 來處理這些繁雜工作。

.collapse 隱藏內容。
.collapse.show 顯示內容。
.collapsing 會在轉換開始時被加入，並在結束的時候被移除。

這些類別可以在 _transitions.scss 中被找到.

透過資料屬性

只需將 data-bs-toggle="collapse" 以及 data-bs-target 加入元素即可自動指定控制一個或多個可折疊元素。data-bs-target 屬性接受 CSS 選擇器以套用摺疊。請確保有在可折疊元素上添加 collapse 類別。如果希望它預設是打開的，加上額外的類別 .show。

要將 accordion-like group management 加到可折疊區域，請添加 data 屬性 data-bs-parent="#selector"。關於更多詳細資訊，請參閱 accordion 頁面。

透過 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`	切換可折疊元素

方法

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

將內容啟用為可摺疊元素。接受一個選擇性的選項 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 元素相關的 collapse 實例的靜態方法，你可以使用像是：`bootstrap.Collapse.getInstance(element)`
`getOrCreateInstance`	靜態方法，允許你獲取與 DOM 元素相關的 collapse 實例，或者在未初始化的情況下創建一個新實例。你可以使用像是：`bootstrap.Collapse.getOrCreateInstance(element)`

事件

Bootstrap 提供一些事件給予折疊使用。

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...
})