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-to | Tooltip 的内容将附加到哪个元素 | CSSSelector / HTMLElement | — |
effect | Tooltip 的主题,内置主题:`dark` / `light` | 枚举 | 暗黑模式 |
content | 显示的内容,可通过 `slot#content` 覆盖 | string | '' |
raw-content | `content` 中的内容是否作为 HTML 字符串处理 | boolean | false |
placement | Tooltip 的出现位置 | 枚举 | bottom |
fallback-placements | 当 Tooltip 的位置超出视图时,可备选的位置列表 popper.js | array | — |
visible / v-model:visible | Tooltip 是否可见 | boolean | — |
disabled | Tooltip 是否被禁用 | boolean | — |
offset | Tooltip 的偏移量 | number | 12 |
transition | 动画名称 | string | — |
popper-options | popper.js 的参数 | object 参考 popper.js 文档 | {} |
arrow-offset 2.9.10 | 控制 tooltip 箭头的偏移量(内边距),相对于 popper。 | number | 5 |
show-after | 延迟出现,单位毫秒 | number | 0 |
show-arrow | Tooltip 内容是否有箭头 | boolean | true |
hide-after | 延迟消失,单位毫秒 | number | 200 |
auto-close | 隐藏提示框的超时毫秒数 | number | 0 |
popper-class | 为 Tooltip 的 popper 添加自定义类名 | string | — |
enterable | 鼠标是否可进入到 tooltip 中 | boolean | true |
teleported | tooltip 的内容是否被 teleported,如果是 `true`,它将被 teleported 到 `append-to` 设置的位置 | boolean | true |
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 | — |
插槽
名称 | 描述 |
---|---|
default | Tooltip 触发和参考元素 |
content | 自定义内容 |
暴露
名称 | 描述 | 类型 |
---|---|---|
popperRef | el-popper 组件实例 | object |
contentRef | el-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
<template>
<el-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
<el-input v-model="value" placeholder="" />
</el-tooltip>
</template>