TechUI Docs

简中

EN

简中

EN

主题

气泡提示 ​

Poptip 是一个轻量级的文字提示组件，主要用于解释界面元素（如按钮、文字）的含义或提供简短的辅助信息。与 Popinfo 相比，它的体积更小，不包含标题，视觉风格更为紧凑，且交互逻辑更偏向于“即指即显”。

基础用法 ​

组件调用 ​

最标准的使用方式，将 <TuiPoptip> 包裹在触发元素外。content 属性用于定义提示内容。

vue
<template>
  <div class="demo-box">
    <TuiPoptip content="这是一个基础提示">
      <TuiButton>Hover Me</TuiButton>
    </TuiPoptip>

    <TuiPoptip 
      content="Danger Type / Bottom" 
      type="danger" 
      placement="bottom"
    >
      <TuiButton type="danger">删除</TuiButton>
    </TuiPoptip>
  </div>
</template>

指令调用 ​

通过 v-tui-popover 指令可以减少层级嵌套，直接将提示绑定到目标元素上。

提示：指令调用的默认 appearance 即为 'poptip'，因此无需像 Popinfo 那样显式指定外观。

vue
<template>
  <TuiButton 
    v-tui-popover="{ 
      content: '通过指令显示的 Poptip', 
      placement: 'right',
      type: 'primary' 
    }"
  >
    指令触发
  </TuiButton>
</template>

视觉风格 ​

Poptip 支持与 Popinfo 同样丰富的色彩与色调组合，以适应各种背景深度和语义场景。

Type 语义色与 Tone 色调 ​

通过 type 定义语义颜色，配合 tone 控制色调强度。

vue
<template>
  <div class="row">
    <TuiPoptip content="Primary Type" type="primary">
      <TuiButton type="primary">Primary</TuiButton>
    </TuiPoptip>

    <TuiPoptip content="Strong Tone" type="success" tone="strong">
      <TuiButton type="success">Success Strong</TuiButton>
    </TuiPoptip>
    
    <TuiPoptip content="Invert Tone" type="warning" tone="strongInvert">
      <TuiButton type="warning">Warning Invert</TuiButton>
    </TuiPoptip>
  </div>
</template>

磨砂玻璃效果 ​

开启 transparent 和 backgroundBlur 可实现背景模糊的半透明效果，通常配合 tone="weak" 使用效果最佳，能呈现出精致的视觉质感。

vue
<template>
  <TuiPoptip 
    content="Glass Effect Poptip" 
    :transparent="true" 
    :backgroundBlur="true"
    tone="weak"
  >
    <TuiButton>磨砂效果</TuiButton>
  </TuiPoptip>
</template>

函数式调用 ​

在某些无法绑定 DOM 的场景（如 Canvas 绘图区域、图表内部元素交互、异步操作反馈）中，可以使用全局注入的 $tPopover 方法手动唤起提示。

vue
<script setup>
import { inject } from 'vue'

const $tPopover = inject('$tPopover')

const openManualPoptip = (event) => {
  $tPopover({
    event: event, // 必须传入事件对象或目标 DOM，用于计算位置
    // appearance: 'poptip', // 默认为 poptip，可省略
    content: '这是一个通过 JS 动态调用的 Poptip',
    type: 'info',
    trigger: 'click', // 函数调用通常配合 click 或手动逻辑
    showTrigger: true // 显示点击波纹动画
  })
}
</script>

<template>
  <div class="manual-area" @click="openManualPoptip">
    点击此区域触发函数式 Poptip
  </div>
</template>

API 参考 ​

Props ​

属性名说明类型可选值 (完整列表)默认值
content提示内容String——
placement弹出位置String'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end''top'
type语义类型String'default', 'invert', 'primary', 'success', 'warning', 'danger', 'info', 'emphasis'null
tone色调强度String'base', 'weak', 'strong', 'strongInvert', 'extremeInvert''base'
shadowColor阴影强度String'weakest', 'weaker', 'weak', 'base', 'strong', 'stronger', 'strongest', 'match''weak'
trigger触发方式String'hover', 'click''hover'
appearance外观模式 (指令/函数调用时)String'poptip', 'popinfo''poptip'
offset偏移距离 (px)Number—8
showArrow是否显示箭头Boolean—true
enterable鼠标是否可进入提示内部Boolean—false
autoClose点击外部是否自动关闭Boolean—true
transparent是否开启背景半透明Boolean—true
backgroundBlur是否开启背景模糊Boolean—true
disabled是否禁用Boolean—false
delay显示延迟 (ms)Number—500
duration自动关闭时间 (ms)，0 为常驻Number0 (常驻) 或具体毫秒数3000
hasShadow是否显示阴影Boolean—true

Slots (组件模式) ​

插槽名说明
default触发提示的目标元素

Global Methods ​

方法名说明参数
$tPopover创建一个 Poptip 实例(options: Object) => void
$tPopoverCloseAll关闭所有 JS/事件创建的实例() => void
$tPopoverDirectiveCloseAll关闭所有指令创建的实例() => void

全局 ESC 监控 ​

为了提供统一且优雅的键盘交互体验，所有浮动组件深度集成了 TechUI 的全局服务（TuiService）。

组件内部会实时监听全局的 EscCounter 参数。当用户按下 Esc 键时，全局服务会更新该计数器，组件捕获到这一变化后，会自动触发隐藏逻辑。这种机制确保了无论页面中有多少个独立的浮层，都能响应统一的关闭指令，无需开发者手动绑定键盘事件。

定位依赖 ​

TechUI 的气泡与弹层组件底层完全依赖于业界成熟的 Floating UI 库进行锚点定位计算。

这意味着您无需担心复杂的几何计算，组件能够自动处理以下场景：

  • 碰撞检测 (Flip)：当预设位置空间不足时（如屏幕边缘），自动翻转到对面位置。
  • 视口修正 (Shift)：确保气泡始终保持在视口可见范围内，不会被截断。
  • 精准偏移：通过 offset 属性实现像素级的精确定位。

您只需通过组件的 placement 属性指定期望方位，剩下的复杂计算均由底层引擎自动完成。