Tooltip 文字提示
鼠标悬浮时显示提示信息。
基础用法
Tooltip 组件内置了 9 个方向。
使用 content
属性来设置鼠标悬浮时显示的内容。 通过 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`
您必须等待 DOM 挂载后才能使用 targetElement
。
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 内容是否被传送,如果为 true ,它将被传送到 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>