ExUI

Tooltip 文字提示 ​

简单的文字提示气泡框，鼠标悬停时显示。带有霓虹发光效果的赛博朋克主题提示组件。

基础用法 ​

最简单的用法，鼠标悬停时显示提示。

vue
<template>
  <ExTooltip content="这是一条提示信息">
    <ExButton>悬停显示</ExButton>
  </ExTooltip>
</template>

不同位置 ​

通过 placement 属性可以设置提示的显示位置，支持 12 个方向。

vue
<template>
  <ExTooltip content="Top" placement="top">
    <ExButton>上边</ExButton>
  </ExTooltip>
  
  <ExTooltip content="Bottom" placement="bottom">
    <ExButton>下边</ExButton>
  </ExTooltip>
  
  <ExTooltip content="Left" placement="left">
    <ExButton>左边</ExButton>
  </ExTooltip>
  
  <ExTooltip content="Right" placement="right">
    <ExButton>右边</ExButton>
  </ExTooltip>
</template>

不同主题 ​

通过 effect 属性可以设置不同的主题样式。

vue
<template>
  <ExTooltip content="深色主题提示" effect="dark">
    <ExButton>深色主题</ExButton>
  </ExTooltip>
  
  <ExTooltip content="浅色主题提示" effect="light">
    <ExButton>浅色主题</ExButton>
  </ExTooltip>
</template>

触发方式 ​

通过 trigger 属性可以设置不同的触发方式。

vue
<template>
  <ExTooltip content="鼠标悬停触发" trigger="hover">
    <ExButton>悬停触发</ExButton>
  </ExTooltip>
  
  <ExTooltip content="点击触发" trigger="click">
    <ExButton>点击触发</ExButton>
  </ExTooltip>
  
  <ExTooltip content="聚焦触发" trigger="focus">
    <ExButton>聚焦触发</ExButton>
  </ExTooltip>
</template>

延迟显示/隐藏 ​

通过 open-delay 和 close-delay 属性可以设置延迟时间。

vue
<template>
  <ExTooltip content="延迟 500ms 显示" :open-delay="500">
    <ExButton>延迟显示</ExButton>
  </ExTooltip>
  
  <ExTooltip content="延迟 500ms 隐藏" :close-delay="500">
    <ExButton>延迟隐藏</ExButton>
  </ExTooltip>
</template>

禁用状态 ​

通过 disabled 属性可以禁用提示。

vue
<template>
  <ExTooltip content="这是一条提示" :disabled="false">
    <ExButton>启用提示</ExButton>
  </ExTooltip>
  
  <ExTooltip content="这是一条提示" :disabled="true">
    <ExButton>禁用提示</ExButton>
  </ExTooltip>
</template>

手动控制 ​

通过 v-model 可以手动控制提示的显示和隐藏。

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

const visible = ref(false)
</script>

<template>
  <ExButton @click="visible = true">显示</ExButton>
  <ExButton @click="visible = false">隐藏</ExButton>
  
  <ExTooltip content="手动控制的提示" v-model="visible">
    <ExButton>目标元素</ExButton>
  </ExTooltip>
</template>

自定义内容 ​

通过 content 插槽可以自定义提示内容。

vue
<template>
  <ExTooltip>
    <template #content>
      <div>
        <div style="font-weight: bold;">自定义标题</div>
        <div>这是自定义的提示内容</div>
      </div>
    </template>
    <ExButton>自定义内容</ExButton>
  </ExTooltip>
</template>

赛博朋克主题示例 ​

展示赛博朋克场景中的提示应用。

vue
<template>
  <ExTooltip placement="top">
    <template #content>
      <div>
        <div style="font-weight: bold;">⚔️ 传说之剑</div>
        <div>攻击力: +150</div>
        <div>暴击率: +25%</div>
        <div>稀有度: 传说</div>
      </div>
    </template>
    <ExButton type="primary">武器</ExButton>
  </ExTooltip>
</template>

API ​

Tooltip Props ​

参数说明类型默认值
content显示的内容string—
placement出现位置'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end''top'
trigger触发方式'hover' | 'click' | 'focus' | 'hover-focus''hover'
effect主题'dark' | 'light''dark'
show-arrow是否显示箭头booleantrue
disabled是否禁用booleanfalse
offset偏移量（像素）number12
transition过渡动画名称string'ex-tooltip-fade'
open-delay延迟显示（毫秒）number0
close-delay延迟隐藏（毫秒）number200
custom-class自定义类名string—
z-index层级number2000
v-model手动控制显示boolean—
aria-label无障碍标签string—

Tooltip Events ​

事件名说明类型
show显示时触发() => void
hide隐藏时触发() => void

Tooltip Slots ​

插槽名说明
default触发元素
content自定义提示内容

Tooltip Methods ​

方法名说明类型
show显示提示() => void
hide隐藏提示() => void
updatePosition更新位置() => void

无障碍支持 ​

  • 使用 role="tooltip" 标记提示内容
  • 完整的 ARIA 属性支持
  • 支持键盘导航（focus 触发）
  • 支持屏幕阅读器

受控 / 非受控 ​

默认由 trigger（hover / click / focus / hover-focus）非受控地控制显隐。也可用 v-model 手动控制：

vue
<template>
  <ExTooltip v-model="show" content="手动控制的提示">
    <ExButton>目标元素</ExButton>
  </ExTooltip>
  <ExButton @click="show = !show">切换</ExButton>
</template>

<script setup>
import { ref } from 'vue'
const show = ref(false)
</script>

常见问题 ​

Q：trigger="focus" 不生效？ 已修复。组件监听 focusin/focusout（会冒泡），聚焦插槽内的可聚焦元素（如 <button>、<input>）即可触发。请确保触发元素本身可获得焦点。

Q：提示被遮挡或超出屏幕边缘？ 内置主轴翻转（flip）与视口夹取：当前方向空间不足时自动翻到对侧，并在边缘处收拢，无需手动处理。

Q：移动端没有 hover 怎么办？ 触屏设备没有 hover，请改用 trigger="click"。

Q：需要在提示里放按钮 / 表单？ Tooltip 仅用于简短文字。承载可交互的复杂内容请用 Popover。

最佳实践 ​

  • 只放简短说明文字；复杂或可交互内容用 Popover。
  • 触发元素应可聚焦（<button>、<a> 或加 tabindex），以同时支持鼠标、键盘与读屏。
  • 触屏/移动端改用 click 触发。
  • 用 open-delay / close-delay 避免快速划过时提示闪烁。

主题定制 ​

Tooltip 不定义独立的组件级变量，深浅样式由 effect="dark" | "light" 切换。定制方式：

  • 单个实例：用 custom-class 添加类名后覆盖 .ex-tooltip__popper 的背景与文字色。
  • 全局：覆盖其消费的全局令牌：
css
:root {
  --ex-color-text-primary: #e6f1ff;   /* 文字色 */
  --ex-color-border-primary: #1f2a37; /* 边框 */
  --ex-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.5); /* 投影 */
}