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

ポップオーバー(Popovers) v5.0.0-beta1設定変更

iOSにあるようなBootstrapのポップオーバーをサイトのどの要素にも追加するための解説と例。

概要(Overview)

ポップオーバー・プラグインを使用するときに知っておくべきこと:

  • ポップオーバーは、サードパーティのライブラリであるPopperを使用して位置情報を取得しているため、ポップオーバーが動作するためには bootstrap.jsbootstrap.min.js の前にpopper.min.jsを組み込むか、代わりにPopperを内部に含む bootstrap.bundle.jsbootstrap.bundle.min.js を使用する必要がある。
  • ポップオーバーは、依存関係として、ツールチップ・プラグインが必要。
  • ポップオーバーは、パフォーマンス上の理由で任意で取得されるため、自分で初期化する必要がある(そのため実行コードが必要)。
  • titlecontent の長さがゼロのポップオーバーは表示されない。
  • container: 'body' を指定すると、より複雑なコンポーネント(インプットグループやボタングループなど)のレンダリングの問題が回避できる。
  • 非表示要素のポップオーバーは機能しない。
  • .disableddisabled 要素のポップオーバーは、それを囲む要素で起動する必要がある。
  • 複数行にまたがるアンカーから起動されたときは、ポップオーバーはアンカー全体の幅の中央に配置される。この現象を回避するには、<a>.text-nowrap を使用する。
  • ポップオーバーは、対応する要素がDOMから削除される前に非表示にする必要がある。
  • ポップオーバーは、シャドウDOM内の要素のために起動できる。

ポップオーバーがどのように動作するかいくつか実例を表示。

 

どこでもポップオーバーを有効にする例(Example: Enable popovers everywhere)v5.0.0-beta1設定変更

ページ上のすべてのポップオーバーを初期化する方法の1つは、data-bs-toggle 属性でそれらを選択すること。

Bootstrap5.xの実行コード 緑背景がv5.0.0-beta1での変更箇所
JavaScriptの場合var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})
HTMLの場合<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script>
  var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
  var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
    return new bootstrap.Popover(popoverTriggerEl)
</script>
※Bootstrap4.xの実行コード
JavaScriptの場合$(function () {
  $('[data-toggle="popover"]').popover()
})
HTMLの場合<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script>
  $('[data-toggle="popover"]').popover()
</script>
【設定】
  • bootstrap.min.js より前に Popper の設定が必要(バンドル版の bootstrap.bundle.min.js のみでも可)
    ※ 各jsファイルをCDNで設置する方法は、クイックスタートに記載
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="popover"][data-bs-toggle="popover"]

 

container オプションの使用例(Example: Using the container option)v5.0.0-alpha1設定変更

ポップオーバーに干渉するいくつかのスタイルを親要素に持たせているときは、ポップオーバーのHTMLが代わりにその要素内に表示されるようにカスタムで container の指定をすることを推奨。

Bootstrap5.xの実行コード
JavaScriptの場合var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
  })
})
※Bootstrap4.xの設定例
JavaScriptの場合$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更

 

ポップオーバーの設定(Example)

見本
Bootstrap5.xの設定例 緑背景がv5.0.0-beta1での変更箇所
HTML<a class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ポップオーバーのタイトル" data-bs-content="ポップオーバーの説明。もう一度ボタンを押すと閉じます。">ココを押して下さい</a>
【設定】
  • ボタンタグの要素に [data-bs-toggle="popover"][title="ポップオーバーのタイトル"][data-bs-content="ポップオーバーの説明"] を入れる
    ※タイトルはなくても可
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="popover"][data-bs-toggle="popover"]
      • [data-content="ポップオーバーの説明"][data-bs-content="ポップオーバーの説明"]

ポップオーバーの方向設定(Four directions)

上、右、下、左の4つのオプション。RTL(右書き)でBootstrapを使用すると、方向が反転する。

見本

※もう一度ボタンを押すと閉じます。

