Skip to page content

悬浮提示

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

用法

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

基础



WARNING

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

自定义

过渡效果

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

可复用的

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

定位

QTooltip 的位置可以自定义。它考虑了可选的 anchorself 属性。 QTooltip 弹出窗口的最终位置是通过计算得出的,以便它将显示在可用的屏幕空间上,必要时会切换到右侧和/或顶部。

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

TIP

offset 属性是相对于锚点元素的边界框来应用的,应用之后最终位置才会被限制在可用的屏幕空间内。因此,如果偏移量过大,或者 QTooltip 锚定在一个全宽/紧贴屏幕边缘的元素上,弹出层可能会被推到视口边缘而被强制裁剪,此时 offset 看起来就像没有生效(被裁剪后的位置与 offset 值无关了)。如果你发现 offset 在某个轴向上似乎被忽略了,请确保所选的 anchor/self 让弹出层有足够的自由空间来扩展——例如,将 QTooltip 挂载到一个 inline / inline-block 触发器上,而不是一个全宽的块级元素上。


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 本身对鼠标是透明的(无法被悬停,当指针离开锚点时它会隐藏),所以请保持其内容简短且非交互式。