in English

ポップオーバー

iOS に見られるような Bootstrap ポップオーバーをサイトの任意の要素に追加するためのドキュメントと例。

概要

popover プラグインを使用する際に知っておくべきこと:

  • ポップオーバーは、ポジショニングのためにサードパーティのライブラリPopperに依存しています。ポップオーバーを機能させるには、 popper.min.jsを bootstrap.js の前に含めるか、Popper を含むbootstrap.bundle.min.js/を使用する必要があります。bootstrap.bundle.js
  • ポップオーバーには、依存関係としてツールチップ プラグインが必要です。
  • JavaScript をソースからビルドする場合util.js、 .
  • ポップオーバーはパフォーマンス上の理由からオプトインであるため、自分で初期化する必要があります
  • 長さtitlecontent値がゼロの場合、ポップオーバーは表示されません。
  • container: 'body'より複雑なコンポーネント (入力グループ、ボタン グループなど) でのレンダリングの問題を回避するために指定します。
  • 非表示の要素でポップオーバーをトリガーしても機能しません。
  • .disabledまたは要素のポップオーバーはdisabled、ラッパー要素でトリガーする必要があります。
  • 複数の行にまたがるアンカーからトリガーされると、ポップオーバーはアンカーの幅全体の中央に配置されます。この動作を回避するには、 でを使用.text-nowrapします。<a>
  • 対応する要素が DOM から削除される前に、ポップオーバーを非表示にする必要があります。
  • Shadow DOM 内の要素のおかげで、ポップオーバーをトリガーできます。
デフォルトでは、このコンポーネントは組み込みのコンテンツ サニタイザーを使用し、明示的に許可されていない HTML 要素を取り除きます。詳細については 、JavaScript ドキュメントのサニタイザーのセクションを参照してください。
このコンポーネントのアニメーション効果は、 prefers-reduced-motionメディア クエリに依存します。アクセシビリティ ドキュメントの縮小モーション セクションを参照してください 。

読み続けて、いくつかの例でポップオーバーがどのように機能するかを確認してください。

例: どこでもポップオーバーを有効にする

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

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

例:containerオプションの使用

親要素にポップオーバーに干渉するスタイルがある場合、container代わりにポップオーバーの HTML がその要素内に表示されるようにカスタムを指定する必要があります。

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

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

四方

上揃え、右揃え、下揃え、左揃えの 4 つのオプションを使用できます。

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Left popover">
  Popover on left
</button>

次のクリックで閉じる

トリガーを使用してfocus、トグル要素とは異なる要素をユーザーが次にクリックしたときにポップオーバーを閉じます。

次のクリックで閉じるには特定のマークアップが必要

クロスブラウザーおよびクロスプラットフォームで適切に動作させるには、タグではなくタグを使用する必要<a>あり、属性<button>も含める必要があります。tabindex

<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はインタラクティブではありません。つまり、ユーザーはそれらをホバーしたりクリックしたりして、ポップオーバー (またはツールヒント) をトリガーすることはできません。回避策として、ラッパーからポップオーバーをトリガーする<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>

使用法

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

$('#example').popover(options)
GPU アクセラレーション

GPU アクセラレーションと変更されたシステム DPI が原因で、Windows 10 デバイスでポップオーバーがぼやけて表示されることがあります。v4 でのこの回避策は、ポップオーバーで必要に応じて GPU アクセラレーションを無効にすることです。

推奨される修正:

Popper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))

キーボードと支援技術のユーザー向けにポップオーバーを機能させる

キーボード ユーザーがポップオーバーをアクティブにできるようにするには、従来キーボード フォーカス可能でインタラクティブな HTML 要素 (リンクやフォーム コントロールなど) にのみ追加する必要があります。属性を追加することで、任意の HTML 要素 ( <span>s など) をフォーカス可能にできますがtabindex="0"、これにより、キーボード ユーザーの非対話型要素に迷惑で紛らわしいタブ ストップが追加される可能性があります。現在、ほとんどの支援技術は、この状況でポップオーバーの��ンテンツを通知しません。 . hoverさらに、ポップオーバーのトリガーとしてのみに依存しないでください。キーボード ユーザーがポップオーバーをトリガーできなくなります。

