Popovers (ポップオーバー)
ポップオーバーをサイト上の任意の要素に追加するためのドキュメントと例を示します。
Overview
popoverプラグインを使うときに知っておきたいこと
- Popovers はサードパーティ製のライブラリ Popper に依存しています。
- popoverを動作させるには、bootstrap.jsの前に popper.min.js をインクルードするか、popper.jsを含む
bootstrap.bundle.min.js/bootstrap.bundle.jsを使用しなければなりません。 - Popovers は、依存関係としてtooltip pluginが必要です。
- Popovers はパフォーマンス上の理由からオプトインになっているので、自分で初期化する必要があります。
titleとcontentの値の長さがゼロの場合は Popovers を表示しません。- 複雑なコンポーネント(入力グループやボタングループなど)でのレンダリングの問題を避けるために
container: 'body'を指定します。 - 隠された要素でポップアップオーバーをトリガーすると動作しません。
.disabled要素のポップオーバーは、ラッパー要素上でトリガされなければなりません。- 複数の行にまたがるアンカーからトリガーされると、Popovers はアンカーの全幅の中央に配置されます。 この動作を回避するには、
<a>で.text-nowrapを使用します。 - Popoversは、対応する要素がDOMから削除される前に非表示にする必要があります。
- Popovers はshadow DOM 内の要素のおかげでトリガーすることができます。
prefers-reduced-motionメディアクエリに依存します。アクセシビリティドキュメントの reduced motion セクションを参照してください。
Popovers がどのように機能するかを確認するために読んでください。
Example: Enable popovers everywhere
ページ上のすべてのポップオーバーを初期化する1つの方法は、 data-bs-toggle属性でポップオーバーを選択することです。
var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
return new bootstrap.Popover(popoverTriggerEl)
})
Example: Using the container option
親要素に Popovers を妨げるいくつかのスタイルがある場合は、代わりにカスタムの containerを指定して、ポップオーバーのHTMLがその要素内に表示されるようにします。
var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
container: 'body'
})
Example
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>Four directions
上、右、下、左揃えの4つのオプションを使用できます。 RTLでBootstrapを使用すると、方向がミラーリングされます。
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
Popover on left
</button>Dismiss on next click
ユーザーが次にトグル要素以外の要素をクリックしたときに Popovers を閉じるには、focusトリガーを使用します。
Specific markup required for dismiss-on-next-click
ブラウザーやプラットフォームに関係なく適切に動作させるには、 <a> タグを使用し、<button> タグを使用しないでください。また、tabindex 属性を含める必要があります。
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
trigger: 'focus'
})
Disabled elements
disabled属性を持つ要素はインタラクティブではありません。つまり、ユーザーはそれらにカーソルを合わせたりクリックしたりして、ポップオーバー（またはツールチップ）をトリガーすることはできません。回避策として、ラッパー <div>または <span>からポップオーバーをトリガーし、無効になっている要素の pointer-eventsをオーバーライドする必要があります。
無効化された Popovers のトリガーについては、data-trigger="hover" を使用できます。これにより、ユーザーは無効化された要素を click することを期待していないため、Popoversがすぐに視覚的なフィードバックとしてユーザーに表示されます。
<span class="d-inline-block" data-bs-toggle="popover" data-bs-content="Disabled popover">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>Sass
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
JavaScriptで popoversを有効にします。
var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)
Making popovers work for keyboard and assistive technology users
キーボードユーザーが Popovers をアクティブにするには、キーボードフォーカスが可能でインタラクティブな HTML 要素（リンクやフォームコントロールなど）に追加する必要があります。
任意の HTML 要素（ <span> など）は tabindex="0" 属性を追加することでフォーカス可能ですが、これはキーボードユーザーには非インタラクティブな要素のタブストップが追加され、混乱を招く可能性があります。
Popovers のトリガーを hover だけに頼ってはいけません。これにより、キーボードユーザーがポップオーバーをトリガーできなくなります。
html オプションでリッチで構造化された HTML を Popovers に挿入することができますが、過剰な量のコンテンツ追加は避けることを強くお勧めします。
Popovers が現在機能する方法は、一度表示されると、そのコンテンツは aria-describedby 属性を持つトリガー要素に結び付けられます。
その結果、 Popovers のコンテンツ全体が、スクリーンリーダーを利用するユーザーに長くて途切れることのないストリームとしてアナウンスされることになります。
さらに、(フォーム要素やリンクなどの)インタラクティブなコントロールを Popovers に含めることも可能ですが、(これらの要素を allowList や許可されている属性やタグに追加することで)、現在のところ、Popovers はキーボードフォーカスの順序を管理していないことに注意してください。
キーボードユーザーがポップオーバーを開くと、フォーカスはトリガー要素のままで、Popover は通常、ドキュメントの構造のトリガーにすぐに追従しないので、TABを前方に移動/押しても、キーボードユーザーがポップオーバー自体に移動するという保証はありません。
要するに、単に Popover にインタラクティブなコントロールを追加するだけでは、キーボードユーザーやスクリーンリーダーを利用するユーザーにとって、これらのコントロールにアクセスできない/使用できない、あるいは少なくとも全体的に非論理的なフォーカスの順序になってしまう可能性があります。このような場合は、代わりに modal dialog (モーダル)の使用を検討してください。
Options
オプションは、データ属性またはJavaScriptで渡すことができます。データ属性の場合は、 data-bs-animation =" "のように、オプション名を data-bs-に追加します。
sanitize, sanitizeFn および allowList オプションはデータ属性を用いて指定することができないことに注意してください。
| Name | Type | Default | Description |
|---|---|---|---|
animation |
boolean | true | ポップオーバーにCSSのフェード遷移を適用します。 |
container |
string | element | false | false |
特定の要素に Popover を適用します。例 |
content |
string | element | function | '' |
関数が与えられた場合は、その |
delay |
number | object | 0 |
Popover の表示と非表示の遅延 (ms) - 手動トリガータイプには適用されません。 数値が与えられた場合、非表示/表示の両方に遅延が適用されます。 オブジェクト構造 : |
html |
boolean | false | Popover に HTML を挿入します。falseの場合、innerTextプロパティを使用してDOMにコンテンツを挿入します。XSS攻撃が心配な場合はテキストを使用します。 |
placement |
string | function | 'right' |
Popover の配置方法 - auto | top | bottom | left | right. 配置を決定するために関数を使用する場合、この関数は popover DOM ノードを第一引数に、triggering element DOM ノードを第二引数にして呼び出されます。 The |
selector |
string | false | false | セレクタが提供されている場合、ポップアップオブジェクトは指定されたターゲットに委譲されます。実際には、これは動的な HTML コンテンツに Popover を追加できるようにするために使用されます。参照 this と an informative example. |
template |
string | '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' |
Popover を作成する際に使用する基本HTML。 Popover の Popover の
一番外側のラッパー要素は |
title |
string | element | function | '' |
関数が与えられた場合、その |
trigger |
string | 'click' |
Popover のトリガー方法 - click | hover | focus | manual. 複数のトリガーを渡すことができます。; manual他のトリガーと組み合わせることはできません。 |
fallbackPlacements |
string | array | 'flip' |
フォールバック時に Popper がどの位置を使用するかを指定することができます。詳細は Popper.js のbehavior docsを参考にしてください。 |
boundary |
string | element | 'scrollParent' |
Popover のオーバーフロー制約境界。 Accepts the values of 'viewport', 'window', 'scrollParent', または HTMLElement 参照 (JavaScript のみ) の値を受け取ります。詳細は Popper.js の preventOverflow docs を参考にしてください。 |
customClass |
string | function | '' |
表示されたら、ポップオーバーにクラスを追加します。テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、それらをスペースで区切ります： 追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。 |
sanitize |
boolean | true | サニタイズを有効にするか無効にします。有効にした場合、'template'、'content'、'title'オプションはサニタイズされます。参考: sanitizer section in our JavaScript documentation. |
allowList |
object | Default value | 許可された属性とタグを含むオブジェクト |
sanitizeFn |
null | function | null | ここでは、独自のサニタイズ関数を指定することができます。これは、サニタイズを実行するために専用のライブラリを使いたい場合に便利です。 |
offset |
array | string | function | [0, 8] |
ターゲットに対するポップオーバーのオフセット。 次のように、カンマ区切りの値を使用してデータ属性に文字列を渡すことができます。 関数を使用してオフセットを決定する場合、ポッパーの配置、参照、およびポッパーの四角形を最初の引数として含むオブジェクトを使用して呼び出されます。トリガー要素のDOMノードが2番目の引数として渡されます。 関数は、次の2つの数値を持つ配列を返す必要があります。: For more information refer to Popper's offset docs. |
popperConfig |
null | object | null | BootstrapのデフォルトのPopper.jsの設定を変更するには Popper.js's configurationを参考にしてください。 |
Data attributes for individual popovers
個々の Popover のオプションは、上で説明したように、データ属性を使用して指定することもできます。
Using function with popperConfig
var popover = new bootstrap.Popover(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Methods
非同期のメソッドとトランジション
すべての API メソッドは非同期で、トランジションを開始します。トランジションが開始されると同時に呼び出し元に返されますが、トランジションが終了する前に返されます。また、遷移中のコンポーネントに対するメソッドコールは無視されます。
show
popover 要素を表示します。 Popover が実際に表示される前に呼び出し元に戻ります。 (shown.bs.popover が発生する前に).
これは Popover の “manual” トリガーとみなされます。タイトルと内容の両方の表示するにようがゼロの場合は Popover は表示されません。
myPopover.show()
hide
popover 要素を非表示にします。
Hides an element’s popover. Popover が実際に非表示される前に呼び出し元に戻ります。 (hidden.bs.popoverがイベントが発生する前).
これは Popover の “manual” トリガーとみなされます。
myPopover.hide()
toggle
popover 要素をトグルします。
Toggles an element’s popover. ポップオーバーが実際に表示または非表示になる前に呼び出し元に戻ります (shown.bs.popover や hidden.bs.popover が発生する前). これは Popover の “manual” トリガーとみなされます。
myPopover.toggle()
dispose
popover 要素を非表示にして破棄します。
デリゲーションを使用する Popover(the selector option) を使用して作成されたものは、子孫のトリガ要素上で個別に破壊することはできません。
myPopover.dispose()
enable
popover 要素 を表示する機能を与えます デフォルトは有効
myPopover.enable()
disable
popover 要素を表示する機能を削除します。ポップオーバーは再有効化された場合にのみ表示されます。
myPopover.disable()
toggleEnabled
popover 要素を表示・非表示を切り替えます。
myPopover.toggleEnabled()
update
popover の位置を更新します。
myPopover.update()
getInstance
DOM 要素に関連付けられた Popover のインスタンスを取得できるようにする静的メソッド
var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
Events
| Event type | Description |
|---|---|
| show.bs.popover | showインスタンスメソッドが呼び出されたときにすぐに発生します。 |
| shown.bs.popover | Popover がユーザーに見えるようになったときに発生します (CSS トランジションが完了するのを待ちます)。 |
| hide.bs.popover | hideインスタンスメソッドが呼び出されたときにすぐに発生します。 |
| hidden.bs.popover | Popover の非表示が完了したときに発生します (CSS トランジションが完了するのを待ちます)。 |
| inserted.bs.popover | show.bs.popover イベントの後に、Popover のテンプレートが DOM に追加されたときに発生します。 |
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
// do something...
})