文本溢出提示

⭐明星组件

TextTip 专为文本展示设计的智能组件。当文本内容超出容器宽度或指定行数时，自动显示省略号，并在鼠标悬停时通过 Poptip (气泡) 或 CursorTip (跟随提示) 展示完整内容。

相比于原生的 title 属性，它提供了更丰富的视觉风格、更智能的定位以及多行截断支持。

基础用法 单行截断

默认情况下，TuiTextTip 会将文本限制为单行显示。当文本超出父容器宽度时，会自动截断并显示省略号。悬停 1秒 (默认延迟) 后显示完整内容。

<template>
  <div style="width: 200px;">
    <TuiTextTip>
      这是一个非常长的文本，用于测试单行溢出的情况，悬停查看更多。
    </TuiTextTip>
  </div>
</template>

多行截断

通过 lines 属性可以指定文本显示的最大行数。组件会自动应用多行省略样式。

<template>
  <div style="width: 300px;">
    <TuiTextTip :lines="3">
      这是一个用于测试的中文文本。我们希望这段文本能够包含各种常见的汉字、标点符号以及数字，以确保在不同的显示环境下都能正确显示。同时，我们也希望这段文本能够有一定的长度，以便测试文本的自动换行和滚动效果。
    </TuiTextTip>
  </div>
</template>

提示外观

组件复用了 Poptip 和 CursorTip 的底层能力，可以通过 appearance 属性在两种交互模式间切换。

• poptip (默认): 固定位置的气泡提示，通常位于文本下方或上方。
• curtip: 跟随鼠标光标移动的提示，适合阅读长段落时的探索性交互。

<script setup>
import { reactive } from 'vue'
const config = reactive({
  mode: 'poptip'
})
</script>

<template>
  <TuiTextTip appearance="poptip" placement="bottom">
    常规 Poptip 模式，位置固定。
  </TuiTextTip>

  <TuiTextTip appearance="curtip" placement="bottom-end">
    Curtip 模式，提示框会跟随鼠标移动，体验更灵动。
  </TuiTextTip>
</template>

视觉风格

支持与 Poptip 一致的 type (语义色)、tone (色调) 以及磨砂玻璃效果配置。

提示: 默认的 delay 设置为 1000ms，这是为了防止用户快速划过列表时频繁触发弹窗，减少视觉干扰。

<template>
  <TuiTextTip 
    type="invert" 
    tone="strong" 
    :transparent="true" 
    :backgroundBlur="true"
  >
    这是一段重要的文本信息...
  </TuiTextTip>

  <TuiTextTip type="danger">
    错误日志信息：NullPointerExce...
  </TuiTextTip>
</template>

API 参考

Props

属性名	说明	类型	默认值
lines	文本显示行数。null 或 1 为单行截断，大于 1 为多行截断	Number	null
appearance	提示外观模式，可选 'poptip', 'curtip'	String	'poptip'
delay	显示延迟 (ms)。默认为 1秒，避免频繁闪烁	Number	1000
type	语义类型，可选 'default', 'invert', 'primary', 'danger' 等	String	'invert'
tone	色调强度，可选 'base', 'weak', 'strong', 'strongInvert' 等	String	'base'
placement	弹出位置。Poptip 默认为 bottom，Curtip 默认为 bottom-start	String	—
maxWidth	提示框的最大宽度 (px)	Number	—
offset	提示框偏移量 (px)	Number	—
transparent	是否开启背景半透明	Boolean	true
backgroundBlur	是否开启背景模糊	Boolean	true
fadeAni	是否开启淡入淡出动画	Boolean	false

Slots

插槽名	说明
default	需要展示的文本内容

全局交互与定位

由于 TuiTextTip 内部封装了 Poptip 和 CursorTip，它完整继承了这两个组件的底层特性：

• 全局 ESC 监控：组件受 TechUI 全局服务管控。当用户按下 Esc 键时，当前显示的文本提示框会被立即销毁，提供一致的快捷关闭体验。
• 智能定位 (Floating UI)：提示框的定位逻辑完全基于 Floating UI。无论文本处于页面边缘还是复杂的滚动容器中，组件都能自动进行碰撞检测和位置修正，确保提示内容永远不会被视口截断。