オプションを使用してリッチで構造化された HTML をポップオーバーに挿入できますがhtml、過剰な量のコンテンツを追加しないことを強くお勧めします。ポップオーバーが現在機能する方法は、一度表示されると、それらのコンテンツがaria-describedby属性を持つトリガー要素に結び付けられるというものです。その結果、ポップオーバーのコンテンツ全体が、1 つの長く途切れのないストリームとして支援技術ユーザーに通知されます。

さらに、インタラクティブなコントロール (フォーム要素やリンクなど) をポップオーバーに含めることもできますが (これらの要素をwhiteListまたは 許可された属性とタグに追加することによって)、現在、ポップオーバーはキーボード フォーカスの順序を管理しないことに注意してください。キーボード ユーザーがポップオーバーを開くと、フォーカスはトリガー要素に残ります。ポップオーバーは通常、ドキュメントの構造内でトリガーのすぐ後に続くわけではないため、前方に移動したり押したりする保証はありません。TABキーボード ユーザーをポップオーバー自体に移動します。要するに、単純にインタラクティブなコントロールをポップオーバーに追加すると、キーボード ユーザーや支援技術のユーザーがこれらのコントロールにアクセスできなくなったり、使用できなくなったり、少なくとも全体的なフォーカス順序が非論理的になる可能性があります。このような場合は、代わりにモーダル ダイアログの使用を検討してください。

オプション

オプションは、データ属性または JavaScript を介して渡すことができます。data-データ属性の場合、オプション名をのようにに追加しますdata-animation=""

セキュリティ上の理由から、、およびオプションは、データ属性を使用して提供できないことに注意し sanitizesanitizeFnください whiteList
名前 タイプ デフォルト 説明
アニメーション ブール値 真実 ポップオーバーに CSS フェード トランジションを適用する
容器 文字列 | 要素 | 間違い 間違い

ポップオーバーを特定の要素に追加します。例: container: 'body'. このオプションは、ドキュメントのフロー内でトリガー要素の近くにポップオーバーを配置できるという点で特に便利です。これにより、ウィンドウのサイズ変更中にポップオーバーがトリガー要素から離れてしまうのを防ぐことができます。

コンテンツ 文字列 | 要素 | 関数 ''

data-content属性が存在しない場合のデフォルトのコンテンツ値。

関数が指定されている場合this、ポップオーバーがアタッチされている要素に設定された参照で呼び出されます。

遅れ 数 | 物体 0

ポップオーバーの表示と非表示の遅延 (ミリ秒) - 手動トリガー タイプには適用されません

数値が指定されている場合、表示/非表示の両方に遅延が適用されます

オブジェクト構造は次のとおりです。delay: { "show": 500, "hide": 100 }

html ブール値 間違い ポップオーバーに HTML を挿入します。false の場合、jQuery のtextメソッドを使用してコンテンツを DOM に挿入します。XSS 攻撃が心配な場合は、テキストを使用してください。
配置 文字列 | 関数 '右'

ポップオーバーの配置方法 - 自動 | トップ | ボトム | 左 | 左 | 右。
を指定するautoと、ポップオーバーの向きが動的に変更されます。

配置を決定するために関数が使用される場合、最初の引数として popover DOM ノード、2 番目の引数としてトリガー要素 DOM ノードで関数が呼び出されます。thisコンテキストは popover インスタンスに設定されます。

セレクタ 文字列 | 間違い 間違い セレクターが提供されている場合、ポップオーバー オブジェクトは指定されたターゲットに委譲されます。実際には、これは動的 HTML コンテンツにポップオーバーを追加できるようにするために使用されます。これ有益な例を参照してください。
テンプレート ストリング '<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クラスが必要です。

題名 文字列 | 要素 | 関数 ''

title属性が存在しない場合のデフォルトのタイトル値。

関数が指定されている場合this、ポップオーバーがアタッチされている要素に設定された参照で呼び出されます。

