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

オフキャンバス(Offcanvas) v5.0.0-beta3新設

いくつかのクラスとJavaScriptプラグインを使用して、ナビゲーションやショッピングカートなどの非表示のサイドバーをプロジェクトに組み込む。

使い方(How it works)

オフキャンバスは、JavaScriptを経由して切り替えて、ビューポートの左端、右端、下端から表示できるサイドバーコンポーネント。ボタンやアンカーは、切り替えた特定の要素に関連付けるトリガーとして使用され、 data 属性はJavaScriptを呼び出すために使用される。

  • オフキャンバスは、モーダルと同じJavaScriptコードの一部を共有しており、概念的には非常に似ているが、別々のプラグインである。
  • 同様に、オフキャンバスのスタイルと大きさの一部のソースSass変数は、モーダルの変数から継承される。
  • 表示されている場合のオフキャンバスには、非表示にするのにクリック可能なデフォルトの背景が含まれている。
  • モーダル同様、一度に表示できるオフキャンバスは1つだけ。

注意喚起!CSSがアニメーションを処理する方法を考えると .offcanvas 要素に margintranslate を使用することは不可。代わりのクラスを独立したラッピング要素に使用すること。

 

実例(Example)

オフキャンバスコンポーネント(Offcanvas components)

以下は、(.offcanvas.show を経由して)デフォルトで表示されるオフキャンバスの例。オフキャンバスには、閉じるボタンのあるヘッダと、初期 padding 用のオプションのボディクラスのサポートが含まれている。できる場合はいつでも、却下アクションを含むオフキャンバスヘッダを含めるか、明示的な却下アクションを提供することを推奨。

見本 オフキャンバスを開いた状態で表示
オフキャンバス
これがオフキャンバスのコンテンツ。ここにほぼすべてのBootstrapコンポーネントやカスタム要素が配置できる。
設定例
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasLabel">オフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body">
		これがオフキャンバスのコンテンツ。ここにほぼすべてのBootstrapコンポーネントやカスタム要素が配置できる。
	</div>
</div>

オフキャンバスの設定(Live demo)

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

  • .offcanvas は、コンテンツを非表示にする(デフォルト)
  • .offcanvas.show は、コンテンツを表示する

href 属性を持つリンクか data-bs-target 属性を持つボタンが使用できる。どちらの場合も、data-bs-toggle="offcanvas" が必要。

見本

オフキャンバス
プレースホルダーとしてのテキスト。実生活では、選択した要素を持つことができます。いいね、テキスト、画像、リストなど。
設定例
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-expanded="false" aria-controls="offcanvasExample">
	href属性を持つリンク
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-expanded="false" aria-controls="offcanvasExample">
	data-bs-target属性を持つボタン
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasExampleLabel">オフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>	 
	</div>
	<div class="offcanvas-body">
		<div>
			プレースホルダーとしてのテキスト。...
		</div>

		<div class="dropdown mt-3">
			<button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown" aria-expanded="false">
				ドロップダウン
			</button>
			<ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
				<li><a class="dropdown-item" href="#">メニュー1</a></li>
				<li><a class="dropdown-item" href="#">メニュー2</a></li>
				<li><a class="dropdown-item" href="#">メニュー3</a></li>
			</ul>
		</div>
	</div>
</div>
【設定】
  • button.btn《切替ボタン》 + 〔div.offcanvas.offcanvas-start > {div.offcanvas-header > h5.offcanvas-title《タイトル》 + button.btn-close[data-bs-dismiss="offcanvas"][aria-label="閉じる"]《閉じるアイコンボタン》}《ヘッダ》 + div.offcanvas-body《コンテンツ》〕《オフキャンバス部分》
  • オフキャンバスのプラグインを使用するため、
    • 切替ボタンには、[data-bs-toggle="offcanvas"](プラグインを有効にする)と、[data-bs-target="#オフキャンバスのID"][href="#オフキャンバスのID"]
    • div.offcanvas(ボタンのリンク先)には、id="ID名"tabindex="-1"Esc を押すとオフキャンバスが閉じるようにする)
    をそれぞれ入れること
