JavaScript

オプションの JavaScript プラグインを使って Bootstrap を実現しましょう。各プラグイン、データと API オプションなどについて学びます。

On this page

別またはコンパイル

プラグインは、（Bootstrap の個別のjs/dist/*.jsを使って）個別にインクルードすることもできますし、bootstrap.jsや minified のbootstrap.min.jsを使って一度にインクルードすることもできます（両方をインクルードしてはいけません）。

バンドルラー(Webpack, Rollup…)を使っている場合は、UMD に対応したjs/dist/*.jsファイルを使うことができます。

モジュールとしての利用

Bootstrap をブラウザでモジュールとして利用できる ESM としてビルドしたバージョン (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>

互換性のないプラグイン

いくつかのプラグイン、ドロップダウン、ツールチップ、そしてポップオーバプラグインは Popper.js に依存しているため、<script> タグ内で module タイプとして扱うことはできません。詳しくはこのイシューをご覧ください。

依存関係

いくつかのプラグインと CSS コンポーネントは他のプラグインに依存しています。プラグインを個別に組み込む場合は、ドキュメントで確認してください。

ドロップダウン、ポップオーバ、ツールチップは Popper に依存しています。

それでも jQuery を使いたい？それは可能です。

Bootstrap 5 は jQuery を使わないよう設計されていますが、Bootstrap のコンポーネントを jQuery と共に使うことができます。Bootstrap が window オブジェクト内で jQuery を検出すると、全てのコンポーネントに jQuery プラグインを追加します。これにより、$('[data-bs-toggle="tooltip"]').tooltip() を実行してツールチップを有効にすることができます。他のコンポーネントも同様です。

データ属性

ほぼ全ての Bootstrap プラグインはデータ属性を持つ HTML だけ有効になり機能します。単一の要素に対して 1 セットのデータ属性のみを使用するようにしてください(例えば、同じボタンからツールチップとモーダルを同時にトリガーすることはできません)。

セレクタ

Bootstrap ではパフォーマンスの都合により、DOM 要素のクエリにネイティブのメソッドである querySelector と querySelectorAll を用いています。そのため、必ず有効なセレクタ.を使うようにしてください。特別なセレクタを使用する場合は、例えば collapse:Example のようにエスケープしてください。

イベント

Bootstrap は、ほとんどのプラグインに一意のアクションのカスタムイベントを提供します。これらは、不定期イベントとしてアクション開始時にトリガされ(例えば show)、完了時にもトリガされます(例えば show)。

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

var myModal = document.getElementById("myModal");

myModal.addEventListener("show.bs.modal", function (event) {
  if (!data) {
    return event.preventDefault(); // stops modal from being shown
  }
});

jQuery イベント

Bootstrap は window オブジェクト内に jQuery が存在し、<body> に data-bs-no-jquery 属性がない場合に jQuery を検出します。jQuery が見つかった場合、Bootstrap は jQuery のイベントシステムを用いてイベントを発行します。Bootstrap のイベントを監視したい場合は、addEventListener の代わりに jQuery メソッド (.on, .one) を使う必要があります。

$("#myTab a").on("shown.bs.tab", function () {
  // do something...
});

プログラム的な API

全てのコンストラクタはオプションオブジェクトを渡すことができます。何も渡さない場合には、デフォルトの挙動で初期化されます。

var myModalEl = document.getElementById("myModal");

var modal = new bootstrap.Modal(myModalEl); // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }); // initialized with no keyboard

プラグインのインスタンスを取得したい場合には、プラグインが公開している getInstance メソッドを用いて、例えば bootstrap.Popover.getInstance(myPopoverEl) とすることで取得することができます。

コンストラクタ内の CSS セレクタ

プラグインを初期化するための DOM 要素の代わりに、CSS セレクタを第一引数として使うこともできます。現在のところ、プラグインは単一の要素しかサポートしていないので、プラグインの要素は querySelector メソッドによって見つけられます。

var modal = new bootstrap.Modal("#myModal");
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]');

非同期関数とトランジション

すべてのプログラム API メソッドは 非同期で、トランジションが開始されてから終了する前に呼び出し元に戻ります。

トランジションが完了したらアクションを実行するために、対応するイベントをキャッチすることができます。

var myCollapseEl = document.getElementById("#myCollapse");

myCollapseEl.addEventListener("shown.bs.collapse", function (event) {
  // Action to execute once the collapsible area is expanded
});

さらに、トランジションコンポーネントの呼び出しは無視されます。

var myCarouselEl = document.getElementById("myCarousel");
var carousel = bootstrap.Carousel.getInstance(myCarouselEl); // Retrieve a Carousel instance

myCarouselEl.addEventListener("slid.bs.carousel", function (event) {
  carousel.to("2"); // Will slide to the slide 2 as soon as the transition to slide 1 is finished
});

carousel.to("1"); // Will start sliding to the slide 1 and returns to the caller
carousel.to("2"); // !! Will be ignored, as the transition to the slide 1 is not finished !!

標準の設定

プラグインの Constructor.Default オブジェクトを変更することで、デフォルト設定を変更できます:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false;

コンフリクト回避 (jQuery を使っている場合)

他の UI フレームワークで Bootstrap プラグインを使うことがあります。このような状況では、名前空間のコンフリクトが起こることがあります。この場合、値を元に戻したいプラグインで .noConflict を呼び出すことができます。

var bootstrapButton = $.fn.button.noConflict(); // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton; // give $().bootstrapBtn the Bootstrap functionality

バージョン番号

Bootstrap の各プラグインのバージョンは、コンストラクタの VERSION プロパティから参照できます。例えば、ツールチップの場合:

bootstrap.Tooltip.VERSION; // => "5.0.2"

JavaScript 無効時のフォールバック

JavaScript が無効な状態に対して、Bootstrap プラグインはフォールバックを提供していません。ユーザエクスペリエンスを考慮する場合は <noscript> を使ってユーザに状況(および JavaScript を再び有効にする方法)を説明し、独自のフォールバックを追加することができます。

サードパーティライブラリ

Bootstrap は Prototype や jQuery UI のようなサードパーティーの JavaScript ライブラリを公式にサポートしません。 .noConflict や名前空間のイベントに関わらず、あなた自身で修正する必要のある互換性の問題があるかもしれません。

サニタイザ

ツールチップとポップオーバは、ビルトインのサニタイザを用いてオプションをサニタイズしています。

デフォルトの allowList の値は次のようになっています:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i;
var DefaultAllowlist = {
  // Global attributes allowed on any supplied element below.
  "*": ["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 に値を追加したい場合、次の手順で行うことができます:

var myDefaultAllowList = bootstrap.Tooltip.Default.allowList;

// To allow table elements
myDefaultAllowList.table = [];

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ["data-bs-option"];

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
var myCustomRegex = /^data-my-app-[\w-]+/;
myDefaultAllowList["*"].push(myCustomRegex);

DOMPurify のように異なるライブラリを使う場合など、デフォルトのサニタイザを変更したい場合には、次のようにしてください:

var yourTooltipEl = document.getElementById("yourTooltip");
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content);
  },
});