メインコンテンツへスキップ

Bootstrap4.xの使い方をBootstrap3.xからの変更箇所を交えて解説しています。

ツールチップ(Tooltips) v4.0.0設定変更

CSS3を使ってCSS3とアニメーション用のカスタムBootstrapツールチップを追加し、ローカルタイトルストレージ用のデータ属性を追加するための解説と例。

概要(Overview)

ツールチップ・プラグインを使用するときに知っておくべきこと:

  • ツールチップは、サードパーティのライブラリであるPopper.jsを利用して位置情報を取得しているため、ツールチップが動作するためには bootstrap.js の前にpopper.min.jsを組み込むか、代わりにPopper.jsを内部に含む bootstrap.bundle.jsbootstrap.bundle.min.js を使用する必要がある。
  • ソースファイルからJavaScriptを構築する場合は、util.js が必要
  • ツールチップは、パフォーマンス上の理由で任意で取得されるため、自分で初期化する必要がある(そのため実行コードが必要)。
  • title の長さがゼロのツールチップは表示されない。
  • container: 'body' を指定すると、より複雑なコンポーネント(インプットグループやボタングループなど)のレンダリングの問題が回避可能。
  • 非表示要素のツールチップは機能しない。
  • .disabled または disabled 要素のツールチップは、それを囲む要素で起動する必要がある。サンプル
  • 複数行にまたがるハイパーリンクから起動されると、ツールチップは中央に配置されるので、この動作を回避するには、<a>.text-nowrap を使用すること。
  • ツールチップは、対応する要素がDOMから削除される前に非表示にする必要がある。
  • ツールチップは、シャドウDOM内の要素のために起動可能。

いくつかの例を使ってどのように動作するか以下に表示。

 

どこでもツールチップを有効にする例(Example: Enable tooltips everywhere)

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

実行コード
JavaScriptの場合$(function () {
	$('[data-toggle="tooltip"]').tooltip()
})
HTMLの場合<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script>
	$('[data-toggle="tooltip"]').tooltip()
</script>

【設定】

  • bootstrap.min.js より前に Popper.js の設定が必要
    Popper.js をCDNで設置する場合は、クイックスタートを参照

【Bootstrap3.xとの変更箇所】

 

ツールチップの設定(Examples)v4.0.0一部変更

ツールチップを表示するには、以下のリンクにカーソルを合わせること:

見本

リンクの上にカーソルを合わせるかタッチして下さい。

設定例
HTML<p><a href="#" data-toggle="tooltip" title="これがツールチップです">リンク</a>の上にカーソルを合わせるかタッチして下さい。</p>

【設定】

  • a[data-toggle="tooltip"][title="ツールチップ文"]

下のボタンにカーソルを合わせると、上、右、下、左の4つのツールチップの指示が表示。

1. ツールチップの方向設定

見本
設定例
上に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-toggle="tooltip" data-placement="top" title="上に出るツールチップ">ツールチップ(上)</button>
右に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-toggle="tooltip" data-placement="right" title="右に出るツールチップ">ツールチップ(右)</button>
下に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-toggle="tooltip" data-placement="bottom" title="下に出るツールチップ">ツールチップ(下)</button>
左に出るツールチップ<button type="button" class="btn btn-secondary mb-2 mb-md-0" data-toggle="tooltip" data-placement="left" title="左に出るツールチップ">ツールチップ(左)</button>

【設定】

  • data-toggle="tooltip" と同じ要素に data-placement="xxx"xxxleft(左)、top(上)、bottom(下)、right(右)の中から選択)を入れる

2. HTML付きツールチップ

カスタムHTMLを追加:

見本
設定例
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
	HTML付きツールチップ
</button>

【設定】

  • title にHTMLを入れることも可能

 

使用方法(Usage)

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

JavaScript経由でツールチップを起動:

JavaScript$('#example').tooltip(options)

マークアップ(Markup)

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

<!--HTMLコードの記載 -->
<a href="#" data-toggle="tooltip" title="いくつかのツールチップテキスト!">この上にマウスポインターを移動</a>

