メインコンテンツへスキップ

折り畳み(Collapse) v5.0.0-beta1設定変更

少しのクラスとJavaScriptプラグインを使用して、プロジェクト全体のコンテンツの可視性を切り替える。

概要(How it works)

折り畳み式のJavaScriptプラグインは、コンテンツの表示と非表示に使用。ボタンやアンカーは、切り替える特定の要素にマップされるトリガーとして使用。要素を折り畳むと、height が現在の値から 0 にアニメーション化される。CSSがアニメーションを処理する方法を考えると .collapse 要素に padding は使用不可。代わりのクラスを独立したラッピング要素に使用すること。

 

基本の設定(Example)

以下のボタンをクリックすると、クラスを変更して他の要素を表示したり非表示にする:

  • .collapse でコンテンツを隠す
  • 遷移中に .collapsing が適用される
  • .collapse.show でコンテンツを表示

通常、data-bs-target 属性を持つボタンの使用を推奨。セマンティックの観点からは推奨されないが、href 属性(と role="button")を持つリンクでも使用できる。どちらの場合も、data-bs-toggle="collapse" が必要。

見本

折り畳みコンポーネントのプレースホルダーコンテンツ。このパネルはデフォルトでは非表示になっているが、ユーザーが関連するトリガーをアクティブにすると表示される。
Bootstrap5.xの設定例 緑背景がv5.0.0-beta1での変更箇所
<p>
	<a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
		リンク式
	</a>
	<button type="button" class="btn btn-primary" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
		ボタン式
	</button>
</p>
<div class="collapse" id="collapseExample">
	<div class="card card-body">
		折り畳みコンポーネントのプレースホルダーコンテンツ。...
	</div>
</div>
【設定】
  • コントロールがリンクの場合:a.btn[data-bs-toggle="collapse"][href="#ID"][role="button"]《ボタン》 + div#ID.collapse《コンテンツ》
  • コントロールがボタンの場合:button.btn[data-bs-toggle="collapse"][data-bs-target="#ID"]《ボタン》 + div#ID.collapse《コンテンツ》
  • コンテンツ表示部分を div.card.card-body にすると表示部分がわかりやすい
アクセシビリティの設定】
  • コントロール用のリンクかボタン部分には、
    • aria-expanded="false" 属性(支援技術に要素の開閉の状態を伝える)
    • aria-controls="コンテンツのID" 属性(リンクやボタンリンクやボタンとコンテンツの関連付け)
    を入れる
  • コントロールが <button> でない場合は、その要素に role="button"(支援技術にボタンの役割を伝える)を入れる
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="collapse"][data-bs-toggle="collapse"]
      • [data-target="#ID"][data-bs-target="#ID"]

 

複数のターゲット(Multiple targets)

<button><a> は、hrefdata-bs-target 属性のセレクタを使用して複数の要素の表示や非表示ができる。複数の <button><a> がある場合は、それぞれを hrefdata-bs-target 属性で要素を表示すれば、その要素の表示や非表示ができる。

見本

この複数の折り畳みの見本の1番目の折り畳みコンポーネントのプレースホルダーコンテンツ。このパネルはデフォルトでは非表示になっているが、ユーザーが関連するトリガーをアクティブにすると表示される。
この複数の折り畳みの見本の2番目の折り畳みコンポーネントのプレースホルダーコンテンツ。このパネルはデフォルトでは非表示になっていますが、ユーザーが関連するトリガーをアクティブにすると表示されます。
Bootstrap5.xの設定例 緑背景がv5.0.0-beta1での変更箇所
<p>
	<a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">第1要素の切替</a>
	<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">第2要素の切替</button>
	<button type="button" class="btn btn-primary" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">両方の要素を切替</button>
</p>
<div class="row">
	<div class="col">
		<div class="collapse multi-collapse" id="multiCollapseExample1">
			<div class="card card-body">
				この複数の折り畳みの見本の1番目の折り畳みコンポーネントのプレースホルダーコンテンツ。...
			</div>
		</div>
	</div>
	<div class="col">
		<div class="collapse multi-collapse" id="multiCollapseExample2">
			<div class="card card-body">
				この複数の折り畳みの見本の2番目の折り畳みコンポーネントのプレースホルダーコンテンツ。...
			</div>
		</div>
	</div>
</div>
【設定】
  • 1つのボタンで2つの要素を同時に切り替えるようにするには、[data-bs-target] に共通するクラスを指定

 

アクセシビリティ(Accessibility)

コントロール要素(リンクやボタン部分)には aria-expanded を必ず追加すること。この属性は、コントロールに関連付けられた折り畳み可能な要素の現在の状態をスクリーンリーダーや同様の支援技術に明示的に伝える。折り畳み可能な要素をデフォルトで閉じている場合は、コントロール要素の属性は aria-expanded="false" にする必要がある。show クラスを使用して折り畳み可能な要素をデフォルトで開くように設定した場合は、代わりに aria-expanded="true" をコントロールに設定する。プラグインは、折り畳み可能な要素が開いているか閉じているか(JavaScript経由か、ユーザーが同じ折り畳み可能な要素に関連付けられた別のコントロール要素を切り替えて)自動的にコントロールの属性を切り替える。コントロール要素のHTML要素がボタンではない場合(例:<a><div> など)、role="button" 属性を要素に追加する必要がある。

コントロール要素が単一の折り畳み可能な要素をターゲットにしている場合、つまり data-bs-target 属性が id セレクタを指している場合、折り畳み可能な要素の id を含むコントロール要素に aria-controls 属性を追加する必要がある。モダンなスクリーンリーダーや同様の支援技術は、この属性を利用して折り畳み可能な要素自体に直接移動する追加のショートカットをユーザーに提供している。

