Tooltip 文字提示

常用于展示鼠标 hover 时的提示信息。

何时使用

• 鼠标移入则显示提示，移出消失，气泡浮层不承载复杂文本和操作
• 可用来代替系统默认的 title 提示，提供一个更好的用户体验
• 当某个页面元素需要解释或描述时

基本使用

最简单的用法，浮层的大小由内容区域决定。文本内容可通过 content 或同名 slot 传入。

12 个出现位置

通过 placement 控制方位。

内置主题

effect 提供 dark / light 两套内置背景；要更精细的颜色用 color。

自定义背景色 color

color 优先于 effect，接受任意 CSS color，常用于品牌色 / 警告色提示。

显隐箭头 show-arrow

通过 show-arrow 控制箭头显示/隐藏。

多行 / HTML 内容

#content slot 支持任意 VNode；要把字符串当 HTML 渲染用 rawContent。

触发方式

hover / click / focus / manual 四种。

延迟显示 / 隐藏

通过 show-after / hide-after 控制显隐延迟（ms）。

禁用

disabled=true 时永远不触发显示。

受控显示 v-model:visible

visible 配合 v-model:visible 双向同步。

show / hide 事件追踪

before-show / show / before-hide / hide 四个事件覆盖完整生命周期，常用于埋点。

业务场景：图标提示

「图标 + Tooltip 文字解释」是后台管理表单 / 配置项最常见的辅助说明范式。

API

Tooltip Props

参数	说明	类型	默认值
content	浮层显示文本。也可用同名 content slot 传入富文本	string	—
visible / v-model:visible	受控显示状态	boolean	false
placement	出现位置（12 种）	'top' | 'top-start' | ... | 'right-end'	bottom
effect	内置主题	'dark' | 'light'	dark
color	自定义背景色（覆盖 effect）	string	—
show-arrow	是否显示箭头	boolean	true
show-after	鼠标进入触发显示的延迟（ms）	number	0
hide-after	鼠标离开触发隐藏的延迟（ms）	number	200
popper-class	浮层根节点 class	string	—
trigger	触发方式	'hover' | 'focus' | 'click' | 'manual'	hover
disabled	是否禁用	boolean	false
offset	距触发器的偏移量（px）	number	8
enterable	鼠标是否可进入到 tooltip 中	boolean	true
raw-content	是否将 content 作为 HTML 字符串处理	boolean	false
fresh	关闭后是否销毁内部内容	boolean	false
destroyTooltipOnHide	隐藏时销毁 tooltip 节点	boolean	false
autoAdjustOverflow	自动调整方向避免溢出（接 floating-ui flip）	boolean	true
align	floating-ui offset / flip 等微调参数	object	—
getPopupContainer	自定义弹层容器（返回 null 不 Teleport）	(trigger) => HTMLElement | null	—
aria-label	屏幕阅读器标签	string	—

Tooltip Events

事件名	说明	回调参数
before-show	显示前触发	—
show	显示时触发	—
before-hide	隐藏前触发	—
hide	隐藏时触发	—
update:visible	v-model:visible 同步	visible

Tooltip Slots

插槽名	说明
default	Tooltip 触发 & 引用的元素
content	自定义浮层内容（优先于 content prop）