<!-- プラグインによる一般的なマークアップ -->
<div class="tooltip bs-tooltip-top bs-tooltip-top-docs" role="tooltip">
	<div class="arrow"></div>
	<div class="tooltip-inner">
		いくつかのツールチップテキスト!
	</div>
</div>

無効な要素(Disabled elements)

disabled 属性を持つ要素はインタラクティブではないため、ユーザーがフォーカス、ホバーまたはクリックしてツールチップ(またはポップオーバー)を起動することは不可。回避策として tabindex="0" を使用して理想的にキーボードフォーカスを可能にしたラッパーの <div> または <span> からツールチップを起動し、無効化された要素の pointer-events を上書きする必要がある。

見本
設定例
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="無効要素のツールチップ">
	<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>無効ボタン</button>
</span>

オプション(Options)サンプル v4.3.1一部追加更

オプションは、データの属性やJavaScriptを使用して渡すことが可能。データ属性の場合は、data-animation="" のように、data- にオプション名を追加。

名前 タイプ デフォルト 説明
animation boolean true ツールチップにCSSのフェード遷移を適用
true:有効/false:無効
container
v4.0.0一部変更
string | element | false false ツールチップを特定の要素に追加。例:container: 'body'
このオプションでは、ウィンドウサイズ変更時にツールチップがトリガー要素から浮かないようにし、トリガー要素の近くにツールチップの配置を可能にするという点で特に便利。
delay number | object 0 ツールチップの表示と非表示の遅延時間(1000分の1秒単位) - triggerでmanualを指定した場合は適用されない。

数字が指定された場合、hide/showの両方に遅延が適用。

オブジェクト構造は次のとおり:delay: { "show": 500, "hide": 100 }
html boolean false ツールチップにHTMLを許可。

trueの場合、ツールチップの title のHTMLタグがツールチップに表示される。falseの場合、jQueryの text メソッドがコンテンツをDOMに挿入するために使用される。
XSS攻撃が心配な場合はテキストを使用すること。
true:有効/false:無効
placement string | function 'top' ツールチップの配置方法 - auto | top | bottom | left | right
auto が指定されると、動的にポップオーバーの向きが変更。

function配置を決定するために使用されるとき、ツールチップDOMノードを第1引数として、起動要素DOMノードを第2引数として呼び出す。this コンテキストは、ツールチップヒントインスタンスに設定される。
selector
v4.0.0一部変更
string | false false selectorが提供されている場合、ツールチップオブジェクトが指定されたターゲットに付与される。実際には、動的に追加されたDOM要素(jQuery.on サポート)にツールチップを適用するために使用。ココ有益な実例を参照。
template
v4.0.0一部変更
string '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>' ツールチップを作成するときに使用するベースのHTML。

ツールチップの title.tooltip-inner に挿入される。

.arrow は、ツールチップの矢印になる。

一番外側の包括要素には、.tooltip クラスと role="tooltip" を入れる必要がある。
title string | element | function '' title 属性が存在しない場合のデフォルトのタイトル値。

functionを設定した場合、this 参照セットをツールチップが接続されている要素にセットして呼び出される。
trigger string 'hover focus' ツールチップの起動方法 - click | hover | focus | manual
複数の起動方法を指定:スペースで区切る。

'manual' は、.tooltip('show'), .tooltip('hide'), .tooltip('toggle') メソッドを使用して、ツールチップがプログラムによって起動されるようにする。この値を他の起動方法と組み合わせることは不可。

'hover' を単独で使用すると、キーボードでは操作できないツールチップが表示されるので、キーボードユーザーに対して同じ情報を伝達するための代替方法が存在する場合にのみ使用する必要がある。
offset
v4.0.0追加
v4.3.0一部変更
number | string | function 0

ターゲットに対するツールチップのオフセット値。

