Tooltip 文字提示

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

基础用法

Tooltip 组件内置了 9 个方位。

使用 `content` 属性来决定 `hover` 时的提示信息。 `placement` 属性决定 `tooltip` 的出现位置,值可选:`[方向]-[对齐]`,四个方向 `top`, `left`, `right`, `bottom`,三个对齐 `start`, `end`, `null`,默认值为 `null`。 以 `placement="left-end"` 为例,Tooltip 将会显示在目标元素的左侧,并且 Tooltip 的底部将与目标元素的底部对齐。

主题

Tooltip 组件内置了 `dark` 和 `light` 两种主题。

提示

要使用自定义主题,你需要知道你的 `tooltip` 渲染在哪里,如果你的 `tooltip` 是渲染在根元素上,你就需要全局设置 CSS 规则。

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

通过设置 `effect` 属性来修改主题,默认值为 `dark`。

更多内容的文字提示

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

通过添加一个 `content` 插槽,可替换 `el-tooltip` 中的 `content` 属性。

高级用法

除了这些基本配置项,还有一些属性可以让您自定义自己的

`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` 的内容是可信的,**永远不要**将用户提交的内容作为 `content` 的值。

虚拟触发

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

提示

虚拟触发 tooltip 是一个受控组件,因此,当这种情况发生时,你将不得不自己控制 tooltip 的可见性,你将**不能**通过点击其他地方来关闭 tooltip。

单例

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

提示

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

受控

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

动画

Tooltip 的动画可以自定义,你可以通过 `transition` 来设置你想要的动画。

提示

过渡动画类,更多信息请参阅 Vue 过渡动画

使用 `append-to`

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

API

属性

名称描述类型默认值
append-toTooltip 的内容将附加到哪个元素CSSSelector / HTMLElement
effectTooltip 的主题,内置主题:`dark` / `light`枚举暗黑模式
content显示的内容,可通过 `slot#content` 覆盖string''
raw-content`content` 中的内容是否作为 HTML 字符串处理booleanfalse
placementTooltip 的出现位置枚举bottom
fallback-placements当 Tooltip 的位置超出视图时,可备选的位置列表 popper.jsarray
visible / v-model:visibleTooltip 是否可见boolean
disabledTooltip 是否被禁用boolean
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隐藏提示框的超时毫秒数number0
popper-class为 Tooltip 的 popper 添加自定义类名string
enterable鼠标是否可进入到 tooltip 中booleantrue
teleportedtooltip 的内容是否被 teleported,如果是 `true`,它将被 teleported 到 `append-to` 设置的位置booleantrue
trigger如何触发 tooltip(显示)枚举悬浮时
virtual-triggering指示是否启用虚拟触发boolean
virtual-ref表示 tooltip 附加到的引用元素HTMLElement
trigger-keys当您点击鼠标聚焦于触发元素时,您可以通过键盘定义一组键盘码来控制 Tooltip 的显示。数组['Enter','Space']
persistent当 tooltip 不活跃且 `persistent` 为 `false` 时,popconfirm 将被销毁boolean
aria-label 无障碍与 `aria-label` 相同string

插槽

名称描述
defaultTooltip 触发和参考元素
content自定义内容

暴露

名称描述类型
popperRefel-popper 组件实例object
contentRefel-tooltip-content 组件实例object
isFocusInsideContent验证当前焦点事件是否在 el-tooltip-content 内部触发Function
updatePopper更新 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>

来源

组件源码样式源码文档

贡献者