Tooltip 文字提示

常用于展示鼠标 hover 时的短提示信息。适合图标按钮说明、表格字段解释、被截断文本提示和报价计算器里的辅助说明。

基础用法

使用 content 设置提示内容，使用 placement 控制展示位置。位置由方向和对齐方式组成，例如 top-start、left、bottom-end。

<el-tooltip content="顶部左对齐提示" placement="top-start">
  <el-button>top-start</el-button>
</el-tooltip>

<el-tooltip content="底部右对齐提示" placement="bottom-end">
  <el-button>bottom-end</el-button>
</el-tooltip>

主题

Tooltip 内置 dark 和 light 两种主题，通过 effect 设置。需要自定义主题时，可以传入自定义 effect 并编写全局 popper 样式。

<el-tooltip content="深色提示" placement="top">
  <el-button>Dark</el-button>
</el-tooltip>
<el-tooltip content="浅色提示" placement="bottom" effect="light">
  <el-button>Light</el-button>
</el-tooltip>
<el-tooltip content="自定义主题提示" placement="bottom" effect="customized">
  <el-button>Customized</el-button>
</el-tooltip>

多行内容

当提示内容需要分行或包含简单格式时，使用 content 插槽替代 content 属性。

<el-tooltip placement="top">
  <template #content>
    <div>综合服务费包含：</div>
    <div>方案复核、项目协调、交付跟进</div>
  </template>
  <el-button>费用说明</el-button>
</el-tooltip>

高级扩展

disabled 可以关闭 Tooltip；show-after、hide-after、offset、show-arrow 可以调整显示延迟和浮层外观。

<template>
  <el-tooltip
    :disabled="disabled"
    content="点击按钮可以关闭或启用提示"
    placement="bottom"
    effect="light"
  >
    <el-button @click="disabled = !disabled">
      {{ disabled ? '启用提示' : '关闭提示' }}
    </el-button>
  </el-tooltip>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const disabled = ref(false)
</script>

显示 HTML 内容

设置 raw-content 后，content 会按 HTML 字符串渲染。该能力只适合可信内容，不要把用户提交的内容直接传给 content。

<el-tooltip
  content="<span>当前字段可填写 <strong>0-100</strong> 的数值</span>"
  raw-content
>
  <el-button>HTML 内容</el-button>
</el-tooltip>

受控模式

通过 visible 或 v-model:visible 可以手动控制 Tooltip 的显示与隐藏。

<template>
  <el-tooltip :visible="visible">
    <template #content>
      <span>由鼠标事件控制显示状态</span>
    </template>
    <el-button @mouseenter="visible = true" @mouseleave="visible = false">
      Hover me
    </el-button>
  </el-tooltip>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
</script>

虚拟触发

当触发元素和 Tooltip 内容不写在一起时，可以使用 virtual-triggering 与 virtual-ref 指定触发元素。虚拟触发通常需要手动控制显示状态。

<template>
  <button ref="buttonRef" @click="visible = !visible">虚拟触发按钮</button>
  <el-tooltip
    :visible="visible"
    :virtual-ref="buttonRef"
    virtual-triggering
    trigger="click"
    content="这个 Tooltip 通过 virtual-ref 绑定到按钮。"
    placement="bottom"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
const buttonRef = ref()
</script>

单例模式

单例模式可以让多个触发元素共用同一个 Tooltip。该能力基于虚拟触发实现，适合列表或工具栏中大量同类提示。

<template>
  <el-button
    v-for="item in items"
    :key="item"
    @mouseenter="buttonRef = $event.currentTarget"
    @click="visible = !visible"
  >
    {{ item }}
  </el-button>
  <el-tooltip
    :visible="visible"
    :virtual-ref="buttonRef"
    virtual-triggering
    content="多个按钮共用同一个 Tooltip"
  />
</template>

自定义动画

通过 transition 可以指定 Tooltip 的过渡动画。动画类名按 Vue Transition 规则编写。

<el-tooltip content="使用 slide-fade 动画" transition="slide-fade">
  <el-button>trigger me</el-button>
</el-tooltip>

使用 append-to

通过 append-to 可以指定 Tooltip 内容挂载到哪个元素。实际使用时应确保目标元素已经存在。

<el-tooltip
  append-to=".tooltip-append-target"
  trigger="click"
  content="挂载到 .tooltip-append-target"
  placement="top"
>
  <el-button>Click to open tooltip</el-button>
</el-tooltip>

Tooltip API

Tooltip 属性

属性名	说明	类型	默认值
append-to	Tooltip 内容挂载到哪个元素	CSSSelector | HTMLElement	-
effect	Tooltip 主题，内置 dark 和 light	dark | light | string	dark
content	显示内容，也可以通过 content 插槽覆盖	string	''
raw-content	content 是否作为 HTML 字符串处理	boolean	false
placement	Tooltip 出现位置	enum	bottom
fallback-placements	Tooltip 可用的备用位置	array	-
visible / v-model:visible	Tooltip 是否显示	boolean	-
disabled	Tooltip 是否禁用	boolean	false
offset	Tooltip 出现位置的偏移量	number	12
transition	动画名称	string	-
popper-options	popper.js 参数	object	{}
arrow-offset	Tooltip 箭头相对于弹出窗口的偏移	number	5
show-after	延迟显示时间，单位毫秒，受控模式下无效	number	0
hide-after	延迟隐藏时间，单位毫秒，受控模式下无效	number	200
auto-close	自动隐藏时间，单位毫秒，受控模式下无效	number	0
show-arrow	是否显示箭头	boolean	true
popper-class	为 Tooltip 的 popper 添加自定义类名	string	-
popper-style	为 Tooltip 的 popper 添加自定义样式	string | object	-
enterable	鼠标是否可以进入 tooltip 内容	boolean	true
teleported	是否使用 teleport	boolean	true
trigger	触发方式，受控模式下无效	hover | click | focus | contextmenu / array	hover
virtual-triggering	是否启用虚拟触发	boolean	false
virtual-ref	虚拟触发时的触发元素	HTMLElement	-
trigger-keys	通过键盘控制提示框显示的按键代码，受控模式下无效	array	['Enter', 'Space']
persistent	未激活且为 false 时是否销毁 Tooltip	boolean	true
aria-label	与 aria-label 属性保持一致	string	-
focus-on-target	hover 触发时是否聚焦触发元素以提升可访问性	boolean	false

Tooltip 事件

事件名	说明	类型
before-show	显示提示框之前触发	Function
show	显示提示框时触发	Function
before-hide	隐藏提示框之前触发	Function
hide	隐藏提示框时触发	Function

Tooltip 插槽

插槽名	说明
default	Tooltip 触发元素，只接受单个根元素
content	自定义内容

Tooltip 暴露

名称	说明	类型
popperRef	el-popper 组件实例	object
contentRef	el-tooltip-content 组件实例	object
isFocusInsideContent	判断当前焦点事件是否在 tooltip 内容中触发	Function
updatePopper	更新 el-popper 组件实例	Function
onOpen	打开 Tooltip	Function
onClose	关闭 Tooltip	Function
hide	隐藏 Tooltip	Function

FAQ

嵌套输入框时允许输入空格

Tooltip 默认可通过键盘按键触发。如果触发元素内嵌输入框并需要输入空格，可以把 trigger-keys 设置为空数组。

<el-tooltip content="tooltip content" placement="top" :trigger-keys="[]">
  <el-input v-model="value" />
</el-tooltip>