in English

ツールチップ

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

このページでは

概要

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

ツールチップは、サードパーティのライブラリPopperを使用して配置します。の前にpopper.min.jsを含めるbootstrap.jsか、Popper を含むものを使用する必要がありbootstrap.bundle.min.jsます。
ツールチップはパフォーマンス上の理由からオプトインであるため、自分で初期化する必要があります。
タイトルの長さがゼロのツールチップは表示されません。
container: 'body'より複雑なコンポーネント (入力グループ、ボタングループなど) でのレンダリングの問題を回避するために指定します。
非表示の要素に対するツールチップのトリガーは機能しません。
.disabledまたは要素のツールチップはdisabled、ラッパー要素でトリガーする必要があります。
複数行にわたるハイパーリンクからトリガーされると、ツールチップが中央に配置されます。この動作を回避するには、でを使用white-space: nowrap;します。<a>
ツールチップは、対応する要素が DOM から削除される前に非表示にする必要があります。
Shadow DOM 内の要素のおかげで、ツールチップをトリガーできます。

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

デフォルトでは、このコンポーネントは組み込みのコンテンツサニタイザーを使用し、明示的に許可されていない HTML 要素を取り除きます。詳細については、JavaScript ドキュメントのサニタイザーのセクションを参照してください。

このコンポーネントのアニメーション効果は、 prefers-reduced-motionメディアクエリに依存します。アクセシビリティドキュメントの縮小モーションセクションを参照してください。

例

ツールチップを有効にする

前述のように、ツールチップを使用する前に初期化する必要があります。ページ上のすべてのツールチップを初期化する 1 つの方法はdata-bs-toggle、次のように属性で選択することです。

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

リンクのツールチップ

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

html

<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.
</p>

titleまたは data-bs-titleHTML で自由に使用してください。を使用すると、Popper は要素がレンダリングされるとき titleに自動的に置き換えます。data-bs-title

カスタムツールチップ

v5.2.0 で追加

CSS 変数を使用して、ツールチップの外観をカスタマイズできます。data-bs-custom-class="custom-tooltip"カスタムの外観をスコープするカスタムクラスを設定し、それを使用してローカルの CSS 変数をオーバーライドします。

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}

html

<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

方向

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

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

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

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

SVG の場合:

CSS

変数

v5.2.0 で追加

Bootstrap の進化する CSS 変数アプローチの一環として、ツールチップはローカル CSS 変数を使用し.tooltipてリアルタイムのカスタマイズを強化するようになりました。CSS 変数の値は Sass を介して設定されるため、Sass のカスタマイズも引き続きサポートされます。

  --#{$prefix}tooltip-zindex: #{$zindex-tooltip};
  --#{$prefix}tooltip-max-width: #{$tooltip-max-width};
  --#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
  --#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
  --#{$prefix}tooltip-margin: #{$tooltip-margin};
  @include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
  --#{$prefix}tooltip-color: #{$tooltip-color};
  --#{$prefix}tooltip-bg: #{$tooltip-bg};
  --#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
  --#{$prefix}tooltip-opacity: #{$tooltip-opacity};
  --#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
  --#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

サス変数

$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:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

使用法

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

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

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)

オーバーフロー`auto`と`scroll`

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

