ツールチップ
アニメーション用の 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 内の要素のおかげで、ツールチップをトリガーできます。
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)
オーバーフローauto
とscroll
ツールチップの位置は、親コンテナーが私たちの を持っている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"
。
sanitize
て
sanitizeFn
ください
allowList
。
名前 | タイプ | デフォルト | 説明 |
---|---|---|---|
animation |
ブール値 | true |
ツールチップに CSS フェード トランジションを適用する |
container |
文字列 | 要素 | 間違い | false |
ツールチップを特定の要素に追加します。例: |
delay |
数 | 物体 | 0 |
ツールチップの表示と非表示の遅延 (ミリ秒) - 手動トリガー タイプには適用されません 数値が指定されている場合、表示/非表示の両方に遅延が適用されます オブジェクト構造は次のとおりです。 |
html |
ブール値 | false |
ツールチップで HTML を許可します。 true の場合、ツールヒントの HTML タグがツールヒント XSS 攻撃が心配な場合は、テキストを使用してください。 |
placement |
文字列 | 関数 | 'top' |
ツールチップの配置方法 - 自動 | トップ | ボトム | 左 | 左 | 右。 関数を使用して配置を決定する場合、ツールチップ DOM ノードを最初の引数として呼び出し、トリガー要素の DOM ノードを 2 番目の引数として呼び出します。 |
selector |
文字列 | 間違い | false |
セレクターが提供されている場合、ツールチップ オブジェクトは指定されたターゲットに委譲されます。実際には、これは、動的に追加された DOM 要素 (jQuery.on サポート) にツールチップを適用するためにも使用されます。これと有益な例を参照してください。 |
template |
ストリング | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
ツールチップの作成時に使用するベース HTML。 ツールチップ
最も外側のラッパー要素には、 |
title |
文字列 | 要素 | 関数 | '' |
関数が指定されている場合 |
trigger |
ストリング | 'hover focus' |
ツールチップのトリガー方法 - クリック | ホバー | フォーカス | マニュアル。複数のトリガーを渡すことができます。スペースで区切ります。
|
fallbackPlacements |
配列 | ['top', 'right', 'bottom', 'left'] |
プレースメントのリストを配列 (優先順) で指定して、フォールバック プレースメントを定義します。詳細については、Popper の動作に関するドキュメントを参照してください。 |
boundary |
文字列 | エレメント | 'clippingParents' |
ツールチップのオーバーフロー制約境界 (Popper の preventOverflow 修飾子にのみ適用されます)。デフォルトで'clippingParents' は、HTMLElement 参照を受け入れることができます (JavaScript 経由のみ)。詳細については、Popper のdetectOverflow docsを参照してください。 |
customClass |
文字列 | 関数 | '' |
ツールチップが表示されたら、クラスをツールチップに追加します。これらのクラスは、テンプレートで指定されたクラスに加えて追加されることに注意してください。複数のクラスを追加するには、クラスをスペースで区切ります: 追加のクラス名を含む単一の文字列を返す関数を渡すこともできます。 |
sanitize |
ブール値 | true |
サニタイズを有効または無効にします。有効にする'template' と、'title' オプションがサニタイズされます。JavaScript ドキュメントのサニタイザーのセクションを参照してください。 |
allowList |
物体 | デフォルト値 | 許可された属性とタグを含むオブジェクト |
sanitizeFn |
null | null | 関数 | null |
ここでは、独自のサニタイズ関数を指定できます。これは、専用のライブラリを使用してサニタイズを実行したい場合に役立ちます。 |
offset |
配列 | 文字列 | 関数 | [0, 0] |
ターゲットに対するツールチップのオフセット。次のようなカンマ区切りの値を使用して、データ属性に文字列を渡すことができます。 オフセットを決定するために関数が使用される場合、その関数は、最初の引数としてポッパーの配置、参照、およびポッパーの四角形を含むオブジェクトで呼び出されます。トリガー要素の DOM ノードは、2 番目の引数として渡されます。この関数は、2 つの数値を含む配列を返さなければなりません: . 詳細については、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 メソッドは非同期であり、遷移を開始します。トランジションが開始されるとすぐに呼び出し元に戻りますが、トランジションが終了する前に戻ります。さらに、遷移中のコンポーネントでのメソッド呼び出しは無視されます。
見せる
要素のツールチップを表示します。ツールチップが実際に表示される前 (つまり、イベントが発生する前)に呼び出し元に戻ります。shown.bs.tooltip
これは、ツールチップの「手動」トリガーと見なされます。タイトルの長さがゼロのツールチップは表示されません。
tooltip.show()
隠れる
要素のツールチップを非表示にします。ツールチップが実際に非表示になる前 (つまり、イベントが発生する前)に呼び出し元に戻ります。hidden.bs.tooltip
これは、ツールチップの「手動」トリガーと見なされます。
tooltip.hide()
トグル
要素のツールチップを切り替えます。ツールチップが実際に表示または非表示になる前 (つまり、orイベントが発生する前)に呼び出し元に戻ります。これは、ツールチップの「手動」トリガーと見なされます。shown.bs.tooltip
hidden.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()