個別か一括で(Individual or compiled)
プラグインは個別(Bootstrapの個別の /js/dist/*.js
ファイルを使用)か、一括版(bootstrap.js
か軽量版の bootstrap.min.js
)が使用可能(両方を組み込む必要はない)。
バンドラ(webpack、Rollupなど)を使用する場合は、UMD対応の /js/dist/*.js
ファイルが使用可能。
※Bootstrapの個別の *.js
ファイル(ソースファイルの js/dist/
内にある)
alert.js
(アラートメッセージ用)button.js
(コントロールボタン用)carousel.js
(カルーセル用)collapse.js
(折り畳み(アコーディオン)、ナビゲーションバーの切替用)dropdown.js
(ドロップダウン用、要Popper)modal.js
(モーダル用)offcanvas.js
(オフキャンバス用)popover.js
(ポップオーバー用、要Popper)scrollspy.js
(スクロールスパイ用)tab.js
(動的タブ(ナビゲーション)、リストグループ切替パネル用)toast.js
(トースト用)tooltip.js
(ツールチップ用、要Popper)
【変更履歴】
- 【v5.0.0-alpha1】
- オフキャンバス・コンポーネントの新設に伴い
offcanvas.js
が追加 index.js
(webpackなどに組込用)は、ソースファイル内のjs/index.esm.js
やjs/index.umd.js
に移動util.js
(ユーティリティ用)は、ソースファイル内のjs/src/util/index.js
に移動
- オフキャンバス・コンポーネントの新設に伴い
モジュールとしてのBootstrapの使い方(Using Bootstrap as a module)v5.0.0-alpha1新設
<script type="module">
がターゲットのブラウザでサポートされている場合、Bootstrapをブラウザのモジュールとして使用できるようにするために、ESM
(ES Modules)で構築されたBootstrapのバージョン(bootstrap.esm.js
と bootstrap.esm.min.js
)を提供。
設定例
<script type="module">
import { Toast } from 'bootstrap.esm.min.js'
Array.from(document.querySelectorAll('.toast'))
.forEach(toastNode => new Toast(toastNode))
</script>
互換性のないプラグイン
Bootstrapのドロップダウン、ツールチップ、ポップオーバープラグインではPopperに依存しているので、ブラウザの制限によりmodule
タイプでの <script>
タグは使用不可。問題の詳細は、V8のJavaScript modulesに記載。
依存関係(Dependencies)v5.0.0-alpha1変更
一部のプラグインとCSSコンポーネントは、他のプラグインに依存する。個別のプラグインを組み込む場合は、解説でこれらの依存関係を確認すること。
Bootstrapのドロップダウン、ツールチップ、ポップオーバーは、Popperにも依存している。
【変更履歴】
- 【v5.0.0-alpha1】
- すべてのプラグインにおいてjQueryとの依存関係が必要なくなった
引き続きjQueryは使用可能(Still want to use jQuery? It’s possible!)v5.0.0-alpha1新設
Bootstrap 5はjQueryなしで使用するように設計されているが、jQueryでコンポーネントを使用することはまだ可能。Bootstrapが window
オブジェクトで jQuery
を検出すると、jQueryのプラグインシステムにすべてのコンポーネントが追加され、ツールチップを有効にするために $('[data-bs-toggle="tooltip"]').tooltip()
が実行可能になる。他のコンポーネントについても同様。
データ属性(Data attributes)
ほぼ全てのBootstrapプラグインは、HTMLだけでデータ属性を使用して有効化と構成が可能(JavaScript機能を使用する推奨方法)。必ず1つの要素に対して1組のデータ属性を使用すること(同じボタンからツールチップとモーダルを起動することなどは不可)。
【変更履歴】
- 【v5.0.0-alpha1】
- データ属性APIの無効と
data-api
の名前空間とともに名前空間としてプラグインの名前を組み込む方法は削除
- データ属性APIの無効と
セレクタ
現在、DOM要素をクエリするために、パフォーマンス上の理由からネイティブメソッドquerySelector
と querySelectorAll
を使用しているため、有効なセレクタを使用する必要がある。特殊なセレクタを使用する場合は、collapse:Example
のようなエスケープをすること。
イベント(Events)
Bootstrapは、ほとんどのプラグインの独自の動作のためのカスタムイベントを提供。通常、これらは動詞、過去分詞の形態になる-動詞形(show
など)がイベントの開始時に起動され、その過去分詞形(shown
など)がアクションの完了時に起動される。
すべての動詞形のイベントで preventDefault()
機能を提供。これにより、アクション開始前にそのアクションの実行を停止することが可能。イベントハンドラからfalseを返すと、preventDefault()
も自動的に呼び出される。
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptvar myModal = document.getElementById('myModal')
myModal.addEventListener('show.bs.modal', function (event) {
if (!data) {
return event.preventDefault() // モーダルの表示を止める
}
})
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$('#myModal').on('show.bs.modal', function (event) {
if (!data) {
return event.preventDefault() // モーダルの表示を止める
}
})
jQueryのイベント
window
オブジェクトに jQuery
があり、<body>
に data-bs-no-jquery
属性が設定されていない場合、BootstrapはjQueryを検出する。jQueryが検出された場合、BootstrapはjQueryのイベントシステムのためにイベントを発行する。従って、Bootstrapのイベントを監視したい場合は、addEventListener
の代わりにjQueryメソッド(.on
, .one
)を使用する必要がある。
JavaScript$('#myTab a').on('shown.bs.tab', function () {
// 何かをする...
})
プログラムに基づいたAPI(Programmatic API)
すべてのコンストラクタはオプションのoptionsオブジェクトを受け入れるか、または何も受け入れない(これによりデフォルトの動作でプラグインが起動される)。
Bootstrap5.xの設定例
JavaScriptvar myModalEl = document.getElementById('myModal')
var modal = new bootstrap.Modal(myModalEl) // デフォルトで初期化
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // キーボードなしで初期化
※Bootstrap4.xの設定例
JavaScript$('#myModal').modal() // デフォルトで初期化
$('#myModal').modal({ keyboard: false }) // キーボードなしで初期化
$('#myModal').modal('show') // 初期化して直ちに表示を呼び出す
特定のプラグイン・インスタンスを取得できるよう各プラグインで getInstance
メソッドを公開。要素から直接取得するには次のように設定:
Bootstrap5.xの設定例
JavaScriptbootstrap.Popover.getInstance(myPopoverEl)
※Bootstrap4.xの設定例
JavaScript$('[rel=popover]').data('popover')
同期関数と遷移(Asynchronous functions and transitions)
すべてのプログラムAPIメソッドは非同期であり、遷移が開始された後、終了する前に呼び出し元に戻る。
遷移が完了したらアクションを実行するために、対応するイベントに従う。
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptvar myCollapseEl = document.getElementById('#myCollapse')
myCollapseEl.addEventListener('shown.bs.collapse', function (event) {
// 折り畳み領域が展開された後に実行するアクション
})
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$('#myCollapse').on('shown.bs.collapse', function (event) {
// 折り畳み領域が展開された後に実行するアクション
})
さらに、遷移コンポーネントのメソッド呼び出しは無視される。
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptvar myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // カルーセル・インスタンスを取得
myCarouselEl.addEventListener('slid.bs.carousel', function (event) {
carousel.to('2') // スライド1への移行が終了するとすぐにスライド2にスライド
})
carousel.to('1') // スライド1にスライドして呼び出し元に戻る
carousel.to('2') // !! スライド1への移行が終了していないため、無視される !!
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$('#myCarousel').on('slid.bs.carousel', function (event) {
$('#myCarousel').carousel('2') // スライド1への移行が終了するとすぐにスライド2にスライド
})
$('#myCarousel').carousel('1') // スライド1にスライドして呼び出し元に戻る
$('#myCarousel').carousel('2') // !! スライド1への移行が終了していないため、無視される !!
デフォルト設定(Default settings)
プラグインの Default
オブジェクトを変更することにより、プラグインのデフォルト設定を変更することが可能:
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScript// モーダルプラグインの`keyboard`オプションのデフォルトをfalseに変更
bootstrap.Modal.Default.keyboard = false
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript// モーダルプラグインの`keyboard`オプションのデフォルトをfalseに変更
$.fn.modal.Constructor.DEFAULTS.keyboard = false
競合の回避(jQueryを使用している場合のみ)(No conflict)
他のUIフレームワークでBootstrapプラグインを使用する必要がある場合には、名前空間の衝突が起きることがある。そのような場合は、値を元に戻したいプラグインで .noConflict
を呼び出すことが可能。
設定例
JavaScriptvar bootstrapButton = $.fn.button.noConflict() // 以前$.fn.buttonに割り当てられた値に戻す
$.fn.bootstrapBtn = bootstrapButton // $().bootstrapBtnにBootstrapの機能を与える
バージョン・ナンバー(Version numbers)
Bootstrapの各プラグインのバージョンは、プラグインのコンストラクタの VERSION
プロパティ経由で取得可能。例えばツールチッププラグインの場合:
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptbootstrap.Tooltip.VERSION // => "5.0.0"
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$.fn.tooltip.Constructor.VERSION // => "4.4.1"
JavaScript無効時の特別なフォールバック(No special fallbacks when JavaScript is disabled)
JavaScriptが無効になっていると、Bootstrapのプラグインは特に適切なフォールバックをしない。この場合のユーザーの体験を重視する場合は、<noscript>
を使用してユーザーに状況(とJavaScriptを再度有効にする方法)を説明するか、独自のカスタム・フォールバックを追加する。
サードパーティ製のライブラリ
Bootstrapは、PrototypeやjQueryのUIのようなサードパーティのJavaScriptライブラリを正式にサポートしていない。.noConflict
や名前空間のイベントにもかかわらず自分で修正する必要のある互換性の問題がある場合がある。
HTMLサニタイザー(Sanitizer)v5.0.0-alpha2名称変更
ツールチップとポップオーバーでは、HTMLを受け付けるオプションでサニタイズするためにBootstrap内蔵のサニタイザーを使用。
※ツールチップとポップオーバープラグインの data-bs-template
属性には、属性値に渡すことができるHTMLの適切なXSSサニタイズがなかったため実装。
デフォルトの allowList
値は次のとおり:
JavaScriptvar ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultAllowlist = {
// 以下の任意の要素で許可されているグローバル属性
'*': ['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', 'srcset', 'alt', 'title', 'width', 'height'],
li: [],
ol: [],
p: [],
pre: [],
s: [],
small: [],
span: [],
sub: [],
sup: [],
strong: [],
u: [],
ul: []
}
このデフォルトの allowList
に新しい値を追加したい場合は、次のようにする:
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptvar myDefaultAllowList = bootstrap.Tooltip.Default.allowList
// テーブル要素を許可
myDefaultAllowList.table = []
// td要素とtd要素のdata-bs-option属性を許可
myDefaultAllowList.td = ['data-bs-option']
// 属性を検証するために自分で任意の正規表現を追加することが可能
// 正規表現がゆるくなりすぎないように注意
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScriptvar myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList
myDefaultWhiteList.table = []
myDefaultWhiteList.td = ['data-bs-option']
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)
DOMPurifyなどの専用ライブラリを使用するためにBootstrapのサニタイザーを回避する場合は、次の手順を実行する必要がある:
Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptvar yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$('#yourTooltip').tooltip({
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})
【変更履歴】
- 【v5.0.0-alpha2】
whitelist
をallowlist
に名称変更