摺疊

透過幾個類別和我們的 JavaScript 外掛，在專案中切換內容的可見度。

在此頁面中

運作方式

Collapse JavaScript 外掛用於顯示和隱藏內容。按鈕或錨點用作觸發器，對應到您切換的特定元素。摺疊元素會將 height 從目前的數值動畫到 0。考量到 CSS 處理動畫的方式，您無法在 .collapse 元素上使用 padding。相反地，將類別用作獨立的包裝元素。

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

範例

按一下下列按鈕，透過類別變更顯示和隱藏另一個元素

.collapse 隱藏內容
.collapsing 適用於轉場期間
.collapse.show 顯示內容

一般來說，我們建議使用具有 data-bs-target 屬性的 <button>。雖然從語意觀點來看不建議這麼做，但您也可以使用具有 href 屬性（以及 role="button"）的 <a> 連結。在兩種情況下，都需要 data-bs-toggle="collapse"。

具有 href 的連結

折疊元件的一些佔位內容。此面板在預設情況下為隱藏，但在使用者啟動相關觸發器時會顯示。

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>

水平

折疊外掛程式支援水平折疊。加入 .collapse-horizontal 修飾詞類別，以轉換 width 而不是 height，並在直接子元素上設定 width。您可以自由撰寫自己的自訂 Sass、使用內嵌樣式，或使用我們的寬度工具。

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

這是水平折疊的一些佔位內容。它在預設情況下為隱藏，且在觸發時顯示。

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> 或 <a> 元素可透過在 data-bs-target 或 href 屬性中參照選取器來顯示和隱藏多個元素。相反地，如果多個 <button> 或 <a> 元素各自透過 data-bs-target 或 href 屬性參照同一個元素，則可顯示和隱藏同一個元素。

切換第一個元素

這個多重收合範例的第一個收合元件的一些佔位符內容。這個面板預設為隱藏，但在使用者啟用相關觸發器時會顯示。

這個多重收合範例的第二個收合元件的一些佔位符內容。這個面板預設為隱藏，但在使用者啟用相關觸發器時會顯示。

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>

無障礙

務必將 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 變數

scss/_variables.scss

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

類別

收合轉場類別可以在 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);
  }
}

用法

收合外掛程式使用幾個類別來處理繁重的工作

.collapse 隱藏內容
.collapse.show 顯示內容
轉場開始時新增 .collapsing，完成時移除

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

透過資料屬性

只要將 data-bs-toggle="collapse" 和 data-bs-target 新增到元素中，即可自動指定一個或多個可摺疊元素的控制權。data-bs-target 屬性接受 CSS 選擇器以套用摺疊。務必將 collapse 類別新增到可摺疊元素。如果你希望它預設為開啟狀態，請新增其他類別 show。

若要將手風琴式群組管理新增到可摺疊區域，請新增資料屬性 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，而個別資料屬性將覆寫 data-bs-config 中給定的值。此外，現有的資料屬性能夠存放 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

最後設定物件是 data-bs-config、data-bs- 和 js 物件 的合併結果，其中最後給定的金鑰值會覆寫其他值。

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

方法

所有 API 方法都是非同步的，並會開始轉換。它們在轉換開始後立即傳回呼叫者，但在轉換結束之前。此外，在轉換元件上的方法呼叫會被忽略。在我們的 JavaScript 文件中了解更多資訊。

將您的內容作為可收合元素啟用。接受一個選用的選項 物件。

您可以使用建構函式建立一個收合實例，例如

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
  toggle: false
})

方法	說明
`dispose`	銷毀元素的收合。（移除儲存在 DOM 元素上的資料）
`getInstance`	靜態方法，讓您可以取得與 DOM 元素關聯的收合實例，您可以這樣使用它：`bootstrap.Collapse.getInstance(element)`。
`getOrCreateInstance`	靜態方法，傳回與 DOM 元素關聯的收合實例，或是在尚未初始化的情況下建立新的實例。您可以像這樣使用它：`bootstrap.Collapse.getOrCreateInstance(element)`。
`隱藏`	隱藏可收合元素。在可收合元素實際隱藏之前傳回呼叫者（例如，在 `hidden.bs.collapse` 事件發生之前）。
`顯示`	顯示可收合元素。在可收合元素實際顯示之前傳回呼叫者（例如，在 `shown.bs.collapse` 事件發生之前）。
`toggle`	切換可收合元素為顯示或隱藏。在可收合元素實際顯示或隱藏之前傳回呼叫者（即在 `shown.bs.collapse` 或 `hidden.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...
})