Bootstrap5.xの設定例 緑背景がv5.0.0-beta1での変更箇所
上に出るポップオーバー<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="上に出るポップオーバー">ポップオーバー(上)</button>
左に出るポップオーバー<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="左に出るポップオーバー">ポップオーバー(左)</button>
下に出るポップオーバー<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="下に出るポップオーバー">ポップオーバー(下)</button>
右に出るポップオーバー<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="右に出るポップオーバー">ポップオーバー(右)</button>
【設定】
  • data-bs-toggle="popover" と同じ要素に data-bs-placement="{side}"{side}left(左)、top(上)、bottom(下)、right(右)の中から選択)を入れる
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • data-placement="{side}"data-bs-placement="{side}"

次のクリックで閉じる(Dismiss on next click)

triggerに focus を使用して、切替要素とは別の要素の次のクリックでポップオーバーを閉じる。

見本
Bootstrap5.xの設定例 緑背景がv5.0.0-beta1での変更箇所
HTML<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="却下するポップアップ" data-bs-content="ボタンを押しても閉じません。それ以外のところを押して閉じて下さい。">ココを押して下さい</a>
Bootstrap5.xの実行コード例
JavaScriptvar popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})
※Bootstrap4.xの実行コード例
JavaScript$('.popover-dismiss').popover({
  trigger: 'focus'
})
【設定】
  • HTMLコードに入れる場合は、a[data-bs-toggle="popover"]tabindex="0"data-bs-trigger="focus" を入れる
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • data-trigger="focus"data-bs-trigger="focus"

無効な要素(Disabled elements)v5.0.0-beta2設定変更

disabled 属性を持つ要素はインタラクティブではないため、ユーザーがカーソルを移動したりクリックしてポップオーバー(またはツールチップ)を起動することは不可。回避策として、ラッパーの <div><span> からポップオーバーを起動することを推奨。理想的には、tabindex ="0" を使用してキーボードフォーカスを可能にする。

無効化されたポップオーバーを起動する場合、無効化された要素をクリックすることを期待しないため、ポップオーバーがユーザーに即座に視覚的フィードバックとして表示されるように、data-bs-trigger="hover focus" も選択できる。

見本
Bootstrap5.xの設定例 緑背景が変更箇所
<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="無効ボタンのポップオーバー">
<button type="button" class="btn btn-primary" disabled>無効ボタン</button>
</span>
※Bootstrap4.xの設定例 赤背景が変更箇所
<span class="d-inline-block" data-toggle="popover" data-content="無効ボタンのポップオーバー">
<button type="button" class="btn btn-primary" style="pointer-events: none;" disabled>無効ボタン</button>
</span>
【設定】
  • span[tabindex="0"][data-bs-toggle="popover"][data-bs-trigger="hover focus"][data-bs-content] > button.btn.btn-{themecolor}[disabled]
【変更履歴】
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-toggle="popover"][data-bs-toggle="popover"]
      • [data-content][data-bs-content]
  • 【v5.0.0-beta2】
    • <span>[tabindex="0"][data-bs-trigger="hover focus"] を入れる
    • [style="pointer-events: none;"] の設定を削除

 

Sass v5.0.0-beta3追加

変数(Variables)

デフォルトの設定
scss/_variables.scss 内 popover-variables の設定$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

 

使用方法(Usage)v5.0.0-alpha1設定変更

JavaScriptでポップオーバーを有効にする:

Bootstrap5.xの設定例
JavaScriptvar exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)
※Bootstrap4.xの設定例
JavaScript$('#example').popover(options)
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの設定がjQueryに依存しない方法に変更

オプション(Options)v5.0.0-beta1オプション追加、v5.0.0-beta2一部変更

オプションは、データ属性かJavaScriptを使用して渡すことができる。データ属性の場合、data-bs-animation="" のように、data-bs- にオプション名を追加。データ属性を経由してオプションを渡す場合は、必ずオプション名の命名規則をキャメルケース(単語の先頭を大文字にする)からケバブケース(単語をハイフンでつなぐ)に変更すること。例:data-bs-customClass="beautifier" を使用する代わりに、data-bs-custom-class="beautifier" を使用する。

