跟随提示

👑首创

CursorTip 是一种特殊的提示组件，它的位置不固定于某个 DOM 元素，而是实时跟随鼠标光标移动。它结合了 Poptip 的轻量和 Popinfo 的丰富性，既可以展示简单的文本，也可以包含标题和语义色。

此类组件常用于需要用户实时查看状态、属性或进行探索性交互（Explore）的场景。

基础用法

组件调用

将 <TuiCursorTip> 包裹在触发区域外。当鼠标在该区域内移动时，提示框会跟随光标显示。

vue

<template>
  <div class="demo-box">
    <TuiCursorTip content="跟随鼠标移动的文本">
      <div class="hover-area">移动到此处</div>
    </TuiCursorTip>

    <TuiCursorTip 
      title="详细信息" 
      content="这里显示更具体的描述内容..."
    >
      <div class="hover-area">查看详情</div>
    </TuiCursorTip>
  </div>
</template>

指令调用 (v-tui-cursor-tip)

使用指令可以更便捷地为元素添加跟随提示。

vue

<template>
  <div 
    v-tui-cursor-tip="{ 
      title: '指令提示', 
      content: '通过 v-tui-cursor-tip 生成', 
      placement: 'top-end' 
    }" 
    class="hover-area"
  >
    指令触发区域
  </div>
</template>

视觉风格

与 Popover 系列组件一致，支持丰富的语义色和色调配置，以及磨砂玻璃效果。

vue

<template>
  <div class="row">
    <TuiCursorTip 
      content="删除操作不可恢复" 
      title="警告" 
      type="danger" 
    >
      <TuiButton type="danger">Danger Zone</TuiButton>
    </TuiCursorTip>

    <TuiCursorTip 
      content="背景模糊效果" 
      :transparent="true" 
      :backgroundBlur="true" 
      tone="weak"
    >
      <div class="glass-area">Glass Effect</div>
    </TuiCursorTip>
  </div>
</template>

几何配置

由于提示框紧贴鼠标，为了避免遮挡用户的视线或操作焦点，可以通过 caretSize 和 caretOffset 微调其与光标的距离。

caretSize: 控制提示框箭头的尺寸。
caretOffset: 控制提示框相对于鼠标光标的偏移距离。

vue

<template>
  <TuiCursorTip 
    content="距离光标更远一点" 
    :caretSize="8" 
    :caretOffset="10"
  >
    <div class="area">大偏移量</div>
  </TuiCursorTip>
</template>

全局交互监控

为了提供流畅的体验，CursorTip 集成了全局交互服务：

ESC 响应 (escCounter)：当用户按下 Esc 键时，即使鼠标仍在触发区域内，当前的跟随提示也会被强制隐藏，直到鼠标移出并再次进入区域。
注意：与常规 Poptip 不同，跟随提示不支持“点击关闭”或“点击外部关闭”逻辑，因为其生命周期完全依赖于鼠标的悬停状态。

API 参考

Props

这里筛选了适用于跟随提示的配置项。

属性名	说明	类型	默认值
content	提示内容	`String`	—
title	标题文本 (可选)	`String`	—
placement	相对光标的方位 (如 `top-start`, `bottom-end` 等)	`String`	`'bottom-end'`
type	语义类型 (`primary`, `success`, `danger`, `warning` 等)	`String`	`null`
tone	色调强度 (`base`, `weak`, `strong`, `strongInvert`)	`String`	`'base'`
caretSize	箭头尺寸 (px)	`Number`	`5`
caretOffset	距离光标的偏移量 (px)	`Number`	`2`
delay	显示延迟 (ms)	`Number`	`100`
transparent	是否开启背景半透明	`Boolean`	`true`
backgroundBlur	是否开启背景模糊	`Boolean`	`true`
disabled	是否禁用	`Boolean`	`false`
zIndex	层级	`Number`	`2000`

Directives

指令名	说明	参数
v-tui-cursor-tip	绑定跟随提示配置对象	`Object` (Props 配置)

定位核心 Floating UI

CursorTip 的定位机制同样基于 Floating UI，但采用了特殊的 Virtual Element 技术。

组件会实时捕获鼠标的 MouseEvent 坐标，将其转换为一个宽高为 0 的虚拟元素（Virtual Element），并将其作为 Floating UI 的锚点。这使得提示框能够像吸附在 DOM 元素上一样吸附在移动的光标旁，同时保留了 Floating UI 强大的边缘检测 (Flip) 和 视口修正 (Shift) 能力——当光标靠近屏幕边缘时，提示框会自动调整方向，确保内容永远不会被挤出屏幕可视范围。

跟随提示 ​

基础用法 ​

组件调用 ​

指令调用 (v-tui-cursor-tip) ​

视觉风格 ​

几何配置 ​

全局交互监控 ​

API 参考 ​

Props ​

Directives ​

定位核心 Floating UI ​