引き金 ストリング 'クリック' ポップオーバーのトリガー方法 - クリック | ホバー | フォーカス | マニュアル。複数のトリガーを渡すことができます。スペースで区切ります。manual他のトリガーと組み合わせることはできません。
オフセット 数 | ストリング 0 ターゲットに対するポップオーバーのオフセット。詳細については、Popper のオフセット ドキュメントを参照してください。
フォールバック配置 文字列 | 配列 「フリップ」 Popper がフォールバックで使用する位置を指定できるようにします。詳細については、Popper の動作に関するドキュメントを参照してください。
カスタムクラス 文字列 | 関数 ''

ポップオーバーが表示されたらクラスを追加します。これらのクラスは、テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、クラスをスペースで区切ります: 'a b'.

追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。

境界 文字列 | エレメント 「スクロール親」 ポップオーバーのオーバーフロー制約境界。'viewport''window''scrollParent'、または HTMLElement 参照 (JavaScript のみ)の値を受け入れます。詳細については、Popper のpreventOverflow docsを参照してください。
消毒する ブール値 真実 サニタイズを有効または無効にします。有効'template'にする'content'と、'title'オプションがサニタイズされます。JavaScript ドキュメントのサニタイザーのセクションを参照してください。
ホワイトリスト 物体 デフォルト値 許可された属性とタグを含むオブジェクト
サニタイズFn null | null | 関数 ヌル ここでは、独自のサニタイズ関数を指定できます。これは、専用のライブラリを使用してサニタイズを実行したい場合に役立ちます。
popperConfig null | null | 物体 ヌル Bootstrap のデフォルトの Popper 設定を変更するには、Popper の設定を参照してください。

個々のポップオーバーのデータ属性

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

メソッド

非同期メソッドと遷移

すべての API メソッドは非同期であり、遷移を開始します。トランジションが開始されるとすぐに呼び出し元に戻りますが、トランジションが終了する前に戻ります。さらに、遷移中のコンポーネントでのメソッド呼び出しは無視されます。

詳細については、JavaScript のドキュメントを参照してください

$().popover(options)

要素コレクションのポップオーバーを初期化します。

.popover('show')

要素のポップオーバーを表示します。ポップオーバーが実際に表示される前 (つまり、イベントが発生する前)に呼び出し元に戻ります。shown.bs.popoverこれは、ポップオーバーの「手動」トリガーと見なされます。タイトルとコンテンツの長さがどちらもゼロのポップオーバーは表示されません。

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

.popover('hide')

要素のポップオーバーを非表示にします。ポップオーバーが実際に非表示になる前 (つまり、イベントが発生する前)に呼び出し元に戻ります。hidden.bs.popoverこれは、ポップオーバーの「手動」トリガーと見なされます。

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

.popover('toggle')

要素のポップオーバーを切り替えます。ポップオーバーが実際に表示または非表示になる前 (つまり、orイベントが発生する前)に呼び出し元に戻ります。これは、ポップオーバーの「手動」トリガーと見なされます。shown.bs.popoverhidden.bs.popover

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

.popover('dispose')

要素のポップオーバーを非表示にして破棄します。委任を使用するポップオーバー (オプションを使用selectorて作成される) は、子孫トリガー要素で個別に破棄できません。

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

.popover('enable')

要素のポップオーバーを表示できるようにします。ポップオーバーはデフォルトで有効になっています。

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

.popover('disable')

要素のポップオーバーを表示する機能を削除します。ポップオーバーは、再度有効にした場合にのみ表示できます。

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

.popover('toggleEnabled')

要素のポップオーバーを表示または非表示にする機能を切り替えます。

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

.popover('update')

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

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

イベント

イベントタイプ 説明
show.bs.popover showこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
shown.bs.popover このイベントは、ポップオーバーがユーザーに表示されるようになったときに発生します (CSS トランジションが完了するのを待ちます)。
hide.bs.popover hideこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
hidden.bs.popover このイベントは、ポップオーバーがユーザーから非表示になったときに発生します (CSS トランジションが完了するのを待ちます)。
挿入された.bs.popover このイベントはshow.bs.popover、ポップオーバー テンプレートが DOM に追加されたときに、イベントの後に発生します。
$('#myPopover').on('hidden.bs.popover', function () {
  // do something...
})