Tooltip 文字提示

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

TIP

在 SSR 场景下,您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

基础用法

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

主题

Tooltip 组件内置了两个主题:darklight

TIP

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

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

更多内容的文字提示

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

高级扩展

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

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

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

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

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 来控制它的显示与关闭。

自定义动画

Tooltip 可以自定义动画,你可以根据需要自行设置所需的动画方法。

API

Attributes

名称说明类型默认值
append-to指示 Tooltip 的内容将附加在哪一个网页元素上CSSSelector / HTMLElement
effectTooltip 主题,内置了 dark / light 两种enumdark
content显示的内容,也可被 slot#content 覆盖string''
raw-contentcontent 中的内容是否作为 HTML 字符串处理booleanfalse
placementTooltip 组件出现的位置enumbottom
fallback-placementsTooltip 可用的 positions 请查看popper.js 文档array
visible / v-model:visibleTooltip 组件可见性boolean
disabledTooltip 组件是否禁用boolean
offset出现位置的偏移量number12
transition动画名称string
popper-optionspopper.js 参数object 请参考 popper.js 文档{}
show-after在触发后多久显示内容,单位毫秒number0
show-arrowtooltip 的内容是否有箭头booleantrue
hide-after延迟关闭,单位毫秒number200
auto-closetooltip 出现后自动隐藏延时,单位毫秒number0
popper-class为 Tooltip 的 popper 添加类名string
enterable鼠标是否可进入到 tooltip 中booleantrue
teleported是否使用 teleport。设置成 true则会被追加到 append-to 的位置booleantrue
trigger如何触发 Tooltipenumhover
virtual-triggering用来标识虚拟触发是否被启用boolean
virtual-ref标识虚拟触发时的触发元素HTMLElement
trigger-keys当鼠标点击或者聚焦在触发元素上时, 可以定义一组键盘按键并且通过它们来控制 Tooltip 的显示Array['Enter','Space']
persistent当 tooltip 组件长时间不触发且 persistent 属性设置为 false 时, popconfirm 将会被删除boolean
aria-label a11yaria-label 属性保持一致string

Slots

插槽名说明
defaultTooltip 触发 & 引用的元素
content自定义内容

Exposes

名称详情类型
popperRefel-popper 组件实例object
contentRefel-tooltip0-content 组件实例object
isFocusInsideContent验证当前焦点事件是否在 el-tooltip-content 中触发Function
updatePopper更新 el-popper组件实例Function
onOpenonOpen 方法控制 el-tooltip 显示状态Function
onCloseonClose 方法控制 el-tooltip 显示状态Function
hide提供 hide 方法Function

源代码

组件文档

贡献者