Tooltip 文字提示
鼠标悬停时展示提示信息。
基础用法
共有 9 个出现位置。
使用 content 设置悬停时展示的内容。placement 决定提示位置,取值为 [方向]-[对齐]:方向含 top、left、right、bottom,对齐含 start、end、空(默认)。例如 placement="left-end" 表示提示在元素左侧,且提示底部与元素底部对齐。
主题
内置 dark 与 light 两种主题。
TIP
使用自定义主题时,需要清楚提示渲染到何处。若挂载在根节点,需在全局编写样式。
不建议在同时显示箭头时使用线性渐变背景,因为箭头与内容为两个元素,箭头样式需单独设置,渐变背景可能看起来不协调。
使用 effect 修改主题,默认为 dark。
更多内容
可展示多行文本并设置格式。
通过名为 content 的插槽覆盖 el-tooltip 的 content 属性。
高级用法
除基础用法外,还可通过属性自定义:
transition 可自定义显示/隐藏动画,默认 el-fade-in-linear。
disabled 设为 true 可禁用文字提示。
文字提示基于 UPopper 扩展,可使用 UPopper 允许的属性。
HTML 内容
content 可设为 HTML 字符串。
WARNING
虽然 content 支持 HTML 字符串,但在页面中动态渲染任意 HTML 存在 XSS 风险。启用 raw-content 时,请确保 content 来源可信,切勿将用户输入直接赋给 content。
虚拟触发
有时需要将提示挂载到其他触发元素上,从而分离触发区域与内容。
TIP
虚拟触发为受控模式,需自行控制显示;此时无法通过点击外部关闭提示。
单例
可启用单例模式:多个触发元素共享一个提示实例,基于「虚拟触发」实现。
TIP
已知问题:单例模式下,浮层可能从意外位置弹出。
受控模式
父组件可通过 :visible 实现双向绑定以控制显示。
动画
可通过 transition 自定义动画。
TIP
过渡类名说明见 Vue Transition。
使用 append-to
使用 targetElement 前需等待 DOM 挂载完成。
API
属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| append-to | 提示内容挂载到的元素 | CSSSelector / HTMLElement | — |
| effect | 主题,内置 dark / light | enum | dark |
| content | 展示内容,可被 slot#content 覆盖 | string | '' |
| raw-content | 是否将 content 作为 HTML 字符串解析 | boolean | false |
| placement | 出现位置 | enum | bottom |
| fallback-placements | 可能出现的位置列表,见 popper.js | array | — |
| visible / v-model:visible | 是否可见 | boolean | — |
| disabled | 是否禁用 | boolean | — |
| offset | 偏移量 | number | 12 |
| transition | 动画名称 | string | — |
| popper-options | popper.js 参数 | object 参见 popper.js 文档 | {} |
| arrow-offset | 控制箭头相对浮层的偏移(内边距) | number | 5 |
| show-after | 延迟显示(毫秒),受控模式下无效 | number | 0 |
| show-arrow | 是否显示箭头 | boolean | true |
| hide-after | 延迟隐藏(毫秒),受控模式下无效 | number | 200 |
| auto-close | 自动隐藏超时(毫秒),受控模式下无效 | number | 0 |
| popper-class | 浮层自定义类名 | string | — |
| popper-style | 浮层自定义样式 | string / object | — |
| enterable | 鼠标是否可进入提示区域 | boolean | true |
| teleported | 是否将内容传送至 append-to 指定位置 | boolean | true |
| trigger | 触发方式,受控模式下无效 | enum / array | hover |
| virtual-triggering | 是否启用虚拟触发 | boolean | — |
| virtual-ref | 虚拟触发时关联的参考元素 | HTMLElement | — |
| trigger-keys | 鼠标聚焦触发元素后,可通过键盘码控制显示,受控模式下无效 | Array | ['Enter','Space'] |
| persistent | 非激活且为 false 时销毁提示 | boolean | — |
| aria-label a11y | 同 aria-label | string | — |
| focus-on-target | 悬停触发时是否聚焦触发元素,以提升无障碍体验 | boolean | false |
事件
| 名称 | 说明 | 类型 |
|---|---|---|
| before-show | 显示前触发,参数为触发原因对应的事件 | Function |
| show | 显示时触发,参数为触发原因对应的事件 | Function |
| before-hide | 隐藏前触发,参数为触发原因对应的事件 | Function |
| hide | 隐藏时触发,参数为触发原因对应的事件 | Function |
插槽
| 名称 | 说明 |
|---|---|
| default | 触发与参考元素,仅接受单一根元素 |
| content | 自定义内容 |
暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| popperRef | el-popper 组件实例 | object |
| contentRef | el-tooltip-content 组件实例 | object |
| isFocusInsideContent | 判断当前聚焦是否在 el-tooltip-content 内 | Function |
| updatePopper | 更新 el-popper 实例 | Function |
| onOpen | 打开状态处理函数 | Function |
| onClose | 关闭状态处理函数 | Function |
| hide | 隐藏函数 | Function |
常见问题
嵌套文字提示时输入框无法输入空格?
典型问题:#20907
<template>
<u-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
<u-input v-model="value" placeholder="" />
</u-tooltip>
</template>