メインコンテンツにスキップ ドキュメント ナビゲーションにスキップ
in English

ツールチップ

アニメーション用の CSS3 とローカル タイトル ストレージ用の data-bs-attributes を使用して、CSS と JavaScript でカスタム Bootstrap ツールチップを追加するためのドキュメントと例。

概要

ツールチップ プラグインを使用する際の注意事項:

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

それをすべて手に入れましたか?すばらしい、いくつかの例でそれらがどのように機能するか見てみましょう。

例: どこでもツールチップを有効にする

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

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

以下のリンクにカーソルを合わせると、ツールヒントが表示されます。

ツールチップを含むいくつかのインライン リンクを示すプレースホルダー テキスト。これは単なるフィラーであり、キラーではありません。実際のテキストの存在を模倣するためだけにここに配置されたコンテンツ。これらはすべて、実際の状況で使用した場合にツールチップがどのように表示されるかを理解するためのものです。自分のサイトやプロジェクトでこれらのツールチップを使用すると、リンクに関するこれらのツールチップが実際にどのように機能するかがわかったと思います.

下のボタンにカーソルを合わせると、上、右、下、左の 4 つのツールチップの方向が表示されます。RTL で Bootstrap を使用すると、方向がミラーリングされます。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

カスタム HTML を追加すると、次のようになります。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

SVG の場合:

サス

変数

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

使用法

ツールチップ プラグインは、オンデマンドでコンテンツとマークアップを生成し、デフォルトではトリガー要素の後にツールチップを配置します。

JavaScript を介してツールチップをトリガーします。

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
オーバーフローautoscroll

ツールチップの位置は、親コンテナーが私たちの を持っているoverflow: autoか、overflow: scroll好きなときに自動的に変更しようとします.table-responsiveが、元の配置の位置を維持します。これを解決するには、boundaryオプション(オプションを使用するフリップ修飾子用popperConfig) を任意の HTMLElement に設定して、次'clippingParents'のようなデフォルト値をオーバーライドしdocument.bodyます。

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // or document.querySelector('#boundary')
})

マークアップ

ツールチップに必要なマークアップはdata属性のみでtitleあり、ツールチップを表示したい HTML 要素上にあります。生成されたツールチップのマークアップはかなり単純ですが、位置が必要です (デフォルトではtop、プラグインによって設定されます)。

ツールチップをキーボードおよび支援技術ユーザー向けに機能させる

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

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

無効な要素

この属性を持つ要素disabledはインタラクティブではありません。つまり、ユーザーはツールヒント (またはポップオーバー) をトリガーするためにそれらにフォーカスしたり、ホバーしたり、クリックしたりすることはできません。回避策として、ラッパーからツールチップをトリガーする<div><span>、理想的には を使用してキーボード フォーカス可能にしtabindex="0"ます。

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

オプション

オプションは、データ属性または JavaScript を介して渡すことができます。data-bs-データ属性の場合、オプション名をのようにに追加しますdata-bs-animation=""。データ属性を介してオプションを渡すときは、オプション名のケース タイプを camelCase から kebab-case に変更してください。たとえば、 を使用する代わりに、 をdata-bs-customClass="beautifier"使用しますdata-bs-custom-class="beautifier"

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

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

delay 数 | 物体 0

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

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

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

html ブール値 false

ツールチップで HTML を許可します。

true の場合、ツールヒントの HTML タグがツールヒントtitleに表示されます。false の場合、innerTextプロパティを使用してコンテンツを DOM に挿入します。

XSS 攻撃が心配な場合は、テキストを使用してください。

placement 文字列 | 関数 'top'

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

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

selector 文字列 | 間違い false セレクターが提供されている場合、ツールチップ オブジェクトは指定されたターゲットに委譲されます。実際には、これは、動的に追加された DOM 要素 (jQuery.onサポート) にツールチップを適用するためにも使用されます。これ有益な例を参照してください。
template ストリング '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

ツールチップの作成時に使用するベース HTML。

ツールチップtitleは に挿入されます.tooltip-inner

.tooltip-arrowツールチップの矢印になります。

