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

Bootstrap4.xの使い方をBootstrap3.xからの変更箇所を交えて解説しています。

JavaScript

jQueryに組み込まれたJavaScriptプラグインを使用して、Bootstrapに活力を与える。各プラグイン、データとプログラムのAPIオプションなどについて学習する。

個別または一括で(Individual or compiled)

プラグインは個別(Bootstrapの個別の /js/dist/*.js ファイルを使用)に組み込むか、一括版の あらかじめPopper.jsが組み込まれている bootstrap.bundle.js とその軽量版の bootstrap.bundle.min.js も使用可能(両方を組み込む必要はない)を使用することが可能。

バンドラ(webpack、Rollupなど)を使用する場合は、UMD対応の /js/dist/*.js ファイルが使用可能。

※Bootstrapの個別の *.js ファイル(ソースファイルjs/dist/ 内にある)

 

依存関係(Dependencies)v4.0.0変更

いくつかのプラグインとCSSコンポーネントは、他のプラグインに依存する。個別のプラグインを組み込んでいる場合、マニュアルでこれらの依存関係を確認するように。また、すべてのプラグインは、jQueryに依存している(これはjQueryファイルがプラグインファイルの前に導入されていなければならないことを意味する)ことに注意。jQueryのどのバージョンをサポートしているかはpackage.json(peerDependenciesの項目)に記載(v4.4.1時点で1.9.1~3に対応)。

Bootstrapのドロップダウン、ツールチップ、ポップオーバーは、Popper.jsにも依存している。

【Bootstrap3.xとの変更箇所】

  • 記載ファイル:bower.jsonpackage.json

 

データ属性(Data attributes)

ほぼ全てのBootstrapプラグインは、データ属性(JavaScript機能を使う好ましい方法)を使用してHTMLだけを有効にして設定可能。必ず1つの要素に対して1組のデータ属性を使用すること(例:同じボタンからツールチップとモーダルを起動することは不可)。

しかし、この機能を無効にすることが望ましい場合もある。データ属性APIを無効にするには、次のように data-api で使用した名前空間ドキュメント上のすべてのイベントのバインドを解除:

設定例
JavaScript$(document).off('.data-api')

また特定のプラグインを対象にするには、次のように data-api の名前空間とともに名前空間としてプラグインの名前を組み込むことも可能:

設定例
JavaScript$(document).off('.alert.data-api')

 

イベント(Events)

Bootstrapは、ほとんどのプラグインの独自の動作のためのカスタムイベントを提供。一般的に、これらは動詞、過去分詞の形態になる-動詞形(例:show)がイベントの開始時に起動され、その過去分詞形(例:shown)がアクションの完了時に起動される。

すべての動詞形のイベントで preventDefault() 機能を提供。これにより、アクション開始前にそのアクションの実行を停止することが可能。イベントハンドラからfalseを返すと、preventDefault() も自動的に呼び出される。

設定例
JavaScript$('#myModal').on('show.bs.modal', function (e) {
	if (!data) {
		return e.preventDefault() // モーダルの表示を止める
	}
})

 

プログラムに基づいたAPI(Programmatic API)

単にJavaScript API経由で、すべてのBootstrapのプラグインを使用することが可能。すべての公開APIは、単独または連鎖的なメソッドで処理結果を返す。

設定例
JavaScript$('.btn.danger').button('toggle').addClass('fat')

すべてのメソッドは、オプションのオプション・オブジェクト、特定のメソッドを対象とした文字列を入れるか、または空欄(デフォルトの動作でプラグインを開始)にする:

設定例
JavaScript$('#myModal').modal() // デフォルトで初期化
$('#myModal').modal({ keyboard: false }) // キーボードなしで初期化
$('#myModal').modal('show') // 初期化して直ちに表示を呼び出す

各プラグインは、Constructor プロパティを $ fn.popover.Constructor のように設定して、未加工のコンストラクタを公開している。特定のプラグインのインスタンスを取得したい場合は、要素を $('[rel=popover]').data('popover') のように設定して直接取得する。

同期関数と遷移(Asynchronous functions and transitions)

すべてのプログラマティックAPIメソッドは非同期であり、移行が開始されると呼び出し元に戻るが、終了する前に呼び出し元に戻る

遷移が完了したらアクションを実行するために、対応するイベントを実行することが可能。

設定例
JavaScript$('#myCollapse').on('shown.bs.collapse', function (e) {
	// 折り畳み領域が展開された後に実行するアクション
})

さらに、遷移コンポーネントのメソッド呼び出しは無視される

設定例
JavaScript$('#myCarousel').on('slid.bs.carousel', function (e) {
	$('#myCarousel').carousel('2') // スライド1への移行が終了するとすぐにスライド2にスライド
})

$('#myCarousel').carousel('1') // スライド1にスライドして呼び出し元に戻る
$('#myCarousel').carousel('2') // !! スライド1への移行が終了していないため、無視される !!

デフォルト設定(Default settings)

プラグインの Constructor.DEFAULTS オブジェクトを変更することにより、プラグインのデフォルト設定を変更することが可能:

設定例
JavaScript// モーダルプラグインの`keyboard`オプションのデフォルトをfalseに変更
$.fn.modal.Constructor.DEFAULTS.keyboard = false 

 

競合の回避(No conflict)

他のUIフレームワークでBootstrapプラグインを使用する必要がある場合には、名前空間の衝突が起きることがある。そのような場合は、値を元に戻したいプラグインで .noConflict を呼び出すことが可能。

設定例
JavaScriptvar bootstrapButton = $.fn.button.noConflict() // 以前$.fn.buttonに割り当てられた値に戻す
$.fn.bootstrapBtn = bootstrapButton // $().bootstrapBtnにBootstrapの機能を与える

 

バージョン・ナンバー(Version numbers)

Bootstrapの各jQueryプラグインのバージョンは、プラグインのコンストラクタの VERSION プロパティ経由で取得可能。例えばツールチッププラグインの場合:

設定例
JavaScript$.fn.tooltip.Constructor.VERSION // => "4.4.1"

 

JavaScript無効時の特別なフォールバック(No special fallbacks when JavaScript is disabled)

JavaScriptが無効になっていると、Bootstrapのプラグインは特別なフォールバックをしない。この場合のユーザーの体験が気になるなら、<noscript> を使ってユーザーに状況(JavaScriptを再度有効にする方法)を説明し、独自のカスタム・フォールバックを追加する。

 

ユーティリティ(Util)

すべてのBootstrapのJavascriptファイルは、util.js に依存し、他のJavaScriptファイルと一緒に組み込む必要がある。すでにコンパイル済みの(または軽量化された)bootstrap.js を使用している場合は、そこに組み込まれているので、改めてこれを追加する必要はない。

util.js には、ユーティリティ機能と transitionEnd イベントの基本な補助とCSS遷移アニメーションエミュレーターが組み込まれている。これは他のプラグインでCSS遷移アニメーションのサポートをチェックし、遷移アニメーションを実行するために使用される。

【Bootstrap3.xとの変更箇所】

  • v3の transition.jsutil.js

 

HTMLサニタイザー(Sanitizer)v4.3.1新設

ツールチップポップオーバーでは、HTMLを受け付けるオプションでサニタイズするためにBootstrap内蔵のサニタイザーを使用。
※ツールチップおよびポップオーバープラグインの data-template 属性には、属性値に渡すことができるHTMLの適切なXSSサニタイズがなかったため実装。

デフォルトの whiteList 値は以下のとおり:

JavaScriptvar ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
  // 以下の任意の要素で許可されているグローバル属性
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

このデフォルトの whiteList に新しい値を追加したい場合は、次のようにする:

設定例
JavaScriptvar myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

// テーブル要素を許可
myDefaultWhiteList.table = []

// td要素およびtd要素のdata-option属性を許可
myDefaultWhiteList.td = ['data-option']

// 属性を検証するために自分で任意の正規表現を追加することが可能
// 正規表現がゆるくなりすぎないように注意
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

DOMPurifyのような専用のライブラリを使用したいという理由でBootstrapのサニタイザーを使わない場合は、次のようにする:

設定例
JavaScript$('#yourTooltip').tooltip({
	sanitizeFn: function (content) {
		return DOMPurify.sanitize(content)
	}
})