TechUI Docs

简中

EN

简中

EN

主题

气泡信息 ​

一种卡片式的气泡浮层，用于展示更丰富的信息或交互内容。相比于简单的文字提示，Popinfo 支持标题、图标、复杂的自定义内容（如表单、列表）以及多种视觉风格。

基础用法 ​

使用 <TuiPopinfo> 组件包裹触发元素。设置 title 即可显示标准头部，content 用于显示文本内容。

vue
<template>
  <div class="demo-box">
    <TuiPopinfo 
      title="标题信息" 
      content="这是一段详细的描述内容，可以包含较多文字。"
    >
      <TuiButton>组件触发</TuiButton>
    </TuiPopinfo>
    
    <TuiPopinfo 
      title="收藏夹" 
      titleIcon="tui-icon tis-star"
      content="已成功添加到您的收藏夹中。"
    >
      <TuiButton>带图标标题</TuiButton>
    </TuiPopinfo>
  </div>
</template>

指令调用 ​

通过 v-tui-popover 指令可以快速将气泡绑定到任意元素上。

注意：使用指令调用时，务必指定 appearance: 'popinfo' 以启用卡片样式。

vue
<template>
  <TuiButton 
    v-tui-popover="{ 
      appearance: 'popinfo',
      title: '指令调用', 
      titleIcon: 'tui-icon ti-info-circle',
      content: '通过指令生成的卡片气泡。',
      placement: 'right'
    }"
  >
    指令触发
  </TuiButton>
</template>

嵌入复杂组件 ​

Popinfo 的核心能力是承载复杂内容。您可以通过 插槽 (Slot) 或 组件属性 (Component Prop) 嵌入任意 Vue 组件。

方式一：使用 Slot (组件模式) ​

最直观的方式，适合在模板中直接编写。

vue
<script setup>
import ColorSelect from './ColorSelect.vue'
</script>

<template>
  <TuiPopinfo 
    title="颜色配置" 
    trigger="click" 
    :enterable="true"
  >
    <TuiButton>选择颜色</TuiButton>
    
    <template #content>
      <div style="padding: 10px;">
        <p style="margin-bottom: 10px;">请选择一种标记颜色：</p>
        <ColorSelect />
      </div>
    </template>
  </TuiPopinfo>
</template>

方式二：使用 Component 属性 (指令/函数模式) ​

当使用指令或函数调用时，可以将组件对象传给 component 属性。

vue
<script setup>
import { markRaw } from 'vue'
import ColorSelect from './ColorSelect.vue'

const popConfig = {
  appearance: 'popinfo',
  title: '动态组件',
  // 使用 markRaw 避免不必要的响应式性能开销
  component: markRaw(ColorSelect), 
  trigger: 'click',
  enterable: true
}
</script>

<template>
  <TuiButton v-tui-popover="popConfig">
    传入组件对象
  </TuiButton>
</template>

视觉风格 ​

Popinfo 深度集成了设计系统的色调功能。通过 type 定义语义色，配合 tone 控制色调强度，甚至可以开启磨砂玻璃效果。

vue
<template>
  <div class="style-demo">
    <TuiPopinfo 
      title="操作成功" 
      content="数据已保存到服务器。" 
      type="success" 
      tone="strong"
    >
      <TuiButton type="success">Success Strong</TuiButton>
    </TuiPopinfo>

    <TuiPopinfo 
      title="注意风险" 
      content="此操作不可逆，请谨慎操作。" 
      type="warning" 
      tone="strongInvert"
    >
      <TuiButton type="warning">Warning Invert</TuiButton>
    </TuiPopinfo>

    <TuiPopinfo 
      title="Glass Effect" 
      content="背景模糊的半透明效果。" 
      :transparent="true" 
      :backgroundBlur="true"
      tone="weak"
    >
      <TuiButton>磨砂风格</TuiButton>
    </TuiPopinfo>
  </div>
</template>

函数式调用 ​

在某些无法绑定 DOM 的场景（如 Canvas 绘图、异步回调）中，可以使用全局注入的 $tPopover 方法手动唤起气泡。

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

const $tPopover = inject('$tPopover')

const openManualPopover = (event) => {
  $tPopover({
    event: event, // 必须传入事件对象或目标 DOM，用于计算位置
    appearance: 'popinfo',
    title: '函数式调用',
    titleIcon: 'tui-icon ti-code',
    content: '这是一个通过 JS 动态创建的 Popinfo。',
    type: 'primary',
    trigger: 'click',
    showTrigger: true // 显示点击波纹动画
  })
}
</script>

<template>
  <div class="manual-trigger" @click="openManualPopover">
    点击此区域触发函数式 Popinfo
  </div>
</template>

API 参考 ​

Props ​

属性名说明类型可选值 (完整列表)默认值
title标题文本String——
titleIcon
V0.0.3+		标题左侧的图标 ClassString——
content内容文本 (若使用 slot 或 component 可不传)String——
component要渲染的自定义组件对象Object—null
placement弹出位置String'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end''top'
trigger触发方式String'hover', 'click''hover'
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'
enterable鼠标是否可进入气泡内部 (交互组件必开)Boolean—false
autoClose点击气泡外部是否自动关闭Boolean—true
transparent是否开启背景半透明Boolean—true
backgroundBlur是否开启背景模糊 (需配合 transparent)Boolean—true
disabled是否禁用Boolean—false
offset弹出的偏移距离 (px)Number—8
showArrow是否显示箭头Boolean—true
delay显示延迟 (ms)Number—500
duration自动关闭时间 (ms)，0 为常驻Number0 (常驻) 或具体毫秒数3000
hasShadow是否显示阴影Boolean—true

Slots (组件模式) ​

插槽名说明
default触发元素
content气泡主体内容区域，用于放置复杂 HTML 或组件

Global Methods ​

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

全局 ESC 监控 ​

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

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

定位依赖 ​

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

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

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

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