Tooltip 文字提示

鼠标悬停时展示提示信息。

基础用法

共有 9 个出现位置。

使用 content 设置悬停时展示的内容。placement 决定提示位置,取值为 [方向]-[对齐]:方向含 topleftrightbottom,对齐含 startend、空(默认)。例如 placement="left-end" 表示提示在元素左侧,且提示底部与元素底部对齐。

主题

内置 darklight 两种主题。

TIP

使用自定义主题时,需要清楚提示渲染到何处。若挂载在根节点,需在全局编写样式。

不建议在同时显示箭头时使用线性渐变背景,因为箭头与内容为两个元素,箭头样式需单独设置,渐变背景可能看起来不协调。

使用 effect 修改主题,默认为 dark

更多内容

可展示多行文本并设置格式。

通过名为 content 的插槽覆盖 el-tooltipcontent 属性。

高级用法

除基础用法外,还可通过属性自定义:

transition 可自定义显示/隐藏动画,默认 el-fade-in-linear

disabled 设为 true 可禁用文字提示。

文字提示基于 UPopper 扩展,可使用 UPopper 允许的属性。

TIP

文字提示内不支持 router-link,请使用 vm.$router.push

文字提示不支持已禁用的表单元素,详见 MDN。需在外层包裹容器元素才能生效。

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 / lightenumdark
content展示内容,可被 slot#content 覆盖string''
raw-content是否将 content 作为 HTML 字符串解析booleanfalse
placement出现位置enumbottom
fallback-placements可能出现的位置列表,见 popper.jsarray
visible / v-model:visible是否可见boolean
disabled是否禁用boolean
offset偏移量number12
transition动画名称string
popper-optionspopper.js 参数object 参见 popper.js 文档{}
arrow-offset控制箭头相对浮层的偏移(内边距)number5
show-after延迟显示(毫秒),受控模式下无效number0
show-arrow是否显示箭头booleantrue
hide-after延迟隐藏(毫秒),受控模式下无效number200
auto-close自动隐藏超时(毫秒),受控模式下无效number0
popper-class浮层自定义类名string
popper-style浮层自定义样式string / object
enterable鼠标是否可进入提示区域booleantrue
teleported是否将内容传送至 append-to 指定位置booleantrue
trigger触发方式,受控模式下无效enum / arrayhover
virtual-triggering是否启用虚拟触发boolean
virtual-ref虚拟触发时关联的参考元素HTMLElement
trigger-keys鼠标聚焦触发元素后,可通过键盘码控制显示,受控模式下无效Array['Enter','Space']
persistent非激活且为 false 时销毁提示boolean
aria-label a11yaria-labelstring
focus-on-target悬停触发时是否聚焦触发元素,以提升无障碍体验booleanfalse

事件

名称说明类型
before-show显示前触发,参数为触发原因对应的事件Function
show显示时触发,参数为触发原因对应的事件Function
before-hide隐藏前触发,参数为触发原因对应的事件Function
hide隐藏时触发,参数为触发原因对应的事件Function

插槽

名称说明
default触发与参考元素,仅接受单一根元素
content自定义内容

暴露

名称说明类型
popperRefel-popper 组件实例object
contentRefel-tooltip-content 组件实例object
isFocusInsideContent判断当前聚焦是否在 el-tooltip-contentFunction
updatePopper更新 el-popper 实例Function
onOpen打开状态处理函数Function
onClose关闭状态处理函数Function
hide隐藏函数Function

常见问题

嵌套文字提示时输入框无法输入空格?

典型问题:#20907

vue
<template>
  <u-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
    <u-input v-model="value" placeholder="" />
  </u-tooltip>
</template>