最も外側のラッパー要素には、.tooltipクラスとrole="tooltip".

title 文字列 | 要素 | 関数 ''

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

関数が指定されている場合thisは、ツールチップが添付されている要素に設定された参照で呼び出されます。

trigger ストリング 'hover focus'

ツールチップのトリガー方法 - クリック | ホバー | フォーカス | マニュアル。複数のトリガーを渡すことができます。スペースで区切ります。

'manual'.show().hide()および.toggle()メソッドを介してプログラムでツールチップがトリガーされることを示します。この値は、他のトリガーと組み合わせることはできません。

'hover'単独では、キーボードからトリガーできないツールチップが生成され、キーボード ユーザーに同じ情報を伝える別の方法が存在する場合にのみ使用する必要があります。

fallbackPlacements 配列 ['top', 'right', 'bottom', 'left'] プレースメントのリストを配列 (優先順) で指定して、フォールバック プレースメントを定義します。詳細については、Popper の動作に関するドキュメントを参照してください。
boundary 文字列 | エレメント 'clippingParents' ツールチップのオーバーフロー制約境界 (Popper の preventOverflow 修飾子にのみ適用されます)。デフォルトで'clippingParents'は、HTMLElement 参照を受け入れることができます (JavaScript 経由のみ)。詳細については、Popper のdetectOverflow docsを参照してください。
customClass 文字列 | 関数 ''

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

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

sanitize ブール値 true サニタイズを有効または無効にします。有効にする'template'と、'title'オプションがサニタイズされます。JavaScript ドキュメントのサニタイザーのセクションを参照してください。
allowList 物体 デフォルト値 許可された属性とタグを含むオブジェクト
sanitizeFn null | null | 関数 null ここでは、独自のサニタイズ関数を指定できます。これは、専用のライブラリを使用してサニタイズを実行したい場合に役立ちます。
offset 配列 | 文字列 | 関数 [0, 0]

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

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

詳細については、Popper のオフセット ドキュメントを参照してください。

popperConfig null | null | オブジェクト | 関数 null

Bootstrap のデフォルトの Popper 設定を変更するには、Popper の設定を参照してください。

関数を使用して Popper 構成を作成する場合、Bootstrap のデフォルトの Popper 構成を含むオブジェクトで呼び出されます。デフォルトを使用して独自の構成にマージするのに役立ちます。この関数は、Popper の構成オブジェクトを返さなければなりません。

個々のツールチップのデータ属性

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

関数の使用popperConfig

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

メソッド

非同期メソッドと遷移

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

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

見せる

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

tooltip.show()

隠れる

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

tooltip.hide()

トグル

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

tooltip.toggle()

廃棄

要素のツールチップを非表示にして破棄します (DOM 要素に保存されているデータを削除します)。委任を使用するツールチップ (オプションを使用selectorて作成される) は、子孫トリガー要素で個別に破棄することはできません。

tooltip.dispose()

有効

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

tooltip.enable()

無効にする

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

tooltip.disable()

トグル有効

要素のツールチップを表示または非表示にする機能を切り替えます。

tooltip.toggleEnabled()

アップデート

要素のツールチップの位置を更新します。

tooltip.update()

getInstance

DOM 要素に関連付けられたツールチップ インスタンスを取得できる静的メソッド

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

getOrCreateInstance

DOM 要素に関連付けられたツールチップ インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

イベント

イベントタイプ 説明
show.bs.tooltip showこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
shown.bs.tooltip このイベントは、ツールチップがユーザーに表示されるようになったときに発生します (CSS トランジションが完了するのを待ちます)。
hide.bs.tooltip hideこのイベントは、インスタンス メソッドが呼び出されるとすぐに発生します。
hidden.bs.tooltip このイベントは、ツールチップがユーザーから非表示になったときに発生します (CSS トランジションが完了するのを待ちます)。
inserted.bs.tooltip このイベントはshow.bs.tooltip、ツールヒント テンプレートが DOM に追加されたときに、イベントの後に発生します。
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // do something...
})

tooltip.hide()