アクセシビリティの設定】
  • h5.offcanvas-titleid="ID名" を入れ、div.offcanvasaria-labelledby="タイトルのID" 属性(タイトルをオフキャンバスのラベルとして関連付ける)を入れること
  • 切替ボタン部分には、
    • aria-expanded="false" 属性(支援技術に要素の開閉の状態を伝える)
    • aria-controls="コンテンツのID" 属性(リンクまたはボタンリンクまたはボタンとコンテンツの関連付け)
    • コントロールが a.btn の場合は、role="button"(支援技術にボタンの役割を伝える)
    を入れる

 

配置(Placement)v5.0.0一部追加

オフキャンバスコンポーネントのデフォルトの配置はないため、以下の修飾子クラスのいずれかを追加する必要がある。

  • .offcanvas-start は、ビューポートの左側にオフキャンバスを配置
  • .offcanvas-end は、ビューポートの右側にオフキャンバスを配置
  • .offcanvas-top は、ビューポートの上側にオフキャンバスを配置
  • .offcanvas-bottom は、ビューポートの下側にオフキャンバスを配置

以下に上側、右側、下側の実例を表示。

1.上側にオフキャンバスを配置 v5.0.0追加

見本
上側オフキャンバス
...
設定例
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">上側オフキャンバスの切替</button>

<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
	<div class="offcanvas-header">
		<h5 id="offcanvasTopLabel">上側オフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じるe"></button>
	</div>
	<div class="offcanvas-body">
		...
	</div>
</div>

2.右側にオフキャンバスを配置

見本
右側オフキャンバス
...
設定例
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">右側オフキャンバスの切替</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
	<div class="offcanvas-header">
		<h5 id="offcanvasRightLabel">右側オフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body">
		...
	</div>
</div>

3.下側にオフキャンバスを配置

見本
下側オフキャンバス
...
設定例
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">下側オフキャンバスの切替</button>

<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasBottomLabel">下側オフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body small">
		...
	</div>
</div>

【設定】

  • 左側にオフキャンバスを配置:.offcanvas.offcanvas-start
  • 右側にオフキャンバスを配置:.offcanvas.offcanvas-end
  • 上側にオフキャンバスを配置:.offcanvas.offcanvas-top
  • 下側にオフキャンバスを配置:.offcanvas.offcanvas-bottom
【変更履歴】
  • 【v5.0.0】
    • 上側にオフキャンバスを配置(.offcanvas.offcanvas-top)を追加

 

背景(Backdrop)

オフキャンバスとその背景が表示されている場合、<body> 要素のスクロールは無効になる。data-bs-scroll 属性を使用して <body> スクロールを切り替え、data-bs-backdrop を使用して背景を切り替える。

見本
スクロールが有効

ページの残りの部分をスクロールして、このオプションの動作を確認すること。

オーバーレイ背景のあるオフキャンバス

ページの残りの部分をスクロールして、このオプションの動作を確認すること。

スクロール可能なオーバーレイ背景

ページの残りの部分をスクロールして、このオプションの動作を確認すること。

設定例
bodyスクロールを有効<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">bodyスクロールを有効</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasScrollingLabel">スクロールが有効</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body">
		<p>...</p>
	</div>
</div>
オーバーレイ背景を有効<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBackdrop" aria-controls="offcanvasWithBackdrop">オーバーレイ背景を有効(デフォルト)</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasWithBackdrop" aria-labelledby="offcanvasWithBackdropLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasWithBackdropLabel">オーバーレイ背景のあるオフキャンバス</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body">
		<p>.....</p>
	</div>
</div>
スクロールとオーバーレイ背景の両方を有効<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">スクロールとオーバーレイ背景の両方を有効</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
	<div class="offcanvas-header">
		<h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">スクロール可能なオーバーレイ背景</h5>
		<button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="閉じる"></button>
	</div>
	<div class="offcanvas-body">
		<p>...</p>
	</div>
</div>
【設定】
  • オフキャンバスが開いているときに、
    • オーバーレイ背景を無効にしてスクロールを有効:data-bs-scroll="true", data-bs-backdrop="false" 属性
    • オーバーレイ背景もスクロールも有効:data-bs-scroll="true" 属性
    .offcanvas に入れる

 

アクセシビリティ(Accessibility)

オフキャンバスパネルは概念的にはモーダルダイアログであるため、オフキャンバスのタイトルに必ず aria-labelledby="...".offcanvas に追加すること。すでにJavaScriptを経由して追加しているため、role="dialog" を追加する必要はないので注意。

 

Sass

変数(Variables)

