Tooltip 文字提示
极轻量、高性能的文字提示组件。基于业内顶级的 Floating UI 定位引擎驱动。
基础用法
提供 12 个方向的弹出位置，通过 placement 属性配置。
基础用法
多种主题
除了内置的 dark / light 主题外，你还可以通过自定义 effect 的值来轻松定义专属主题样式。
主题风格
自定义主题
通过设置 effect="customized" 并编写对应的 CSS，可以获得极致的视觉效果。
自定义主题
尺寸与样式
支持自定义宽度、最大高度，并支持长内容滚动。
尺寸与自由样式
显示 HTML 内容
内容属性可以设置为 HTML 字符串，通过 raw-content 开启。
HTML 渲染
触发行为
支持悬停、点击、焦点以及右键菜单触发，默认为 hover。
触发方式
高级特性
鼠标跟随 (Follow Cursor)
体验鼠标跟随效果
鼠标跟随
内容交互 (Interactive)
允许交互
在 Nuxt 中使用
YH-UI 完美兼容 Nuxt 3。你可以直接在组件中使用，无需手动导入。
Nuxt 3 支持
FAQ
如何在嵌套了 Tooltip 的情况下允许输入框输入空格？
当 Tooltip 包含一个输入框时，在 YH-UI 中，我们确保了交互逻辑不会干扰正常的输入行为。你可以直接在触发层嵌套输入框，空格键将正常工作。
嵌套输入框示例
如何在 Tooltip 中使用跳转链接？
你可以通过 content 插槽在 Tooltip 内部嵌入复杂的交互元素。请确保开启了 interactive 属性。
嵌入外部链接
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 显示文字内容 | string | - |
| placement | 弹出位置 | TooltipPlacement | 'top' |
| trigger | 触发方式 | TooltipTrigger | TooltipTrigger[] | 'hover' |
| disabled | 是否禁用 | boolean | false |
| effect | 主题风格 | string | 'dark' |
| offset | 偏移量 [横向, 纵向] | [number, number] | [0, 8] |
| show-after | 出现延迟 (ms) | number | 0 |
| hide-after | 消失延迟 (ms) | number | 200 |
| show-arrow | 是否显示小三角 | boolean | true |
| interactive | 是否允许鼠标进入提示框 | boolean | true |
| visible | 手动控制可见性 | boolean | null | null |
| raw-content | 是否将 content 作为 HTML 字符串渲染 | boolean | false |
| follow-cursor | 是否跟随鼠标移动 | boolean | false |
| persistent | 隐藏时是否保留弹层 DOM。为 false 时仅在显示时渲染 | boolean | true |
| width | 弹出层宽度 | string | number | 'auto' |
| max-height | 最大高度 | string | number | 'none' |
| scrollable | 内容是否可滚动 | boolean | false |
| popper-class | 弹出层自定义类名 | string | - |
| popper-style | 弹出层自定义样式。当前仅对象样式会在运行时被合并；字符串和数组形式虽已声明但未被消费 | StyleValue | {} |
| content-class | 内容层自定义类名 | string | - |
| content-style | 内容层自定义样式。当前仅对象样式会被运行时合并 | StyleValue | {} |
| arrow-class | 已声明的箭头类名属性，当前模板未消费 | string | '' |
| arrow-style | 已声明的箭头样式属性，当前模板未消费 | StyleValue | {} |
| arrow-wrapper-class | 已声明的箭头容器类名属性，当前模板未消费 | string | '' |
| arrow-wrapper-style | 已声明的箭头容器样式属性，当前模板未消费 | StyleValue | {} |
| z-index | 层级 | number | 2000 |
| transition | 动画名称 | string | 'yh-tooltip-fade' |
| teleported | 是否挂载至 body | boolean | true |
Slots
| 插槽名 | 说明 |
|---|---|
| default | 触发元素 |
| content | 自定义内容 (覆盖 content 属性) |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| show | 提示框显示时触发 | - |
| hide | 提示框隐藏时触发 | - |
| update:visible | 状态改变时触发 | (visible: boolean) |
主题变量 (CSS Variables)
YhTooltip 当前直接消费以下组件级 CSS 变量：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-tooltip-bg | Tooltip 背景色 | var(--yh-bg-color-overlay) |
--yh-tooltip-border | Tooltip 边框色 | var(--yh-border-color-light) |
--yh-tooltip-text | Tooltip 文字颜色 | var(--yh-text-color-primary) |
其余层级、字号、圆角和阴影继续复用全局主题令牌，例如 --yh-z-index-tooltip、--yh-font-size-sm、--yh-radius-md、--yh-shadow-lg。
暗黑模式
当 html.dark 或使用 effect="dark" 时，Tooltip 会自动切换为深色主题变量：
--yh-tooltip-bg:var(--yh-bg-color-overlay-dark)--yh-tooltip-text:var(--yh-text-color-primary-dark)
Expose
| 名称 | 说明 | 类型 |
|---|---|---|
updatePosition | 手动更新浮层定位。 | () => Promise<void> | void |
visible | 当前显示状态引用。 | Ref<boolean> |
triggerRef | 触发元素引用。 | Ref<HTMLElement | null> |
popperRef | 浮层元素引用。 | Ref<HTMLElement | null> |
类型导出
| 名称 | 说明 |
|---|---|
YhTooltipProps | 组件 Props 类型 |
YhTooltipEmits | 组件事件类型 |
YhTooltipSlots | 组件插槽类型 |
YhTooltipExpose | 组件 Expose 类型 |
YhTooltipPlacement | 弹出位置联合类型 |
YhTooltipTrigger | 触发方式联合类型 |
YhTooltipInstance | 组件实例类型 |