<div class="text-center my-3">
<b-button v-b-tooltip.hover title="Tooltip directive content">
Hover Me
</b-button>
<b-button id="tooltip-target-1">
Hover Me
</b-button>
<b-tooltip target="tooltip-target-1" triggers="hover">
I am tooltip <b>component</b> content!
</b-tooltip>
</div>
概要
ツールチップコンポーネントを使用する際に知っておくべきこと
- ツールチップは、位置決めにサードパーティライブラリのPopper.jsを利用しています。
- ツールチップを正しく機能させ、バリアントを使用するには、BootstrapVueのカスタムSCSS/CSSが必要です。
- 非表示要素でツールチップをトリガーしても機能しません。
- より複雑なコンポーネント(インプットグループ、ボタングループなど)でのレンダリングの問題を回避するために、
container
をnull
(デフォルト、<body>
に追加)として指定します。 containerを使用して、レンダリングされたツールチップを追加する別の要素をオプションで指定できます。 disabled
要素のツールチップは、ラッパー要素でトリガーする必要があります。 - 複数行にまたがるハイパーリンクからトリガーされた場合、ツールチップは中央揃えになります。この動作を回避するには、
<a>
、<b-link>
、および<router-link>
でwhite-space: nowrap;を使用してください。
ターゲット
ターゲットは、ツールチップをトリガーするトリガー要素(またはコンポーネント)です。ターゲットは、target
プロパティを介して指定され、次のいずれかになります。
- トリガー要素のID(またはコンポーネントのルート要素のID)を識別する文字列
HTMLElement
またはSVGElement
への参照(ref)(例:this.$refs.refName
) - ルート要素として
HTMLElement
またはSVGElement
のいずれかを持つコンポーネントへの参照(ref)(例:this.$refs.refName
) HTMLElement
またはSVGElement
への参照を返す関数(コールバック)
参照の詳細については、公式のVueドキュメントを参照してください。
注意
ターゲット要素は、<b-tooltip>
がマウントされる前にドキュメントに存在する必要があります。マウント中にターゲット要素が見つからない場合、ツールチップは開かれません。必ず、<b-tooltip>
コンポーネントをターゲット要素よりもDOMの下位に配置してください。このルールは、コールバック関数がターゲット要素として使用されている場合にも適用されます。コールバック関数はマウント時に一度しか呼び出されないためです。
HTMLElement
は、<div>
、<button>
などの標準HTML要素を指し、SVGElement
は、<svg>
またはSVGのサポートされている子要素を指します。
位置決め
位置決めには12のオプションがあります:top
、topleft
、topright
、right
、righttop
、rightbottom
、bottom
、bottomleft
、bottomright
、left
、lefttop
、およびleftbottom
で揃えることができます。デフォルトの位置はtop
です。位置決めはトリガー要素を基準にします。
位置決めのライブ例については、ツールチップディレクティブのドキュメントを参照してください。
トリガー
ツールチップは、click
、hover
、およびfocus
の任意の組み合わせでトリガー(開閉)できます。デフォルトのトリガーはhover focus
です。または、manual
のトリガーを指定できます。この場合、ポップオーバーはプログラムでのみ開閉できます。
ツールチップに複数のトリガーがある場合、ツールチップを閉じるには、すべてのトリガーをクリアする必要があります。つまり、ツールチップにfocus click
というトリガーがあり、focus
によって開かれた場合、ユーザーはトリガー要素を再度クリックし、かつフォーカスを移動してツールチップを閉じる必要があります。
focus
トリガーのみを使用する場合の適切なクロスブラウザおよびクロスプラットフォームの動作については、<button>
タグではなく、<a>
タグをレンダリングする要素を使用し、tabindex="0"
属性を含める必要があります。
以下は、ボタンのように見える<a>
を生成します
<b-button
href="#"
tabindex="0"
v-b-tooltip.focus
title="Tooltip title"
>
Link button with tooltip directive
</b-button>
<b-button id="link-button" href="#" tabindex="0">
Link button with tooltip component
</b-button>
<b-tooltip target="link-button" title="Tooltip title" triggers="focus">
Tooltip title
</b-tooltip>
ツールチップは、キーボードでフォーカス可能でインタラクティブなHTML要素(リンク、ボタン、フォームコントロールなど)にのみ追加する必要があります。<span>
などの任意のHTML要素は、tabindex="0"
属性を追加することでフォーカス可能にできますが、これにより、キーボードユーザーの非インタラクティブ要素に、煩わしく、紛らわしいタブストップが追加される可能性があります。さらに、ほとんどの支援技術では、この状況でツールチップがアナウンスされません。
また、ツールチップのトリガーとしてhover
のみに依存しないでください。これにより、キーボードのみのユーザーはツールチップをトリガーできなくなります。
無効な要素
disabled
属性を持つ要素はインタラクティブではありません。つまり、ユーザーはフォーカス、ホバー、またはクリックしてツールチップ(またはポップオーバー)をトリガーできません。回避策として、ラッパー<div>
または<span>
からツールチップをトリガーし、理想的にはtabindex="0"
を使用してキーボードでフォーカス可能にし、無効な要素のpointer-events
をオーバーライドします。
<div>
<span id="disabled-wrapper" class="d-inline-block" tabindex="0">
<b-button variant="primary" style="pointer-events: none;" disabled>Disabled button</b-button>
</span>
<b-tooltip target="disabled-wrapper">Disabled tooltip</b-tooltip>
</div>
<b-container fluid>
<b-row>
<b-col md="4" class="py-4">
<b-button id="button-1" variant="outline-success">Live chat</b-button>
</b-col>
<b-col md="4" class="py-4">
<b-button id="button-2" variant="outline-success">Html chat</b-button>
</b-col>
<b-col md="4" class="py-4">
<b-button ref="button-3" variant="outline-success">Alternative chat</b-button>
</b-col>
</b-row>
<b-tooltip target="button-1" title="Online!"></b-tooltip>
<b-tooltip target="button-2" placement="bottom">
Hello <strong>World!</strong>
</b-tooltip>
<b-tooltip :target="() => $refs['button-3']" title="Alternative!"></b-tooltip>
</b-container>
コンポーネントオプション
プロパティ | デフォルト | 説明 | サポートされている値 |
target | null | ツールチップをトリガーする要素の文字列ID、要素またはコンポーネントへの参照、またはそれらのいずれかを返す関数。必須 | 有効なドキュメント内の一意の要素ID、要素参照、またはコンポーネント参照、またはそのようなID/参照を返す関数 |
title | null | ツールチップのコンテンツ(テキストのみ、HTMLなし)。HTMLが必要な場合は、デフォルトのスロットに配置します | プレーンテキスト |
placement | 'top' | トリガー要素を基準としたツールチップの位置 | top 、bottom 、left 、right 、auto 、topleft 、topright 、bottomleft 、bottomright 、lefttop 、leftbottom 、righttop 、rightbottom |
fallback-placement | 'flip' | トリガー要素を基準としたツールチップの自動反転配置の動作 | flip 、clockwise 、counterclockwise 、または左から右に評価される有効な配置の配列 |
triggers | 'hover focus' | ツールチップの開閉をトリガーするイベントのスペース区切りのリスト | hover 、focus 、click 。 blur は、通常はclick と組み合わせて使用される、次のクリックでツールチップを閉じるための特別な使用例であることに注意してください。 |
no-fade | false | true に設定するとフェードアニメーションが無効になります | true またはfalse |
delay | 50 | 指定したミリ秒数だけツールチップの表示と非表示を遅らせます。{ show: 100, hide: 400 } の形式のオブジェクトとして指定することもでき、異なる表示/非表示の遅延を許可します。 | 0 以上、整数のみ。 |
offset | 0 | ツールチップの中心を指定したピクセル数だけシフトします | 任意の負または正の整数 |
container | null | ツールチップをレンダリングする際に、追加先の要素の文字列ID。 null の場合、または要素が見つからない場合は、ツールチップは<body> に追加されます(デフォルト)。 | ドキュメント内の有効な一意な要素ID。 |
境界 | 'scrollParent' | ツールチップが表示範囲を制限するコンテナ。ほとんどの場合、デフォルトで十分ですが、ターゲット要素がオーバーフロースクロールのある小さなコンテナ内にある場合は、これを変更する必要がある場合があります。 | 'scrollParent' (デフォルト)、'viewport' 、'window' 、またはHTML要素への参照。 |
境界パディング | 5 | 境界とツールチップの間の最小距離を定義するために使用されるピクセル数。これにより、ツールチップが常にコンテナの端との間に少しのパディングを持つようになります。 | 任意の正の数 |
非インタラクティブ | false | ツールチップをユーザーが操作できないようにするかどうか。 | true またはfalse |
バリアント | null | ツールチップのコンテキストカラーバリアント。 | 任意のコンテキストテーマカラーバリアント名。 |
カスタムクラス | null | ツールチップの外側のラッパー要素に適用するカスタムクラス名。 | 文字列 |
ID | null | ツールチップのルート要素で使用するID。何も指定しない場合は、自動的に生成されます。IDを指定する場合は、レンダリングされたページで一意であることが保証されている必要があります。 | 有効な一意の要素ID文字列 |
BootstrapVueのツールチップは、アクセシビリティ上の理由からデフォルトでユーザーが操作可能です。Bootstrapのデフォルトの動作を復元するには、noninteractive
プロパティを適用します。
<div class="text-center">
<div>
<b-button id="tooltip-button-interactive">My tooltip is interactive</b-button>
<b-tooltip target="tooltip-button-interactive">I will stay open when hovered</b-tooltip>
</div>
<div class="mt-3">
<b-button id="tooltip-button-not-interactive">Mine is not...</b-button>
<b-tooltip target="tooltip-button-not-interactive" noninteractive>Catch me if you can!</b-tooltip>
</div>
</div>
バリアントとカスタムクラス
BootstrapVueのツールチップは、variant
プロパティを介して、カスタムCSSを介したコンテキストカラーバリアントをサポートします。
<div class="text-center">
<b-button id="tooltip-button-variant">Button</b-button>
<b-tooltip target="tooltip-button-variant" variant="danger">Danger variant tooltip</b-tooltip>
</div>
Bootstrapのデフォルトテーマのバリアントは、danger
、warning
、success
、primary
、secondary
、info
、light
、およびdark
です。BootstrapのSCSS変数を使用して、追加のバリアントを変更または追加できます。
custom-class
プロパティを使用すると、ツールチップの外側のラッパー<div>
にカスタムクラスを適用できます。
<div class="text-center">
<b-button id="my-button">Button</b-button>
<b-tooltip target="my-button" custom-class="my-tooltip-class">Tooltip Title</b-tooltip>
</div>
variant
とcustom-class
はリアクティブであり、ツールチップが開いている間に変更できます。
ディレクティブバージョンにバリアントとカスタムクラスを適用する方法については、ツールチップディレクティブのドキュメントを参照してください。
同期可能なブール値show
プロパティを使用して、ツールチップの表示/非表示を手動で制御できます。true
に設定するとツールチップが表示され、false
に設定するとツールチップが非表示になります。
<template>
<div class="text-center">
<div>
<b-button id="tooltip-button-1" variant="primary">I have a tooltip</b-button>
</div>
<div class="mt-3">
<b-button @click="show = !show">Toggle Tooltip</b-button>
</div>
<b-tooltip :show.sync="show" target="tooltip-button-1" placement="top">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</template>
<script>
export default {
data: {
show: true
}
}
</script>
最初のレンダリング時にツールチップを表示するには、単純に<b-tooltip>
にshow
プロパティを追加します。
<div class="text-center">
<b-button id="tooltip-button-2" variant="primary">Button</b-button>
<b-tooltip show target="tooltip-button-2">I start open</b-tooltip>
</div>
プログラムによる制御は、参照によってツールチップに'open'
イベントと'close'
イベントを送信することによっても影響を受ける可能性があります。
<template>
<div class="d-flex flex-column text-md-center">
<div class="p-2">
<b-button id="tooltip-button-show-event" variant="primary">I have a tooltip</b-button>
</div>
<div class="p-2">
<b-button class="px-1" @click="onOpen">Open</b-button>
<b-button class="px-1" @click="onClose">Close</b-button>
</div>
<b-tooltip ref="tooltip" target="tooltip-button-show-event">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</template>
<script>
export default {
methods: {
onOpen() {
this.$refs.tooltip.$emit('open')
},
onClose() {
this.$refs.tooltip.$emit('close')
}
}
}
</script>
$root
イベントを使用して、ツールチップの表示と非表示をトリガーすることもできます。詳細については、以下の$rootイベントを介したツールチップの表示と非表示セクションを参照してください。
同期可能なブール値プロパティdisabled
(デフォルトはfalse
)を使用してツールチップを無効にすることができます。これをtrue
に設定すると、ツールチップが無効になります。 disabledがfalse
に設定されたときにツールチップが現在表示されている場合は、ツールチップが有効になるか、プログラムで閉じられるまで表示されたままになります。$root
イベントを介してツールチップが無効/有効にされた場合(下記参照)、.sync
プロパティ修飾子を指定している限り、disabled
の値が更新されます。
<template>
<div class="d-flex flex-column text-md-center">
<div class="p-2">
<b-button id="tooltip-button-disable" variant="primary">I have a tooltip</b-button>
</div>
<div class="p-2">
<b-button @click="disabled = !disabled">
{{ disabled ? 'Enable' : 'Disable' }} Tooltip by prop
</b-button>
<b-button @click="disableByRef">
{{ disabled ? 'Enable' : 'Disable' }} Tooltip by $ref event
</b-button>
<b-tooltip :disabled.sync="disabled" ref="tooltip" target="tooltip-button-disable">
Hello <strong>World!</strong>
</b-tooltip>
</div>
</div>
</template>
<script>
export default {
data() {
return {
disabled: false
}
},
methods: {
disableByRef() {
if (this.disabled) {
this.$refs.tooltip.$emit('enable')
} else {
this.$refs.tooltip.$emit('disable')
}
}
}
}
</script>
注:上記の例では、デフォルトのツールチップトリガーのfocus hover
を使用しているため、トグルボタンへのフォーカス(およびホバー)を失うために、ツールチップは無効になる前に閉じます。
$root
イベントを送信して、ツールチップの無効化と有効化をトリガーすることもできます。詳細については、以下の$rootイベントを介したツールチップの無効化と有効化セクションを参照してください。
$root
イベントを送信して、ポップオーバーの無効化と有効化をトリガーすることもできます。詳細については、以下の$rootイベントを介したツールチップの無効化と有効化セクションを参照してください。
v-b-tooltip
ディレクティブを使用すると、追加のプレースホルダーマークアップなしで、ツールチップをより簡単に簡単に追加できます。
<b-container fluid>
<b-row>
<b-col md="6" class="py-4">
<b-button v-b-tooltip title="Online!" variant="outline-success">Live chat</b-button>
</b-col>
<b-col md="6" class="py-4">
<b-button
v-b-tooltip.html
title="Hello <strong>World!</strong>"
variant="outline-success"
>
Html chat
</b-button>
</b-col>
</b-row>
</b-container>
ディレクティブ形式の詳細と機能については、v-b-tooltip
ドキュメントを参照してください。
'グローバル'$root
インスタンスイベント
$root
インスタンスを使用すると、<b-collapse>
が使用されているコンポーネントの外部でイベントを送信およびリッスンできます。簡単に言うと、$root
はグローバルイベントエミッターおよびリスナーのように動作します。$root
インスタンスの詳細については、公式Vueドキュメントを参照してください。
$root
でbv::hide::tooltip
イベントを送信することで、開いているすべてのツールチップを閉じることができます(非表示)。
this.$root.$emit('bv::hide::tooltip')
特定のツールチップを閉じるには、トリガー要素のid
、またはツールチップのid
(id
プロパティで提供されている場合)を引数として渡します。
this.$root.$emit('bv::hide::tooltip', 'my-trigger-button-id')
特定のツールチップを開くには、bv::show::tooltip
$rootイベントを送信するときに、トリガー要素のid
、またはツールチップのid
(id
プロパティで提供されている場合)を引数として渡します。
this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')
すべてのツールチップを同時に開くには、bv::show::tooltip
イベントを送信するときに、id
引数を省略します。
これらのイベントは、ツールチップのコンポーネントバージョンとディレクティブバージョンの両方で機能します。
注:ツールチップを表示するには、トリガー要素がDOMに存在し、表示されている状態である必要があります。
$root
でbv::disable::tooltip
イベントを送信することで、開いているすべてのツールチップを無効にすることができます。
this.$root.$emit('bv::disable::tooltip')
特定のツールチップを無効にするには、トリガー要素のid
、またはツールチップのid
(id
プロパティで提供されている場合)を引数として渡します。
this.$root.$emit('bv::disable::tooltip', 'my-trigger-button-id')
特定のツールチップを有効にするには、bv::enable::tooltip
$rootイベントを送信するときに、トリガー要素のid
、またはツールチップのid
(id
プロパティで提供されている場合)を引数として渡します。
this.$root.$emit('bv::enable::tooltip', 'my-trigger-button-id')
すべてのツールチップを同時に有効にするには、bv::enable::tooltip
イベントを送信するときに、id
引数を省略します。
これらのイベントは、ツールチップのコンポーネントバージョンとディレクティブバージョンの両方で機能します。
注:ツールチップを有効または無効にするには、トリガー要素がDOMに存在する必要があります。
ツールチップが開くのを監視するには、以下を使用します。
export default {
mounted() {
this.$root.$on('bv::tooltip::show', bvEvent => {
console.log('bvEvent:', bvEvent)
})
}
}
イベントの完全なリストについては、ドキュメントのイベントセクションを参照してください。
アクセシビリティ
ツールチップが表示されている場合、トリガー要素には、ツールチップの自動生成されたIDが設定された属性aria-describedby
が設定されます。
注: このコンポーネントのアニメーション効果は、prefers-reduced-motion
メディアクエリに依存しています。詳細については、アクセシビリティドキュメントのモーション低減セクションを参照してください。