Tooltip 文字提示
常用于展示鼠标悬停时的提示信息。
基础用法
Tooltip 有 9 种弹出位置。
使用 content 属性来设定鼠标悬停时显示的文字。 属性 placement 决定了提示信息出现的位置。 它的值由 [orientation]-[alignment] 组成,包含四种方向 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 是可信的,并且**绝不要**将用户提供的内容赋值给它。
虚拟触发
有时我们希望在其他触发元素上渲染 Tooltip,我们可以将触发器和内容分开。
提示
虚拟触发 Tooltip 是受控组件,因此当这种情况发生时,您必须自己控制 Tooltip 的可见性,您**将无法**通过点击其他地方来关闭 Tooltip。
单例模式
Tooltip 也可以是单例的,这意味着您可以拥有多个触发器,但只有一个 Tooltip 实例,此功能基于 虚拟触发 实现
提示
已知问题:使用单例模式时,弹出窗口会从意想不到的地方弹出
受控模式
Tooltip 可以由父组件控制,通过使用 :visible 属性,您可以实现双向绑定。
动画
Tooltip 动画可以自定义,您可以使用 transition 设置所需的动画。
提示
过度类名 (Transition Classes),更多信息可以在 Vue Transition 找到。
使用 append-to
在使用 targetElement 之前,您必须等待 DOM 挂载完成。
API
属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| append-to | Tooltip 内容 (CONTENT) 挂载到的元素 | CSSSelector / HTMLElement | — |
| effect | Tooltip 的主题,内置主题:`dark` / `light` | 枚举 | 暗黑模式 |
| content | 显示的内容,可以被 slot#content 覆盖 | string | '' |
| raw-content (HTML内容) | 是否将 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 | 自动隐藏 Tooltip 的超时时间,单位毫秒,在受控模式下无效 | number | 0 |
| popper-class | Tooltip Popper 的自定义类名 | string | — |
| popper-style | Tooltip Popper 的自定义样式 | string / object | — |
| enterable (可进入) | 鼠标是否可以进入 Tooltip | boolean | true |
| teleported | Tooltip 内容是否使用 teleport,如果为 true,它将传送到 append-to 设置的位置 | boolean | true |
| trigger | Tooltip 如何触发(显示),在受控模式下无效 | enum / array | 悬浮时 |
| virtual-triggering | 指示是否启用虚拟触发 | boolean | — |
| virtual-ref | 指示 Tooltip 挂载的参考元素 | HTMLElement | — |
| trigger-keys (触发按键) | 当您通过鼠标点击聚焦触发元素时,可以定义一组键盘代码,通过键盘控制 Tooltip 的显示,在受控模式下无效 | 数组 | ['Enter','Space'] |
| persistent | 当 Tooltip 不活跃且 persistent 为 false 时,Tooltip 将被销毁 | boolean | — |
| aria-label 无障碍 | 同 aria-label | string | — |
| focus-on-target (聚焦于目标) 2.11.2 | 通过悬停触发 Tooltip 时,是否聚焦触发元素,这可以提高可访问性 | boolean | false |
事件
| 名称 | 描述 | 类型 |
|---|---|---|
| before-show (显示前) | Tooltip 显示前触发。 将触发原因作为参数传递。 | Function |
| show | Tooltip 显示时触发。 将触发原因作为参数传递。 | Function |
| before-hide (隐藏前) | Tooltip 隐藏前触发。 将触发原因作为参数传递。 | Function |
| hide | Tooltip 隐藏时触发。 将触发原因作为参数传递。 | Function |
插槽
| 名称 | 描述 |
|---|---|
| default | Tooltip 触发和参考元素,仅接受单个根元素 |
| content | 自定义内容 |
暴露
| 名称 | 描述 | 类型 |
|---|---|---|
| popperRef | el-popper 组件实例 | object |
| contentRef | el-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
<template>
<el-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
<el-input v-model="value" placeholder="" />
</el-tooltip>
</template>