Skip to page content

悬浮提示

QTooltip 组件用于向用户提供有关应用程序中某个区域的更多信息。当鼠标悬停在目标元素上时(或者在移动平台上快速点击并保持) ,工具提示就会出现。

用法

QTooltip 的理念是将其作为直接子元素放置在您希望作为触发器的 DOM 元素/组件内部。不用担心 QTooltip 内容从容器继承 CSS,因为 QTooltip 将通过 Quasar Portal 被注入为 <body> 的直接子级。

基础



WARNING

如果您想要有条件地激活或停用 QTooltip,请使用 v-if 而不是 v-show。

自定义

过渡效果

下面的示例展示了几种过渡效果。有关可用过渡效果的完整列表,请参阅过渡效果。

可复用的

下面的例子展示了如何创建可以与不同目标共享的可复用的菜单。

定位

QTooltip 的位置可以自定义。它考虑了可选的 anchor 和 self 属性。 QTooltip 弹出窗口的最终位置是通过计算得出的,以便它将显示在可用的屏幕空间上:当请求的摆放位置放不下时,若锚点在该轴上的相反一侧空间更充裕,弹出层就会翻转到相反一侧,否则仍停留在请求的一侧(因此当触发器上下空间相等时,会保留你设置的 anchor/self),并被限制在它所拥有的空间内。

关于水平方向上的定位,如果您希望其自动适应 RTL 或 non-RTL,您可以使用 start 和 end。start 和 end 在 non-RTL 中表示"左",在 RTL 中表示"右"。

TIP

offset 属性并不会把弹出层按指定的像素数「平移」。它是把锚点元素的边界框向外撑开:offset[0] 让边界框的 left(左)边向左移、right(右)边向右移,而 offset[1] 让 top(上)边向上移、bottom(下)边向下移。随后弹出层的 self 点会对齐到撑开后边界框的 anchor 点,最后再把结果限制在可用的屏幕空间内。

有两个后果值得了解,因为它们都会让 offset 看起来像是在某个轴向上被忽略了:

  • middle 或 center 锚点不会随 offset 移动。 两边被撑开相同的量后,中点仍停留在原处,所以无论传入什么值,offset[0] 对 anchor="... middle" 都是空操作(no-op),offset[1] 对 anchor="center ..." 也是空操作。QTooltip 默认的 anchor 是 bottom middle,因此只有当你改用 left、right、start 或 end 锚点后,它的水平方向 offset 才会开始生效。
  • 被裁剪的弹出层同样不会随 offset 移动。 由于 offset 是把边界框向外推,把 QTooltip 锚定在全宽或紧贴屏幕边缘的元素上(或传入一个非常大的值),可能会把弹出层推出视口边缘,在那里它会被裁剪回来,最终位置也就不再取决于 offset 值了。请把 QTooltip 挂载到 inline 或 inline-block 触发器上,并让 anchor/self 指向有自由空间的方向,这样 offset 才有发挥的余地。

简而言之,若想把弹出层放在距锚点元素某一侧固定像素距离的位置,请在 anchor 中直接指定那一侧,而不要依赖 middle/center。


Anchor Origin
Vertical
Horizontal
Self Origin
Vertical
Horizontal

<q-tooltip anchor="bottom middle" self="top middle">
  Here I am!
</q-tooltip>

无障碍访问
v2.25+

QTooltip 实现了 WAI-ARIA tooltip 模式:弹出层渲染时带有 role="tooltip",在显示期间其 id 会被添加到锚点元素的 aria-describedby 中(你自行设置的值会被保留并在隐藏时恢复),这样屏幕阅读器会将 tooltip 内容作为锚点的描述播报。tooltip 在键盘聚焦时(当锚点匹配 :focus-visible 时)也会显示,就像悬停一样,Escape 隐藏它且不移动焦点,符合 WCAG 1.4.13 的要求。

需要记住两点。tooltip 是 描述 而非名称——纯图标按钮仍然需要自己的 aria-label,tooltip 只是补充说明。而且 tooltip 本身对鼠标是透明的(无法被悬停,当指针离开锚点时它会隐藏),所以请保持其内容简短且非交互式。