Popovers

Popovers(ポップオーバー)についてのドキュメントと例です。

Overview

Popover Pluginを使用するときに知っておくべきこと:

  • 第三者のライブラリ Popper.js で位置を取得します。bootstrap.jsの前にpopper.min.js を含めるか Popper.jsを含む bootstrap.bundle.min.jsbootstrap.bundle.js を使用する必要があります。
  • 依存関係として tooltip plugin が必要です。
  • ソースからJavaScriptを部いるどする場合は requires util.js が必要です。
  • パフォーマンス上の理由からオプトインするので, 自分で初期化する必要があります。
  • 長さが0のtitlecontent はポップオーバーを表示されません
  • container: 'body' を指定すると, 複雑なコンポーネント(インプットグループ,ボタングループなど)のレンダリングの問題が回避可能です。
  • 非表示要素のポップオーバーは機能しません。
  • .disabled , disabled 要素のポップオーバーはそれを囲む要素で起動する必要があります。
  • 複数行にまたがるアンカーからトリガーすると, アンカーの全体的な幅の中央にポップオーバーが配置されます。この動作を避けるために <a>text-nowrap を使用します。
  • ポップオーバーは, 対応する要素がDOMから削除される前に非表示にする必要があります。

どのように動作するかは下記を参考にしてください。

Example: Enable popovers everywhere

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

$(function () {
  $('[data-toggle="popover"]').popover()
})

Example: Using the container option

ポップオーバーに干渉するスタイルが親要素にある場合は, ポップオーバーのHTMLが代わりにその要素内に表示されるように container の指定をすることを推奨します。

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

Example

<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Four directions

上, 右, 下, 左の4つのオプションがあります。

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

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on right
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on bottom
</button>

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

Dismiss on next click

focus を使用して, トグル要素とは別の要素の次のクリックに対するポップオーバーを閉じます。

Specific markup required for dismiss-on-next-click

For proper cross-browser and cross-platform behavior, you must use the <a> tag, not the <button> tag, and you also must include a tabindex attribute.

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
$('.popover-dismiss').popover({
  trigger: 'focus'
})

Disabled elements

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

無効化されたポップオーバーのトリガーの場合, 無効化された要素をクリックすると予想されないため, ポップオーバーがユーザーに視覚的なフィードバックとしてすぐに表示されるように data-trigger="hover" を適用することもできます。

<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

Usage

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

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

Options

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

Name Type Default Description
animation boolean true Apply a CSS fade transition to the popover
container string | element | false false

Appends the popover to a specific element. Example: container: 'body'. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.

content string | element | function ''

Default content value if data-content attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the popover is attached to.

delay number | object 0

Delay showing and hiding the popover (ms) - does not apply to manual trigger type

If a number is supplied, delay is applied to both hide/show

Object structure is: delay: { "show": 500, "hide": 100 }

html boolean false Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement string | function 'right'

How to position the popover - auto | top | bottom | left | right.
When auto is specified, it will dynamically reorient the popover.

When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the popover instance.

selector string | false false If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See this and an informative example.
template string '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Base HTML to use when creating the popover.

The popover's title will be injected into the .popover-header.

The popover's content will be injected into the .popover-body.

.arrow will become the popover's arrow.

The outermost wrapper element should have the .popover class.

title string | element | function ''

Default title value if title attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the popover is attached to.

trigger string 'click' How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
offset number | string 0 Offset of the popover relative to its target. For more information refer to Popper.js's offset docs.
fallbackPlacement string | array 'flip' Allow to specify which position Popper will use on fallback. For more information refer to Popper.js's behavior docs
boundary string | element 'scrollParent' Overflow constraint boundary of the popover. Accepts the values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs.

Data attributes for individual popovers

Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.

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.

$().popover(options)

ポップオーバーを初期化します。

.popover('show')

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

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

.popover('hide')

ポップオーバーを非表示にします。ポップオーバーが実際に隠される前( hidden.bs.popover が発生する前)に呼び出し元に戻ります。手動のトリガとみなされます。

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

.popover('toggle')

ポップオーバーを切り替えます。ポップオーバーの前に呼び出し元に戻りますが, 実際に表示または非表示にされている( shown.bs.popover , hidden.bs.popover が発生します)。手動のトリガとみなされます。

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

.popover('dispose')

ポップオーバーを隠したり破棄したりします。( the selector option で作成されます。)子孫トリガー要素で個別に破棄することはできません。

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

.popover('enable')

ポップオーバーに表示する機能を与えます。デフォルトでは, ポップオーバーが有効になっています。

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

.popover('disable')

ポップオーバーが表示されるようにする機能を削除します。ポップオーバーは, 再び有効にされた場合にのみ表示することができます。

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

.popover('toggleEnabled')

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

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

.popover('update')

ポップオーバーの位置を更新します。

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

Events

Event Type Description
show.bs.popover This event fires immediately when the show instance method is called.
shown.bs.popover This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.popover This event is fired immediately when the hide instance method has been called.
hidden.bs.popover This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).
inserted.bs.popover This event is fired after the show.bs.popover event when the popover template has been added to the DOM.
$('#myPopover').on('hidden.bs.popover', function () {
  // do something…
})

v4.2