Bootstrap4.xの使い方をBootstrap3.xからの変更箇所を交えて解説しています。
ポップオーバー(Popovers) v4.0.0設定変更
iOSにあるようなBootstrapのポップオーバーをサイトのどの要素にも追加するための解説と例。
概要(Overview)
ポップオーバー・プラグインを使用するときに知っておくべきこと:
- ポップオーバーは、サードパーティのライブラリであるPopperを使用して位置情報を取得しているため、ポップオーバーが動作するためには
bootstrap.js
かbootstrap.min.js
の前にpopper.min.jsを組み込むか、代わりにPopperを内部に含むbootstrap.bundle.js
かbootstrap.bundle.min.js
を使用する必要がある。 - ポップオーバーは、依存関係として、ツールチップ・プラグインが必要。
- ソースファイルからJavaScriptを構築する場合は、
util.js
が必要。 - ポップオーバーは、パフォーマンス上の理由で任意で取得されるため、自分で初期化する必要がある(そのため実行コードが必要)。
title
とcontent
の長さがゼロのポップオーバーは表示されない。container: 'body'
を指定すると、より複雑なコンポーネント(インプットグループやボタングループなど)のレンダリングの問題が回避可能。- 非表示要素のポップオーバーは機能しない。
.disabled
またはdisabled
要素のポップオーバーは、それを囲む要素で起動する必要がある。サンプル- 複数行にまたがるアンカーから起動されたときは、ポップオーバーはアンカー全体の幅の中央に配置される。この現象を回避するには、
<a>
に.text-nowrap
を使用する。 - ポップオーバーは、対応する要素がDOMから削除される前に非表示にする必要がある。
- ポップオーバーは、シャドウDOM内の要素のために起動可能。
ポップオーバーがどのように動作するかいくつか実例を表示。
どこでもポップオーバーを有効にする例(Example: Enable popovers everywhere)
ページ上のすべてのポップオーバーを初期化する方法の1つは、data-toggle
属性でそれらを選択すること。
実行コード
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
の設定が必要
※Popper
をCDNで設置する場合は、クイックスタートを参照
【変更履歴】
- 【v4.0.0】
- Popper の設置が必要
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>
【設定】
- ボタンタグの要素に
[data-toggle="popover"][title="ポップオーバーのタイトル"][data-content="ポップオーバーの説明"]
を入れる
※タイトルはなくても可
ポップオーバーの方向設定(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"
(xxx
はleft
(左)、top
(上)、bottom
(下)、right
(右)の中から選択)を入れる
次のクリックで閉じる(Dismiss on next click)
triggerに focus
を使用して、切替要素とは別の要素の次のクリックでポップオーバーを閉じる。
次のクリックで閉じるために必要な特定のマークアップ
クロスブラウザおよびクロスプラットフォームの適切な動作のためには、<button>
タグではなく、<a>
タグを使用する必要がある。また、tabindex
属性も入れる必要がある。
見本
設定例
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 type="button" class="btn btn-primary" style="pointer-events: none;" disabled>無効ボタン</button>
</span>
使用方法(Usage)
JavaScriptでポップオーバーを有効にする:
JavaScript$('#example').popover(options)
GPUアクセラレーション
GPUアクセラレーションと変更されたシステムDPIが原因で、Windows10デバイスでポップオーバーがぼやけて表示されることがある。v4でのこれの回避策は、ポップオーバーで必要に応じてGPUアクセラレーションを無効にすること。
推奨される修正:
JavaScriptPopper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))
ポップオーバーをキーボードおよび支援技術のユーザーに機能させる
キーボードユーザーがポップオーバーをアクティブにできるようにするには、従来キーボードでフォーカス可能で対話型のHTML要素(リンクやフォームコントロールなど)にのみ追加する必要がある。tabindex="0"
属性を追加することで任意のHTML要素(<span>
など)をフォーカス可能にすることができるが、これはキーボードユーザーにとっては非対話的要素に迷惑で混乱を招くタブ位置を追加してしまう。この状況では、支援技術は現在のところポップオーバーのコンテンツを表示できない。さらに、ポップオーバーの起動を hover
だけに頼らないこと。それだけではキーボードで起動はできない。
html
オプションを使ってポップオーバーに豊富で構造化されたHTMLを挿入することは可能だが、過剰な量のコンテンツを追加しないことを強く推奨。現在のポップオーバーの動作方法は、一度表示されると、その内容は aria-describeby
属性を持つトリガー要素に結び付けられてしまう。結果として、ポップオーバーのコンテンツ全体が、1つの長く途切れないストリームとして支援技術のユーザーに表示されるだろう。
さらに(これらの要素を whiteList
や許可された属性とタグに追加することによって)ポップオーバーに対話型のコントロール(フォーム要素やリンクなど)を含めることも可能だが、現在のポップオーバーはキーボードフォーカスを管理していない。キーボードユーザーがポップオーバーを開いても、フォーカスはトリガー要素に留まる。通常、ポップオーバーはドキュメントの構造内のトリガーにすぐには追従しないため、前方に移動したり Tab を押してもキーボードユーザーがポップオーバー自体に移動するとは限らない。要するに、ポップオーバーに対話型のコントロールを追加するだけでは、キーボードユーザーや支援技術を使用するユーザーにとって、これらのコントロールにアクセスもしくは使用できなくなる可能性がある。このような場合は、代わりにモーダルダイアログを使用することを検討すること。
オプション(Options)サンプル v4.6.0一部追加
オプションは、データ属性またはJavaScriptを使用して渡すことが可能。データ属性の場合、data-animation=""
のように、data-
にオプション名を追加。
sanitize
, sanitizeFn
, whiteList
オプションは、データ属性を使用して指定することは不可。
名前 | タイプ | デフォルト | 説明 |
---|---|---|---|
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攻撃が心配な場合はテキストを使用すること。 true :有効/false :無効 |
placement | string | function | 'right' | ポップオーバーの配置方法 - auto | top | bottom | left | rightauto が指定されると、動的にポップオーバーの向きが変更。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のoffsetドキュメントに記載。 |
fallbackPlacement v4.0.0追加 |
string | array | 'flip' | Popperがフォールバックで使用する位置を指定できるようにする。詳細については、Popperのbehaviorドキュメントに記載。 |
customClass v4.6.0追加 |
string | function | '' | 表示されたら、ポップオーバーにクラスを追加する。これらのクラスは、テンプレートで指定されたクラスに加えて追加されるので注意。複数のクラスを追加するには、それらをスペースで区切る:'a b' 追加のクラス名を含む単一の文字列を返す関数を渡すことも可能。 |
boundary v4.0.0追加 |
string | element | 'scrollParent' | ポップオーバーのオーバーフローを制約する境界。'viewport' , 'window' , 'scrollParent' またはHTMLElementリファレンス(JavaScriptのみ)の値を受け入れる。詳細については、PopperのpreventOverflowドキュメントに記載。 |
sanitize v4.3.1追加 |
boolean | true | サニタイズを有効/無効にする。有効にすると、'template' , 'content' , 'title' オプションはサニタイズされる。true :有効/false :無効 |
whiteList v4.3.1追加 |
object | デフォルト値 | 許可された属性とタグを含むオブジェクト |
sanitizeFn v4.3.1追加 |
null | function | null | 自分用のサニタイズ機能を提供することが可能。サニタイズを実行するために専用のライブラリを使用したい場合に役立つ。 |
popperConfig v4.4.0追加 |
null | object | null | BootstrapのデフォルトのPopperの構成を変更。詳細は、Popperの構成を参照。 |
【変更履歴】
- 【v4.0.0】
offsets
,fallbackPlacement
,boundary
が追加viewport
は廃止container
のタイプにelement
、selector
のタイプにfalse
がそれぞれ追加template
:.popover-title
⇒.popover-header
.popover-content
⇒.popover-body
.top
⇒.popover-top
.bottom
⇒.popover-botoom
.left
⇒.popover-left
.right
⇒.popover-right
- 【v4.3.1】
sanitize
,sanitizeFn
,whiteList
が追加
- 【v4.4.0】
popperConfig
が追加
- 【v4.6.0】
customClass
が追加
個々のポップオーバーのデータ属性
上記で説明したように、個々のポップオーバーのオプションは、データ属性(data-オプション名
)を使用して指定することが可能(sanitize
, sanitizeFn
, whiteList
を除く)。
メソッド(Methods)サンプル
非同期メソッドと遷移
すべてのAPIメソッドは、非同期で遷移を開始する。それらは移行が始まるとすぐに呼び出し元に戻るが、終了する前に呼び出し元に戻る。さらに、遷移コンポーネントのメソッド呼び出しは無視される。
詳細については、Javascriptのドキュメントに記載。
$().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')
【変更履歴】
- 【v4.0.0】
.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 () {
// 何かをする...
})