跳至主要內容 跳至文件導覽
View on GitHub

摺疊（Collapse）

使用幾個類別和我們的 JavaScript 外掛來切換專案中內容的可見性。

本頁內容

運作原理（How it works）

摺疊 JavaScript 外掛用於顯示和隱藏內容。按鈕或錨點用作觸發器，對應到您要切換的特定元素。摺疊一個元素會將其 height 從當前值動畫過渡到 0。由於 CSS 處理動畫的方式，您不能在 .collapse 元素上使用 padding。請改用該類別作為獨立的包裹元素。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們無障礙文件中的減少動態效果章節。

範例（Example）

點擊下方的按鈕，透過類別變更來顯示和隱藏另一個元素：

  • .collapse 隱藏內容
  • .collapsing 在過渡期間套用
  • .collapse.show 顯示內容

一般來說，我們建議使用帶有 data-bs-target 屬性的 <button>。雖然從語意角度來看不太建議，但您也可以使用帶有 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 class="d-inline-flex gap-1">
  <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>

水平摺疊（Horizontal）

摺疊外掛支援水平摺疊。加入 .collapse-horizontal 修飾類別以過渡 width 而非 height，並在直接子元素上設定 width。您可以自由編寫自己的自訂 Sass、使用行內樣式，或使用我們的寬度通用類別。

請注意，雖然下面的範例設定了 min-height 以避免我們文件中的過度重繪，但這並非必要。只需要在子元素上設定 width。

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>

多重切換與目標（Multiple toggles and targets）

一個 <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.
html 
<p class="d-inline-flex gap-1">
  <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>

無障礙（Accessibility）

請務必在控制元素上加入 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 來實作這些功能。

CSS

Sass 變數（Sass variables）

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

類別（Classes）

摺疊過渡類別可以在 scss/_transitions.scss 中找到，因為它們在多個元件（摺疊和手風琴）之間共用。

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

使用方式（Usage）

摺疊外掛使用幾個類別來處理繁重的工作：

  • .collapse 隱藏內容
  • .collapse.show 顯示內容
  • .collapsing 在過渡開始時加入，並在過渡結束時移除

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

透過 data 屬性（Via data attributes）

只需在元素上加入 data-bs-toggle="collapse" 和 data-bs-target，即可自動指定一個或多個可摺疊元素的控制權。data-bs-target 屬性接受 CSS 選擇器以套用摺疊效果。請務必在可摺疊元素上加入 collapse 類別。如果您希望它預設為開啟，請加入額外的 show 類別。

要在可摺疊區域加入類似手風琴的群組管理，請加入 data 屬性 data-bs-parent="#selector"。請參閱手風琴頁面以獲取更多資訊。

透過 JavaScript（Via JavaScript）

手動啟用：

const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))

選項（Options）

由於選項可以透過 data 屬性或 JavaScript 傳遞，您可以將選項名稱附加到 data-bs-，例如 data-bs-animation="{value}"。透過 data 屬性傳遞選項時，請確保將選項名稱的大小寫類型從「camelCase」更改為「kebab-case」。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

從 Bootstrap 5.2.0 開始，所有元件都支援實驗性的保留 data 屬性 data-bs-config，可以將簡單的元件配置作為 JSON 字串存放。當元素同時具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 屬性時，最終的 title 值將是 456，個別的 data 屬性將覆寫 data-bs-config 中給定的值。此外，現有的 data 屬性也能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最終的配置物件是 data-bs-config、data-bs- 和 js object 的合併結果，其中最後給定的鍵值對會覆寫其他的。

名稱型別預設值說明
parent選擇器、DOM 元素null如果提供 parent，則當此可摺疊項目顯示時，指定父元素下的所有可摺疊元素將被關閉。（類似傳統的手風琴行為──這取決於 card 類別）。該屬性必須設定在目標可摺疊區域上。
toggle布林值true在呼叫時切換可摺疊元素。

方法（Methods）

所有 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切換可摺疊元素為顯示或隱藏。在可摺疊元素實際被顯示或隱藏之前返回給呼叫者（即在 shown.bs.collapse 或 hidden.bs.collapse 事件發生之前）。

事件（Events）

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