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

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

ポップオーバー(Popovers) v4.0.0設定変更

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

概要(Overview)

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

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

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

 

どこでもポップオーバーを有効にする例(Example: Enable popovers everywhere)

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

実行コード
JavaScriptの場合コピー$(function () {
	$('[data-toggle="popover"]').popover()
})
HTMLの場合コピー<script>
	$('[data-toggle="popover"]').popover()
</script>

 

container オプションの使用例(Example: Using the container option)

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

実行コード
JavaScriptの場合コピー$(function () {
	$('.example-popover').popover({
		container: 'body'
	})
})

 

ポップオーバーの設定(Example)v4.0.0一部変更

見本
設定例
HTMLコピー<a class="btn btn-lg btn-danger" data-toggle="popover" title="ポップオーバーのタイトル" data-content="ポップオーバーの説明。もう一度ボタンを押すと閉じます。">ココを押して下さい</a>
実行コード
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>

【設定】

  • ボタンタグの要素に [data-toggle="popover"][title="ポップオーバーのタイトル"][data-content="ポップオーバーの説明"] を入れる
    ※タイトルはなくても可
  • bootstrap.min.js より前に Popper.js の設定が必要
    Popper.js をCDNで設置する場合は、クイックスタートを参照

【Bootstrap3.xとの変更箇所】

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

上、右、下、左の4つのオプション。

見本

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

設定例
上に出るポップオーバーコピー<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="上に出るポップオーバー">ポップオーバー(上)</button>
左に出るポップオーバーコピー<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="左に出るポップオーバー">ポップオーバー(左)</button>
下に出るポップオーバーコピー<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="下に出るポップオーバー">ポップオーバー(下)</button>
右に出るポップオーバーコピー<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="右に出るポップオーバー">ポップオーバー(右)</button>

【設定】

  • data-toggle="popover" と同じ要素に data-placement="xxx"xxxleft(左)、top(上)、bottom(下)、right(右)の中から選択)を入れる

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

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

見本
設定例
HTMLコピー<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="却下するポップアップ" data-content="ボタンを押しても閉じません。それ以外のところを押して閉じて下さい。">ココを押して下さい</a>
JavaScriptコピー$('.popover-dismiss').popover({
	trigger: 'focus'
})

【設定】

  • HTMLコードに入れる場合は、a[data-toggle="popover"]tabindex="0"data-trigger="focus" を入れる

無効な要素(Disabled elements)

disabled 属性を持つ要素はインタラクティブではないため、ユーザーがカーソルを移動したりクリックしてポップオーバー(またはツールチップ)を起動することは不可。回避策として、ラッパーの <div> または <span> からポップオーバーを起動し、無効化された要素の pointer-events を上書きする必要がある。

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

見本
設定例
コピー<span class="d-inline-block" data-toggle="popover" data-content="無効なポップオーバー">
	<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>無効ボタン</button>
</span>

 

使用方法(Usage)

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

JavaScript$('#example').popover(options)

オプション(Options)サンプル v4.0.0一部変更

オプションは、データ属性またはJavaScriptを使用して渡すことが可能。データ属性の場合、data-animation="" のように、data- にオプション名を追加。

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

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

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

オブジェクト構造は次のとおり:delay: { "show": 500, "hide": 100 }
html boolean false ポップオーバーにHTMLを挿入。falseの場合、jQueryの text メソッドがコンテンツをDOMに挿入するために使用される。
XSS攻撃が心配な場合はtextを使用すること。
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
v4.0.0一部変更
string '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' ポップオーバーを作成するときに使用するベースのHTML。

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

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

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

一番外側の包括要素には、.popover クラスを入れる必要がある。

配置方向を設定する場合は、.popover.popover-top, .popover-bottom, .popover-left, .popover-rightのいずれかを追加する。
title string | element | function '' title 属性が存在しない場合のデフォルトのタイトル値

functionを設定した場合、this 参照セットをポップオーバーが接続されている要素にセットして呼び出される。
trigger string 'click' ポップオーバーの起動方法 - click | hover | focus | manual
複数の起動方法を指定;スペースで区切る。manual は他と組み合わせ不可。
offset
v4.0.0追加
number | string 0 ターゲットに対するポップオーバーのオフセット値。詳細については、Popper.jsのoffsetドキュメントに記載。
fallbackPlacement
v4.0.0追加
string | array 'flip' Popperがフォールバックで使用する位置を指定できるようにする。詳細については、Popper.jsのbehaviorドキュメントに記載。
boundary
v4.0.0追加
string | element 'scrollParent' ポップオーバーのオーバーフローを制約する境界。'viewport', 'window', 'scrollParent' またはHTMLElementリファレンス(JavaScriptのみ)の値を受け入れる。詳細については、Popper.jsのpreventOverflowドキュメントに記載。

【変更履歴】

  • 【v4.0.0-beta.2】container のタイプに element が追加

    selector のタイプに false が追加

  • 【v4.0.0-beta.3】boundary が追加

【Bootstrap3.xとの変更箇所】

  • offsets, fallbackPlacement が追加
  • viewport は廃止
  • template
    • .popover-title.popover-header
    • .popover-content.popover-body
    • .top.popover-top
    • .bottom.popover-botoom
    • .left.popover-left
    • .right.popover-right
    に名称変更

メソッド(Methods)サンプル

$().popover(options)

要素コレクションのポップオーバーを初期化。

.popover('show')

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

JavaScript$('#element').popover('show')

.popover('hide')

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

JavaScript$('#element').popover('hide')

.popover('toggle')

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

JavaScript$('#element').popover('toggle')

.popover('dispose') v4.0.0名称変更

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

JavaScript$('#element').popover('dispose')

.popover('enable') v4.0.0追加

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

JavaScript$('#element').popover('enable')

.popover('disable') v4.0.0追加

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

JavaScript$('#element').popover('disable')

.popover('toggleEnabled') v4.0.0追加

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

JavaScript$('#element').popover('toggleEnabled')

.popover('update') v4.0.0追加

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

JavaScript$('#element').popover('update')

【Bootstrap3.xとの変更箇所】

  • .popover('destroy').popover('dispose') に名称変更
  • .popover('enable'), .popover('disable'), .popover('toggleEnabled'), .popover('update') が追加

イベント(Events)

イベントタイプ 説明
show.bs.popover このイベントは、show のインスタンス・メソッドが呼び出されると直ちに発動。
shown.bs.popover このイベントは、ユーザーにポップオーバーが表示されたときに発動(完全にCSS遷移が完了するまで待機)。
hide.bs.popover このイベントは、hide のインスタンス・メソッドが呼び出されると直ちに発動。
hidden.bs.popover このイベントは、ポップオーバーがユーザーから非表示になったときに発動(完全にCSS遷移が完了するまで待機)。
inserted.bs.popover このイベントは、ポップオーバーテンプレートがDOMに追加されたときに show.bs.popover イベントの後に発動。
使用例
JavaScript$('#myPopover').on('hidden.bs.popover', function () {
	// 何かをする...
})