Skip to main content Skip to docs navigation
Bootstrapの新しいバージョンがあります。

Popovers (ポップオーバー)

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

Overview

popoverプラグインを使うときに知っておきたいこと

  • Popovers はサードパーティ製のライブラリ Popper に依存しています。
  • popoverを動作させるには、bootstrap.jsの前に popper.min.js をインクルードするか、popper.jsを含む bootstrap.bundle.min.js / bootstrap.bundle.js を使用しなければなりません。
  • Popovers は、依存関係としてtooltip pluginが必要です。
  • Popovers はパフォーマンス上の理由からオプトインになっているので、自分で初期化する必要があります。
  • titlecontent の値の長さがゼロの場合は Popovers を表示しません。
  • 複雑なコンポーネント(入力グループやボタングループなど)でのレンダリングの問題を避けるために container: 'body' を指定します。
  • 隠された要素でポップアップオーバーをトリガーすると動作しません。
  • .disabled 要素のポップオーバーは、ラッパー要素上でトリガされなければなりません。
  • 複数の行にまたがるアンカーからトリガーされると、Popovers はアンカーの全幅の中央に配置されます。 この動作を回避するには、<a>.text-nowrap を使用します。
  • Popoversは、対応する要素がDOMから削除される前に非表示にする必要があります。
  • Popovers はshadow DOM 内の要素のおかげでトリガーすることができます。
デフォルトでは、このコンポーネントは内蔵のコンテンツサニタイザーを使用しており、明示的に許可されていない HTML 要素を取り除いています。詳細は、JavaScript ドキュメントの sanitizer セクションを参照してください。
このコンポーネントのアニメーション効果は、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 を適用します。例 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 を追加できるようにするために使用されます。参照 thisan 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 ここでは、独自のサニタイズ関数を指定することができます。これは、サニタイズを実行するために専用のライブラリを使いたい場合に便利です。
offset array | string | function [0, 8]

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

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

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 メソッドは非同期で、トランジションを開始します。トランジションが開始されると同時に呼び出し元に返されますが、トランジションが終了する前に返されます。また、遷移中のコンポーネントに対するメソッドコールは無視されます

詳しくは JavaScript のドキュメントをご覧ください

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