Tooltip 文字提示

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

基础用法

Tooltip 有 9 种弹出位置。

使用 content 属性来设定鼠标悬停时显示的文字。 属性 placement 决定了提示信息出现的位置。 它的值由 [orientation]-[alignment] 组成,包含四种方向 topleftrightbottom 以及三种对齐方式 startendnull,默认对齐方式为 null。 以 placement="left-end" 为例,Tooltip 将显示在鼠标悬停元素的左侧,且 Tooltip 的底部与元素的底部对齐。

主题

Tooltip 有两种内置主题:darklight

提示

要使用自定义主题,您需要了解 Tooltip 被渲染到的位置,如果 Tooltip 被渲染到了根元素中,您需要全局设置 CSS 规则。

在使用自定义主题并同时显示小箭头时,建议不要使用线性渐变背景色,因为弹出箭头和内容是两个不同的元素,弹出箭头的样式需要单独设置,涉及到渐变背景色时,可能会显得有些奇怪。

设置 effect 来修改主题,默认值为 dark

更多内容

展示多行文本并设置其格式。

通过添加名为 content 的插槽,可以覆盖 el-tooltipcontent 属性。

高级用法

除了基本用法外,还有一些属性可以让您自定义您的组件

transition 属性允许您自定义 Tooltip 显示或隐藏时的动画,默认值为 el-fade-in-linear。

disabled 属性允许您禁用 tooltip。 您只需将其设置为 true 即可。

实际上,Tooltip 是基于 ElPopper 的扩展,您可以使用 ElPopper 中允许的所有属性。

提示

Tooltip 中不支持 router-link 组件,请使用 vm.$router.push

Tooltip 不支持禁用的表单元素,更多信息可以在 MDN 上找到。 您需要用一个容器元素包裹禁用的表单元素,Tooltip 才能生效。

HTML 作为内容

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

警告

虽然 content 属性支持 HTML 字符串,但在网站上动态渲染任意 HTML 可能非常危险,因为这很容易导致 XSS 攻击。 因此,当开启 raw-content 时,请确保 content 是可信的,并且**绝不要**将用户提供的内容赋值给它。

虚拟触发

有时我们希望在其他触发元素上渲染 Tooltip,我们可以将触发器和内容分开。

提示

虚拟触发 Tooltip 是受控组件,因此当这种情况发生时,您必须自己控制 Tooltip 的可见性,您**将无法**通过点击其他地方来关闭 Tooltip。

单例模式

Tooltip 也可以是单例的,这意味着您可以拥有多个触发器,但只有一个 Tooltip 实例,此功能基于 虚拟触发 实现

提示

已知问题:使用单例模式时,弹出窗口会从意想不到的地方弹出

受控模式

Tooltip 可以由父组件控制,通过使用 :visible 属性,您可以实现双向绑定。

动画

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

提示

过度类名 (Transition Classes),更多信息可以在 Vue Transition 找到。

使用 append-to

在使用 targetElement 之前,您必须等待 DOM 挂载完成。

API

属性

名称描述类型默认值
append-toTooltip 内容 (CONTENT) 挂载到的元素CSSSelector / HTMLElement
effectTooltip 的主题,内置主题:`dark` / `light`枚举暗黑模式
content显示的内容,可以被 slot#content 覆盖string''
raw-content (HTML内容)是否将 content 视为 HTML 字符串booleanfalse
placementTooltip 的位置枚举bottom
fallback-placementsTooltip 可能的位置列表 popper.jsarray
visible / v-model:visibleTooltip 的可见性boolean
disabled是否禁用 Tooltipboolean
offsetTooltip 的偏移量number12
transition动画名称string
popper-optionspopper.js 参数object请参考 popper.js 文档{}
arrow-offset 小箭头偏移量 2.9.10控制 Tooltip 箭头相对于 popper 的偏移量(填充)。number5
show-after出现延迟,单位毫秒,在受控模式下无效number0
show-arrowTooltip 内容是否带有小箭头booleantrue
hide-after消失延迟,单位毫秒,在受控模式下无效number200
auto-close自动隐藏 Tooltip 的超时时间,单位毫秒,在受控模式下无效number0
popper-classTooltip Popper 的自定义类名string
popper-styleTooltip Popper 的自定义样式string / object
enterable (可进入)鼠标是否可以进入 Tooltipbooleantrue
teleportedTooltip 内容是否使用 teleport,如果为 true,它将传送到 append-to 设置的位置booleantrue
triggerTooltip 如何触发(显示),在受控模式下无效enum / array悬浮时
virtual-triggering指示是否启用虚拟触发boolean
virtual-ref指示 Tooltip 挂载的参考元素HTMLElement
trigger-keys (触发按键)当您通过鼠标点击聚焦触发元素时,可以定义一组键盘代码,通过键盘控制 Tooltip 的显示,在受控模式下无效数组['Enter','Space']
persistent当 Tooltip 不活跃且 persistentfalse 时,Tooltip 将被销毁boolean
aria-label 无障碍aria-labelstring
focus-on-target (聚焦于目标) 2.11.2通过悬停触发 Tooltip 时,是否聚焦触发元素,这可以提高可访问性booleanfalse

事件

名称描述类型
before-show (显示前)Tooltip 显示前触发。 将触发原因作为参数传递。Function
showTooltip 显示时触发。 将触发原因作为参数传递。Function
before-hide (隐藏前)Tooltip 隐藏前触发。 将触发原因作为参数传递。Function
hideTooltip 隐藏时触发。 将触发原因作为参数传递。Function

插槽

名称描述
defaultTooltip 触发和参考元素,仅接受单个根元素
content自定义内容

暴露

名称描述类型
popperRefel-popper 组件实例object
contentRefel-tooltip-content 组件实例object
isFocusInsideContent (焦点是否在内容中)验证当前焦点事件是否在 el-tooltip-content 内部触发Function
updatePopper (更新 Popper)更新 el-popper 组件实例Function
onOpen (打开回调)暴露 onOpen 函数以管理 el-tooltip 的打开状态Function
onClose暴露 onClose 函数以管理 el-tooltip 的打开状态Function
hide暴露隐藏 (hide) 函数Function

常见问题

嵌套 Tooltip 时如何允许输入框中出现空格?

典型问题: #20907

vue
<template>
  <el-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
    <el-input v-model="value" placeholder="" />
  </el-tooltip>
</template>

来源

组件样式文档

贡献者