View on GitHub

Popovers (ポップオーバー)

ポップオーバーをサイト上の任意の要素に追加するためのドキュメントと例を示します。

On this page

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 内の要素のおかげでトリガーすることができます。

By default, this component uses the built-in content sanitizer, which strips out any HTML elements that are not explicitly allowed. See the sanitizer section in our JavaScript documentation for more details.

The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation.

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

上、右、下、左と表示値を選択できます。

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on left
</button>

Dismiss on next click

ユーザーが次にトグル要素以外の要素をクリックしたときに Popovers を閉じるには、focusトリガーを使用します。

Specific markup required for dismiss-on-next-click

ブラウザーやプラットフォームに関係なく適切に動作させるには、 <a> タグを使用し、<button> タグを使用しないでください。また、tabindex 属性を含める必要があります。

Dismissible popover

<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>

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 を適用します。例 `container: 'body'`. このオプションは、ドキュメントの流れの中で Popover をトリガー要素の近くに配置することができるという点で特に便利です。これにより、ウィンドウのサイズ変更中にポップオーバーがトリガー要素から浮き上がるのを防ぐことができます。
`content`	string \| element \| function	''	`data-content`属性が存在しない場合のデフォルトの内容の値。関数が与えられた場合は、その `this` 参照が Popover がアタッチされている要素に設定された状態で呼び出されます。
`delay`	number \| object	0	Popover の表示と非表示の遅延 (ms) - 手動トリガータイプには適用されません。数値が与えられた場合、非表示/表示の両方に遅延が適用されます。オブジェクト構造 : `delay: { "show": 500, "hide": 100 }`
`html`	boolean	false	Popover に HTML を挿入します。falseの場合、`innerText`プロパティを使用してDOMにコンテンツを挿入します。XSS攻撃が心配な場合はテキストを使用します。
`placement`	string \| function	'right'	Popover の配置方法 - auto \| top \| bottom \| left \| right. When `auto` を指定すると、動的にポップオーバーの配置を変更します。配置を決定するために関数を使用する場合、この関数は popover DOM ノードを第一引数に、triggering element DOM ノードを第二引数にして呼び出されます。 The `this` コンテキストは Popover のインスタンスに設定されています。
`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 の `title` は `.popover-header` に適用されます。 Popover の `content` は `.popover-body` に適用されます。 `.popover-arrow`がポップアップの矢印になります。一番外側のラッパー要素は `.popover` クラスを持っていなければなりません。
`title`	string \| element \| function	`''`	`title`属性が存在しない場合のデフォルトのタイトル値。関数が与えられた場合、その `this` 参照が Popover がアタッチされている要素に設定された状態で呼び出されます。
`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	`''`	表示されたら、ポップオーバーにクラスを追加します。テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、それらをスペースで区切ります： `'class-1 class-2'`. 追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。
`sanitize`	boolean	true	サニタイズを有効にするか無効にします。有効にした場合、`'template'`、`'content'`、`'title'`オプションはサニタイズされます。参考: sanitizer section in our JavaScript documentation.
`allowList`	object	Default value	許可された属性とタグを含むオブジェクト
`sanitizeFn`	null \| function	null	ここでは、独自のサニタイズ関数を指定することができます。これは、サニタイズを実行するために専用のライブラリを使いたい場合に便利です。
`popperConfig`	null \| object	null	BootstrapのデフォルトのPopper.jsの設定を変更するには Popper.js's configurationを参考にしてください。

Data attributes for individual popovers

個々の Popover のオプションは、上で説明したように、データ属性を使用して指定することもできます。

Methods

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

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...
})