V Design

Components · 通用组件

Fluid Tooltip ​

一组触发器共用的流体提示浮层。在图标之间移动时，提示框的位置、尺寸和文字方向连续变化。

Overview ​

普通 Tooltip 通常为每个触发器分别创建浮层。Fluid Tooltip 在同一组中只保留一个浮层，因此连续浏览工具栏时不会反复消失和出现。

Demo ​

Code ​

vue
<script setup lang="ts">
import { House } from '@lucide/vue'
import {
  FluidTooltipGroup,
  FluidTooltipTrigger,
} from '@/library/web/components/fluid-tooltip'
</script>

<template>
  <FluidTooltipGroup
    orientation="horizontal"
    :open-delay="350"
    :close-delay="100"
  >
    <FluidTooltipTrigger id="home" content="Home" aria-label="Home">
      <House aria-hidden="true" />
    </FluidTooltipTrigger>
  </FluidTooltipGroup>
</template>

API ​

FluidTooltipGroup ​

PropTypeDefaultDescription
orientationauto | horizontal | verticalauto判断内容切换方向的轴线
openDelaynumber350首次打开前的等待时间，单位毫秒
closeDelaynumber100离开后的关闭缓冲，单位毫秒
disabledbooleanfalse禁用整组提示

FluidTooltipTrigger ​

PropTypeDefaultDescription
idstringrequired组内唯一标识
contentstringrequired简短、非交互式提示文本
asstring | Componentbutton触发元素
placementtop | right | bottom | leftgroup default首选出现方向
offsetnumber8浮层与触发器的距离
showArrowbooleantrue是否显示箭头
disabledbooleanfalse禁用单个触发器

其余 HTML attributes 会透传给触发元素。

Behavior ​

  • 鼠标悬停或键盘聚焦后显示提示。
  • 首次打开遵守 openDelay，同组触发器之间切换不重复等待。
  • 位置和尺寸变化共用同一个浮层，文字按移动方向切换。
  • 浮层接近视口边缘时自动翻转或偏移。
  • Escape 关闭当前提示。
  • 系统启用减少动画时，移除位移与缩放效果。

Notes ​

  • Tooltip 只用于补充短文本，不应放置按钮、输入框或链接。
  • 触摸设备不触发 hover 行为；关键说明不能只存在于 Tooltip 中。
  • 浮层通过 Teleport 渲染到 body，避免父级 overflow 和 stacking context 截断。
  • 默认视觉由 --vd-tooltip-* CSS Variables 控制，具体项目可以通过 Project Design 覆盖。
  • 交互灵感来自 Sona UI Fluid Tooltip。原实现基于 React，本页面是独立的 Vue 3 适配；Sona UI 使用 MIT 许可证。