オフセットを決定するために関数を使用する場合は、最初の引数としてオフセットデータを含むオブジェクトで呼び出される。関数は同じ構造を持つオブジェクトを返さなければならない。切替要素のDOMノードは、2番目の引数として渡される。

詳細については、Popper.jsのoffsetドキュメントに記載。

fallbackPlacement
v4.0.0追加
string | array 'flip' Popperがフォールバックで使用する位置を指定できるようにする。詳細については、Popper.jsのbehaviorドキュメントに記載。
boundary
v4.0.0追加
string | element 'scrollParent' ツールチップのオーバーフローを制約する境界。'viewport', 'window', 'scrollParent' またはHTMLElementリファレンス(JavaScriptのみ)の値を受け入れる。詳細については、Popper.jsのpreventOverflowドキュメントに記載。
sanitize
v4.3.1追加
boolean true サニタイズを有効/無効にする。有効にすると、'template', 'content', 'title' オプションはサニタイズされる。
true:有効/false:無効
whiteList
v4.3.1追加
object デフォルト値 許可された属性とタグを含むオブジェクト
sanitizeFn
v4.3.1追加
null | function null 自分用のサニタイズ機能を提供することが可能。サニタイズを実行するために専用のライブラリを使用したい場合に役立つ。

【変更履歴】

  • 【v4.0.0-beta.2】container のタイプに element が追加

    selector のタイプに false が追加

  • 【v4.0.0-beta.3】boundary が追加
  • 【v4.3.0】offset のタイプに function(関数)が追加
  • 【v4.3.1】sanitize, sanitizeFn, whiteList が追加

【Bootstrap3.xとの変更箇所】

  • offset, fallbackPlacement が追加
  • viewport は廃止
  • template のうち .tooltip-arrow.arrow

メソッド(Methods)サンプル

$().tooltip(options)

要素コレクションにツールチップのハンドラーを付ける。

.tooltip('show')

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

JavaScript$('#element').tooltip('show')

.tooltip('hide')

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

JavaScript$('#element').tooltip('hide')

.tooltip('toggle')

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

JavaScript$('#element').tooltip('toggle')

.tooltip('dispose') v4.0.0名称変更

要素のツールチップを非表示にしたり破棄したりする。(selector オプションを使用して作成される)デリゲートを使用するツールチップは、子孫トリガー要素で個別に破棄できない。

JavaScript$('#element').tooltip('dispose')

.tooltip('enable') v4.0.0追加

要素のツールチップに表示する機能を与える。デフォルトで有効

JavaScript$('#element').tooltip('enable')

.tooltip('disable') v4.0.0追加

要素のツールチップが表示されるようにする機能を削除。ツールチップは、再度有効になっている場合にのみ表示可能。

JavaScript$('#element').tooltip('disable')

.tooltip('toggleEnabled') v4.0.0追加

要素のツールチップが表示または非表示になるように切り替える。

JavaScript$('#element').tooltip('toggleEnabled')

.tooltip('update') v4.0.0追加

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

JavaScript$('#element').tooltip('update')

【Bootstrap3.xとの変更箇所】

  • .tooltip('destroy').tooltip('dispose') に名称変更
  • .tooltip('enable'), .tooltip('disable'), .tooltip('toggleEnabled'), .tooltip('update') が追加

イベント(Events)

イベントタイプ 説明
show.bs.tooltip このイベントは、show のインスタンス・メソッドが呼び出されると直ちに発動。
shown.bs.tooltip このイベントは、ユーザーにツールチップが表示されたときに発動(完全にCSS遷移が完了するまで待機)。
hide.bs.tooltip このイベントは、hide のインスタンス・メソッドが呼び出されると直ちに発動。
hidden.bs.tooltip このイベントは、ツールチップがユーザーから非表示になったときに発動(完全にCSS遷移が完了するまで待機)。
inserted.bs.tooltip このイベントは、ツールチップテンプレートがDOMに追加されたときに show.bs.tooltip イベントの後に発動。
使用例
JavaScript$('#myTooltip').on('hidden.bs.tooltip', function () {
	// 何かをする...
})