名前 タイプ デフォルト 説明
animation boolean true ポップオーバーにCSSフェード遷移を適用
true:有効/false:無効
container string | element | false false ポップオーバーを特定の要素に追加。例:container: 'body'
このオプションはウィンドウサイズ変更時にポップオーバーがトリガー要素から浮かないようにし、トリガー要素の近くにポップオーバーの配置を可能にするという点で特に便利。
content string | element | function '' data-bs-content 属性がない場合のデフォルトのコンテンツ値。

functionが指定された場合、this 参照セットをポップオーバーと接続されている要素にセットして呼び出される。
delay number | object 0 ポップオーバーの表示と非表示の遅延時間(1000分の1秒単位) - triggerでmanualを指定した場合は適用されない。

数字が指定された場合、hide/showの両方に遅延が適用。

オブジェクト構造は次のとおり:delay: { "show": 500, "hide": 100 }
html boolean false ポップオーバーにHTMLを挿入。falseの場合、innerText プロパティがコンテンツをDOMに挿入するために使用される。
XSS攻撃が心配な場合はテキストを使用すること。
true:有効/false:無効
placement string | function 'right' ポップオーバーの配置方法 - auto | top | bottom | left | right
auto が指定されると、動的にポップオーバーの向きが変更。

functionを使用して配置決定する場合は、ポップオーバーDOMノードが第1引数として、トリガー要素DOMノードが第2引数として呼び出される。this コンテキストは、ポップオーバーインスタンスに設定される。
selector string | false false selectorが提供されている場合、ポップオーバーオブジェクトが指定されたターゲットに付与される。実際には動的HTMLコンテンツにポップオーバーを追加できるのに使用。ココ有益な実例に記載
template
v5.0.0-alpha1一部変更
string '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' ポップオーバーを作成するときに使用するベースのHTML。

ポップオーバーの title.popover-header に挿入される。

ポップオーバーの content.popover-body に挿入される。

.popover-arrow は、ポップオーバーの矢印になる。

一番外側の包括要素には、.popover クラスを入れる必要がある。
title string | element | function '' title 属性がない場合のデフォルトのタイトル値

functionを設定した場合、this 参照セットをポップオーバーが接続されている要素にセットして呼び出される。
trigger string 'click' ポップオーバーの起動方法 - click | hover | focus | manual
複数の起動方法を指定;スペースで区切る。manual は他と組み合わせ不可。
fallbackPlacements
v5.0.0-beta2変更
array ['top', 'right', 'bottom', 'left'] 配列内の配置のリストを(優先順に)提供することにより、フォールバック配置を定義。詳細については、Popperのbehaviorドキュメントに記載。
boundary
v5.0.0-beta2変更
string | element 'clippingParents' ポップオーバーのオーバーフローを制約する境界(PopperのpreventOverflow修飾子にのみ適用)。デフォルトでは 'clippingParents' であり、HTMLElementリファレンスが受け入れ可能(JavaScript経由のみ)。詳細については、PopperのpreventOverflowドキュメントに記載。
customClass
v5.0.0-beta1追加
string | function '' 表示されたら、ポップオーバーにクラスを追加する。これらのクラスは、テンプレートで指定されたクラスに加えて追加されるので注意。複数のクラスを追加するには、それらをスペースで区切る:'class-1 class-2'

追加のクラス名を含む単一の文字列を返す関数を渡すことも可能。
sanitize boolean true サニタイズを有効/無効にする。有効にすると、'template', 'content', 'title' オプションはサニタイズされる。
true:有効/false:無効
allowList
v5.0.0-alpha2名称変更
object デフォルト値 許可された属性とタグを含むオブジェクト
sanitizeFn null | function null 自分用のサニタイズ機能を提供できる。サニタイズを実行するために専用のライブラリを使用したい場合に役立つ。詳細は、JavaScriptのサニタイザーに記載。
offset
v5.0.0-beta2復活
array | string | function [0, 8]

ターゲットに対するポップオーバーンのオフセット値。data-bs-offset="10,20" のように、カンマ区切りの値を使用してデータ属性に文字列を渡すことが可能。