Bootstrapの現在の実装では、WAI-ARIAオーサリングプラクティス1.1のアコーディオンパターンで説明されているさまざまな任意のキーボードの相互作用はカバーしていないので注意。任意のJavaScriptでこれらを組み込む必要がある。

 

Sass v5.0.0-beta3追加

変数(Variables)

デフォルトの設定
scss/_variables.scss 内 collapse-transition$transition-collapse:         height .35s ease;

クラス(Classes)

折り畳み遷移クラスは、複数のコンポーネント(折り畳みとアコーディオン)で共有されるため、scss/_transitions.scss にある。

デフォルトの設定
scss/_transitions.scss 内 collapse-classes の設定.collapse {
	&:not(.show) {
		display: none;
	}
}

.collapsing {
	height: 0;
	overflow: hidden;
	@include transition($transition-collapse);
}

 

使用方法(Usage)

折り畳みプラグインは、上下動による開閉処理を取り扱うために、いくつかのクラスを使用:

  • .collapse:コンテンツを非表示
  • .collapse.show:コンテンツを表示
  • .collapsing:遷移が開始されると追加され、終了すると削除される

これらのクラスは、_transitions.scss の中にある。

データ属性経由で(Via data attributes)

data-bs-toggle="collapse"data-bs-target を要素に追加するだけで、単独や複数の折り畳み可能な要素の制御が自動的に割り当てられる。data-bs-target 属性は、折り畳みを適用するCSSセレクタを受け入れる。折り畳み可能な要素には必ず .collapse を追加する。デフォルトで開いた状態にしたい場合は、.show を追加する。

折り畳み可能領域にアコーディオンのようなグループ管理を追加するには、データ属性 data-bs-parent="#selector" を追加する。これを実践するには、見本に記載。

JavaScript経由で(Via JavaScript)v5.0.0-alpha1設定変更

手動で有効にする:

Bootstrap5.xの設定例
JavaScriptvar collapseElementList = [].slice.call(document.querySelectorAll('.collapse'))
var collapseList = collapseElementList.map(function (collapseEl) {
  return new bootstrap.Collapse(collapseEl)
})
※Bootstrap4.xの設定例
JavaScript$('.collapse').collapse()
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更

オプション(Options)

オプションは、データ属性かJavaScriptを使用して渡すことができる。データ属性の場合、data-bs-parent="" のように data-bs- にオプション名を追加すること。

名前 タイプ デフォルト 説明
parent selector | jQuery object | DOM element false parentが指定されている場合、指定された親要素の下にある折り畳み可能な要素は、この折り畳み可能なアイテムが表示されているときに閉じられる。(従来のアコーディオンの動作に似ている - これは card クラスに依存)
属性は、折り畳み可能な領域に設定する必要がある。
toggle boolean true 呼び出し時に折り畳み可能な要素を切り替える。
true:有効/false:無効

メソッド(Methods)v5.0.0-alpha1設定変更、v5.0.2メソッド追加

コンテンツを折り畳み可能な要素としてアクティブ化し、オプションの object を受け入れる。

コンストラクタを使用して折り畳みインスタンスが作成できる。以下に例を示す:

Bootstrap5.xの設定例
JavaScriptvar myCollapse = document.getElementById('myCollapse')
var bsCollapse = new bootstrap.Collapse(myCollapse, {
	toggle: false
})
※Bootstrap4.xの設定例
JavaScript$('#myCollapsible').collapse({
	toggle: false
})
メソッド 説明
toggle 折り畳み可能な要素を表示か非表示に切り替える。折り畳み可能な要素が実際に表示されたり非表示にされる前(つまり、shown.bs.collapsehidden.bs.collapse イベントが発生する前)に呼び出し元に戻る
show 折り畳み可能な要素を表示。折り畳み可能な要素が実際に表示される前(つまり、shown.bs.collapse イベントが発生する前)に呼び出し元に戻る
hide 折り畳み可能な要素を非表示にする。折り畳み可能な要素が実際に非表示にされる前(つまり、hidden.bs.collapse イベントが発生する前)に呼び出し元に戻る
dispose 要素の折り畳みを破棄(DOM要素に保存されているデータを削除)。
getInstance
v5.0.0-alpha1追加
DOM要素に関連付けられた折り畳みインスタンスを取得できる静的メソッドで、次のように使用可能:bootstrap.Collapse.getInstance(element)
getOrCreateInstance
v5.0.2追加
DOM要素に関連付けられているか初期化されていない場合は新しい要素を作成して折り畳みインスタンスを返す静的メソッド。次のように使用可能:bootstrap.Collapse.getOrCreateInstance(element)
【変更履歴】
  • 【v5.0.0-alpha1】
    • $().collapse('xxx')collapse.xxx()
    • getInstance メソッドが追加
  • 【v5.0.2】
    • getOrCreateInstance メソッドが追加

イベント(Events)

Bootstrapの折り畳みクラスは、折り畳み機能に接続するためにいくつかのイベントを公開している。

イベントタイプ 説明
show.bs.collapse show のインスタンス・メソッドが呼び出されると直ちに発動。
shown.bs.collapse ユーザーに折り畳み要素が表示されたときに発動(完全にCSS遷移が完了するまで待機)。
hide.bs.collapse hide のメソッドが呼び出されると直ちに発動。
hidden.bs.collapse 折り畳み要素がユーザーから非表示になったときに発動(完全にCSS遷移が完了するまで待機)。
使用例 v5.0.0-alpha1設定変更
JavaScriptvar myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', function () {
	// 何かをする...
})