Tooltip 文字提示 ​

常用于展示鼠标 hover 时的提示信息。

基础用法 ​

在这里我们提供 9 种不同方向的展示方式,可以通过以下完整示例来理解,选择你要的效果。

使用 content 属性来决定 hover 时的提示信息。 由 placement 属性决定展示效果: placement属性值为:[方向]-[对齐位置];四个方向:top、left、right、bottom;三种对齐位置:start, end,默认为空。 如 placement="left-end",则提示信息出现在目标元素的左侧,且提示信息的底部与目标元素的底部对齐。

主题 ​

Tooltip 组件内置了两个主题:dark和light。

TIP

要使用自定义主题,您必须知道您的工具提示在哪里渲染, 如果您的工具提示被呈现为根元素,您将需要全局设置 css 规则。

建议您使用自定义主题并同时显示箭头时不使用线性渐变背景颜色。 因为弹出箭头和内容是两个不同的元素, 弹出箭头的样式需要单独设置, 当它到渐变背景颜色时,会看起来很奇怪。

通过设置 effect 来修改主题,默认值为 light.

更多内容的文字提示 ​

展示多行文本或者是设置文本内容的格式

用具名 slot content,替代tooltip中的content属性。

超限滚动 ​

通过 max-width / max-height 限定弹出层内容区的最大尺寸,避免超长提示内容整体溢出。 max-height 非空时,超出高度的内容会由滚动容器承载,可纵向滚动查看;max-width 只约束宽度,不会产生滚动。 数字值按 px 处理,也可以直接传入带单位的字符串(如 20rem、80vh)。 若不希望尺寸约束生效,可继续用 popper-style 显式传入同名属性覆盖。

max-width 与 max-height 对 content 属性与具名 slot content 两种内容形态同样生效。

高级扩展 ​

除了这些基本设置外,还有一些属性可以让使用者更好的定制自己的效果:

transition 属性可以定制显隐的动画效果,默认为fade-in-linear。

如果需要关闭 tooltip 功能,disabled 属性可以满足这个需求, 你只需要将其设置为 true。

事实上,Tooltip 是一个基于 WPopper 的扩展,您可以使用 WPopper 中允许的任何属性。

TIP

Tooltip 内不支持 router-link 组件,请使用 vm.$router.push 代替。

tooltip 内不支持 disabled form 元素,参考 MDN, 请在 disabled form 元素外层添加一层包裹元素。

显示 HTML 内容 ​

内容属性可以设置为 HTML 字符串。

WARNING

content 属性虽然支持传入 HTML 片段,但是在网站上动态渲染任意 HTML 是非常危险的,因为容易导致 XSS 攻击。 因此在 raw-content 打开的情况下,请确保 content 的内容是可信的,永远不要将用户提交的内容赋值给 content 属性。

虚拟触发 ​

有时候我们想把 tooltip 的触发元素放在别的地方,而不需要写在一起,这时候就可以使用虚拟触发。

TIP

需要注意的是,虚拟触发的 tooltip 是受控组件,因此你必须自己去控制 tooltip 是否显示,你将无法通过点击空白处来关闭 tooltip。

单例模式 ​

Tooltip 可以作为单例,也就是是说你可以同时有多个触发同一个 tooltip 的触发元素,这个功能是在 虚拟触发 的基础上开发的。

TIP

已知问题:使用单例模式时,弹出窗口会从意料之外的位置弹出。

受控模式 ​

Tooltip 可以通过父组件使用 :visible 来控制它的显示与关闭。受控模式下 trigger 无效,不必再设置。

自定义动画 ​

Tooltip 可以自定义动画,您可以使用 transition 设置所需的动画效果。

TIP

过渡效果的更多信息可以在 Vue 过渡效果 中找到。

API ​

属性 ​

名称说明类型默认值
append-totooltip 内容挂载到哪个元素CSSSelector / HTMLElement—
effectTooltip 主题,内置主题:dark / light / lighterenumlight
content显示内容,可被 slot#content 覆盖string''
raw-content是否将 content 作为 HTML 字符串处理booleanfalse
max-widthTooltip 内容区最大宽度string / number''
max-heightTooltip 内容区最大高度,非空时内容超限纵向滚动string / number''
placementTooltip 的出现位置enumbottom
fallback-placementsTooltip 可能的备用位置列表(参考 popper.js)array—
visible / v-model:visibleTooltip 是否可见boolean—
disabled是否禁用 Tooltipboolean—
offsetTooltip 的偏移量number12
transition动画名称string—
popper-optionspopper.js 参数object参考 popper.js 文档{}
arrow-offset控制 tooltip 箭头相对 popper 的偏移(padding)number5
show-after显示延迟(毫秒),受控模式下无效number0
show-arrowtooltip 内容是否显示箭头booleantrue
hide-after隐藏延迟(毫秒),受控模式下无效number200
auto-close自动隐藏的超时时间(毫秒),受控模式下无效number0
popper-classTooltip 弹出层的自定义类名string—
popper-styleTooltip 弹出层的自定义样式string / object—
enterable鼠标是否可进入 tooltipbooleantrue
teleportedtooltip 内容是否 teleport;若为 true,将传送到 append-to 指定的位置booleantrue
triggerTooltip 的触发方式(显示),受控模式下无效enum / arrayhover
virtual-triggering是否启用虚拟触发boolean—
virtual-reftooltip 所依附的参考元素(虚拟触发用)HTMLElement—
trigger-keys鼠标点击聚焦触发元素后,可定义一组键盘码通过键盘控制 tooltip 显示(受控模式下无效)Array['Enter','Space']
persistenttooltip 不可见且 persistent 为 false 时,tooltip 将被销毁boolean—
aria-label a11y同 aria-labelstring—
focus-on-targethover 触发时,是否聚焦触发元素(提升可访问性)booleanfalse

事件 ​

名称说明类型
before-showTooltip 显示前触发,参数为触发事件。Function
showTooltip 显示时触发,参数为触发事件。Function
before-hideTooltip 隐藏前触发,参数为触发事件。Function
hideTooltip 隐藏时触发,参数为触发事件。Function

插槽 ​

名称说明
defaultTooltip 的触发/参考元素,只接受单一根元素
content自定义内容

暴露 ​

名称说明类型
popperRefw-popper 组件实例object
contentRefw-tooltip-content 组件实例object
isFocusInsideContent判断当前焦点事件是否发生在 w-tooltip-content 内Function
updatePopper更新 w-popper 组件实例Function
onOpen暴露 onOpen,用于管理 w-tooltip 打开状态Function
onClose暴露 onClose,用于管理 w-tooltip 关闭状态Function
hide暴露 hide 方法Function

FAQ ​

Tooltip 嵌套时,如何在输入框中允许输入空格? ​

vue
<template>
  <w-tooltip
    content="请输入主诉症状,空格亦有效"
    placement="top"
    :trigger-keys="[]"
  >
    <w-input v-model="value" placeholder="请输入主诉" />
  </w-tooltip>
</template>

Copyright 2025 Winning Health 版权所有