関数を使用してオフセットを決定する場合、Popperの配置、参照とPopperの四角形を最初の引数として含むオブジェクトを使用して呼び出される。トリガー要素のDOMノードが2番目の引数として渡される。関数は、2つの数値を持つ配列を返す必要がある:[スキッド, 距離]

詳細については、Popper.jsのoffsetドキュメントに記載。

popperConfig
v5.0.0-beta2変更
null | object | function null

BootstrapのデフォルトのPopperの構成を変更。詳細は、Popperの構成に記載。

関数を使用してPopper構成を作成すると、BootstrapのデフォルトのPopper構成を含むオブジェクトで呼び出される。これは、デフォルトを使用して独自の構成とマージするのに役立つ。この関数は、Popperの構成オブジェクトを返す必要がある。

popperConfig null | object null BootstrapのデフォルトのPopperの構成を変更。詳細は、Popperの構成に記載。

popperConfig でfunctionを使用 v5.0.0-beta2追加

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // 必要に応じてdefaultBsPopperConfigを使用...
    // newPopperConfigを返す
  }
})
【変更履歴】
  • 【v5.0.0-alpha1】
    • template のうち .arrow.popover-arrow に名称変更
  • 【v5.0.0-alpha2】
    • whiteListallowList に名称変更
  • 【v5.0.0-beta1】
    • customClass が追加(v4.6.0でバックポート)
    • Popper v2対応により、
      • offset は廃止
      • fallbackPlacementfallbackPlacements に変更
  • 【v5.0.0-beta2】
    • fallbackPlacements で要素の配置を改善するため、設定タイプを array に、デフォルト値を ['top', 'right', 'bottom', 'left'] に変更
    • boundary のデフォルトの設定が scrollParent から clippingParent に変更
    • offset を復活
    • popperConfig のタイプに function を追加

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

show

要素のポップオーバーを表示。実際にポップオーバーが表示される前(つまり、show.bs.popover イベント発動前)に呼び出し元に戻る。これは、ポップオーバーの"manual"トリガーとみなされる。タイトルとコンテンツが両方とも長さゼロのポップオーバーは表示されない。

JavaScriptmyPopover.show()

hide

要素のポップオーバーを非表示にする。ポップオーバーが実際に非表示になる前(つまり、hidden.bs.popover イベント発動前)に呼び出し元に戻る。これは、ポップオーバーの"manual"トリガーとみなされる。

JavaScriptmyPopover.hide()

toggle

要素のポップオーバーを切り替える。ポップオーバーが実際に表示か非表示になる前(つまり、shown.bs.popoverhidden.bs.popover イベント発動前)に呼び出し元に戻る。これは、ポップオーバーの"manual"トリガーとみなされる。

JavaScriptmyPopover.toggle()

dispose

要素のポップオーバーを非表示にしたり破棄したりする(DOM要素に保存されているデータを削除)。(selector オプションを使用して作成される)デリゲートを使用するポップオーバーは、子孫トリガー要素で個別に破棄できない。

JavaScriptmyPopover.dispose()

enable

要素のポップオーバーに表示する機能を与える。デフォルトで有効

JavaScriptmyPopover.enable()

disable

要素のポップオーバーが表示されるようにする機能を削除。ポップオーバーは、再度有効になっている場合にのみ表示できる。

JavaScriptmyPopover.disable()

toggleEnabled

要素のポップオーバーが表示か非表示になるように切り替える。

JavaScriptmyPopover.toggleEnabled()

update

要素のポップオーバーの位置を更新。

JavaScriptmyPopover.update()

getInstance v5.0.0-alpha1追加

DOM要素に関連付けられたポップオーバー・インスタンスを取得できる静的メソッド

JavaScriptvar exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Bootstrapポップオーバー・インスタンスを返す

getOrCreateInstance v5.0.2追加

DOM要素に関連付けられたポップオーバー・インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。

JavaScriptvar exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Bootstrapポップオーバー・インスタンスを返す
【変更履歴】
  • 【v5.0.0-alpha1】
    • $().popover('xxx')popover.xxx()
    • getInstance メソッドが追加
  • 【v5.0.2】
    • getOrCreateInstance メソッドが追加

イベント(Events)

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