const tooltip = new bootstrap.Tooltip('#example', {
  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" data-bs-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"ます。

html

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

オプション

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

Bootstrap 5.2.0 の時点で、すべてのコンポーネントは、単純なコンポーネント構成を JSON 文字列として格納できる実験的な予約済みデータ属性をサポートしています。data-bs-config要素にdata-bs-config='{"delay":0, "title":123}'とdata-bs-title="456"属性がある場合、最終的なtitle値はに456なり、個別のデータ属性がで指定された値をオーバーライドしますdata-bs-config。さらに、既存のデータ属性は、のような JSON 値を格納できますdata-bs-delay='{"show":0,"hide":150}'。

セキュリティ上の理由から、、、およびオプションは、データ属性を使用して提供できないことに注意し sanitizeて sanitizeFnください allowList。

名前	タイプ	デフォルト	説明
`allowList`	物体	デフォルト値	許可された属性とタグを含むオブジェクト。
`animation`	ブール値	`true`	ツールチップに CSS フェードトランジションを適用します。
`boundary`	文字列、要素	`'clippingParents'`	ツールチップのオーバーフロー制約境界 (Popper の preventOverflow 修飾子にのみ適用されます)。デフォルトで`'clippingParents'`は、HTMLElement 参照を受け入れることができます (JavaScript 経由のみ)。詳細については、Popper のdetectOverflow docsを参照してください。
`container`	文字列、要素、false	`false`	ツールチップを特定の要素に追加します。例: `container: 'body'`. このオプションは、トリガー要素の近くのドキュメントの流れにツールヒントを配置できるという点で特に便利です。これにより、ウィンドウのサイズ変更中にトリガー要素からツールヒントが浮かび上がるのを防ぐことができます。
`customClass`	文字列、関数	`''`	ツールチップが表示されたら、クラスをツールチップに追加します。これらのクラスは、テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、クラスをスペースで区切ります: `'class-1 class-2'`. 追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。
`delay`	数、オブジェクト	`0`	ツールチップの表示と非表示の遅延 (ミリ秒) — 手動トリガータイプには適用されません。数値を指定すると、hide/show の両方に遅延が適用されます。オブジェクト構造: `delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	配列	`['top', 'right', 'bottom', 'left']`	プレースメントのリストを配列 (優先順) で指定して、フォールバックプレースメントを定義します。詳細については、Popper の動作に関するドキュメントを参照してください。
`html`	ブール値	`false`	ツールチップで HTML を許可します。true の場合、ツールヒントの HTML タグがツールヒント`title`に表示されます。false の場合、`innerText`プロパティを使用してコンテンツを DOM に挿入します。XSS 攻撃が心配な場合は、テキストを使用してください。
`offset`	配列、文字列、関数	`[0, 0]`	ターゲットに対するツールチップのオフセット。次のようなカンマ区切りの値を使用して、データ属性に文字列を渡すことができます`data-bs-offset="10,20"`。オフセットを決定するために関数が使用される場合、その関数は、最初の引数としてポッパーの配置、参照、およびポッパーの四角形を含むオブジェクトで呼び出されます。トリガー要素の DOM ノードは、2 番目の引数として渡されます。この関数は、 skiddingとdistanceの 2 つの数値を含む配列を返さなければなりません。詳細については、Popper のオフセットドキュメントを参照してください。
`placement`	文字列、関数	`'top'`	ツールチップの配置方法: 自動、上、下、左、右。を指定する`auto`と、ツールチップの向きが動的に変更されます。関数を使用して配置を決定する場合、ツールチップ DOM ノードを最初の引数として呼び出し、トリガー要素の DOM ノードを 2 番目の引数として呼び出します。`this`コンテキストはツールチップインスタンスに設定されます。
`popperConfig`	null、オブジェクト、関数	`null`	Bootstrap のデフォルトの Popper 設定を変更するには、Popper の設定を参照してください。関数を使用して Popper 構成を作成する場合、Bootstrap のデフォルトの Popper 構成を含むオブジェクトで呼び出されます。デフォルトを使用して独自の構成にマージするのに役立ちます。この関数は、Popper の構成オブジェクトを返さなければなりません。
`sanitize`	ブール値	`true`	サニタイズを有効または無効にします。有効`'template'`にする`'content'`と、`'title'`オプションがサニタイズされます。
`sanitizeFn`	null、関数	`null`	ここでは、独自のサニタイズ関数を指定できます。これは、専用のライブラリを使用してサニタイズを実行したい場合に役立ちます。
`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'`を介してプログラムでツールチップがトリガーされることを示します。この値は、他のトリガーと組み合わせることはできません。単独では、キーボードからトリガーできないツールチップが生成され、キーボードユーザーに同じ情報を伝える別の方法が存在する場合にのみ使用する必要があります。`.tooltip('show').tooltip('hide').tooltip('toggle')'hover'`

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

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

関数の使用`popperConfig`

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

メソッド

非同期メソッドと遷移

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

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

方法	説明
`disable`	要素のツールチップを表示する機能を削除します。ツールチップは、再度有効にした場合にのみ表示できます。
`dispose`	要素のツールチップを非表示にして破棄します (DOM 要素に保存されているデータを削除します)。委任を使用するツールチップ (オプションを使用し`selector`て作成される) は、子孫トリガー要素で個別に破棄することはできません。
`enable`	要素のツールチップを表示できるようにします。ツールチップはデフォルトで有効になっています。
`getInstance`	DOM 要素に関連付けられたツールチップインスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
`getOrCreateInstance`	DOM 要素に関連付けられたツールチップインスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
`hide`	要素のツールチップを非表示にします。ツールチップが実際に非表示になる前 (つまり、イベントが発生する前)に呼び出し元に戻ります。`hidden.bs.tooltip`これは、ツールチップの「手動」トリガーと見なされます。
`setContent`	初期化後にツールチップのコンテンツを変更する方法を提供します。
`show`	要素のツールチップを表示します。ツールチップが実際に表示される前 (つまり、イベントが発生する前)に呼び出し元に戻ります。`shown.bs.tooltip`これは、ツールチップの「手動」トリガーと見なされます。タイトルの長さがゼロのツールチップは表示されません。
`toggle`	要素のツールチップを切り替えます。ツールチップが実際に表示または非表示になる前 (つまり、orイベントが発生する前)に呼び出し元に戻ります。これは、ツールチップの「手動」トリガーと見なされます。`shown.bs.tooltiphidden.bs.tooltip`
`toggleEnabled`	要素のツールチップを表示または非表示にする機能を切り替えます。
`update`	要素のツールチップの位置を更新します。

const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

イベント

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

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()

ツールチップ

概要

例

ツールチップを有効にする

リンクのツールチップ

カスタム ツールチップ

方向

CSS

変数

サス変数

使用法

オーバーフローautoとscroll

マークアップ

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

無効な要素

オプション

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

関数の使用popperConfig

メソッド

非同期メソッドと遷移

イベント

カスタムツールチップ

オーバーフロー`auto`と`scroll`

関数の使用`popperConfig`