デフォルトの設定
scss/_variables.scss 内 offcanvas-variables の設定$offcanvas-padding-y:               $modal-inner-padding;
$offcanvas-padding-x:               $modal-inner-padding;
$offcanvas-horizontal-width:        400px;
$offcanvas-vertical-height:         30vh;
$offcanvas-transition-duration:     .3s;
$offcanvas-border-color:            $modal-content-border-color;
$offcanvas-border-width:            $modal-content-border-width;
$offcanvas-title-line-height:       $modal-title-line-height;
$offcanvas-bg-color:                $modal-content-bg;
$offcanvas-color:                   $modal-content-color;
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;

 

使用方法(Usage)

オフキャンバスプラグインは、いくつかのクラスと属性を利用して、手間のかかる作業を処理:

  • .offcanvas は、コンテンツを非表示にする
  • .offcanvas.show は、コンテンツを表示する
  • .offcanvas-start は、左側のオフキャンバスを非表示にする
  • .offcanvas-end は、右側のオフキャンバスを非表示にする
  • .offcanvas-bottom は、下側のオフキャンバスを非表示にする

data-bs-dismiss="offcanvas" 属性を使用して閉じるボタンを追加し、これを押すことによりJavaScript機能が起動される。すべてのデバイスで適切に動作するように、必ず <button> 要素を使用すること。

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

要素に data-bs-toggle="offcanvas"data-bs-targethref を追加して、1つのオフキャンバス要素の制御を自動的に割り当てる。data-bs-target 属性は、オフキャンバスを適用するCSSセレクタを受け入れる。必ず .offcanvas クラスをオフキャンバス要素に追加すること。またデフォルトで開いた状態にしたい場合は、あらかじめ .show クラスを追加する。

JavaScript経由で(Via JavaScript)

手動で有効にする:

設定例
JavaScriptvar offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
  return new bootstrap.Offcanvas(offcanvasEl)
})

オプション(Options)

オプションは、データ属性かJavaScriptを経由して渡される。データ属性の場合は、data-bs-backdrop="" のように、data-bs- にオプション名を追加。

名前 タイプ デフォルト 説明
backdrop boolean true オフキャンバスが開いている間にbodyにオーバーレイ背景を適用
true:有効/false:無効
keyboard boolean true Esc が押されたときにオフキャンバスを閉じる
true:有効/false:無効
scroll boolean false オフキャンバスが開いているときにbodyをスクロールできるようにする
true:有効/false:無効

メソッド(Methods)v5.0.2メソッド追加

コンテンツをオフキャンバス要素としてアクティブ化し、オプションの object を受け入れる。

コンストラクタを使用してオフキャンバス・インスタンスが作成できる。以下に例を表示:

設定例
JavaScriptvar myOffcanvas = document.getElementById('myOffcanvas')
var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)
メソッド 説明
toggle オフキャンバス要素を表示または非表示に切り替える。オフキャンバス要素が実際に表示されたり非表示にされる前(つまり、shown.bs.offcanvas または hidden.bs.offcanvas イベントが発生する前)に呼び出し元に戻る
show オフキャンバス要素を表示。オフキャンバス要素が実際に表示される前(つまり、shown.bs.offcanvas イベントが発生する前)に呼び出し元に戻る
hide オフキャンバス要素を非表示にする。オフキャンバス要素が実際に非表示にされる前(つまり、hidden.bs.offcanvas イベントが発生する前)に呼び出し元に戻る
getInstance DOM要素に関連付けられたオフキャンバス・インスタンスを取得できる静的メソッド。
getOrCreateInstance
v5.0.2追加
DOM要素に関連付けられたオフキャンバス・インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
【変更履歴】
  • 【v5.0.2】
    • getOrCreateInstance メソッドが追加

イベント(Events)

Bootstrapのオフキャンバスクラスは、オフキャンバス機能に接続するためのいくつかのイベントを公開している。

イベントタイプ 説明
show.bs.offcanvas show のインスタンス・メソッドが呼び出されると直ちに発動。
shown.bs.offcanvas ユーザーにオフキャンバス要素が表示されたときに発動(完全にCSS遷移が完了するまで待機)。
hide.bs.offcanvas hide のメソッドが呼び出されると直ちに発動。
hidden.bs.offcanvas オフキャンバス要素がユーザーから非表示になったときに発動(完全にCSS遷移が完了するまで待機)。
使用例
JavaScriptvar myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', function () {
	// 何かをする...
})