Tooltip 文字提示

用于解释图标、按钮或截断文本。

何时使用

• 需要在鼠标悬停、键盘聚焦或点击时展示短文本说明。
• 说明内容较短，不承载复杂结构或操作。
• 复杂卡片、标题和操作按钮请优先使用 Popover 气泡卡片。

基础用法

<template>
  <x-tooltip content="这是一段提示内容">
    <x-button>悬浮查看</x-button>
  </x-tooltip>

  <x-tooltip content="键盘聚焦也可查看" :trigger="['hover', 'focus']">
    <x-button>聚焦查看</x-button>
  </x-tooltip>
</template>

弹出位置

<template>
  <x-tooltip content="上方" position="top">
    <x-button>Top</x-button>
  </x-tooltip>
  <x-tooltip content="右侧" position="right">
    <x-button>Right</x-button>
  </x-tooltip>
</template>

迷你尺寸和颜色

<template>
  <x-tooltip content="1234" mini>
    <x-button>迷你尺寸</x-button>
  </x-tooltip>

  <x-tooltip content="蓝色提示" background-color="#165dff">
    <x-button>蓝色</x-button>
  </x-tooltip>
</template>

禁用和空内容

<template>
  <x-tooltip content="禁用后不会展示" disabled>
    <x-button>禁用提示</x-button>
  </x-tooltip>

  <x-tooltip content="需要管理员权限">
    <x-button disabled>禁用按钮提示</x-button>
  </x-tooltip>

  <x-tooltip>
    <x-button>空内容不展示</x-button>
  </x-tooltip>

  <x-tooltip :content="0">
    <x-button>数字 0</x-button>
  </x-tooltip>
</template>

受控显隐和事件

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(false);
</script>

<template>
  <x-button @click="visible = !visible">切换显隐</x-button>
  <x-tooltip
    v-model:popup-visible="visible"
    trigger="click"
    content="受控 Tooltip"
    @popup-visible-change="(nextVisible) => console.log(nextVisible)"
  >
    <x-button>点击触发</x-button>
  </x-tooltip>
</template>

自定义内容

<template>
  <x-tooltip>
    <x-button>查看状态</x-button>
    <template #content>
      <div>
        <strong>构建完成</strong>
        <span>耗时 12.4s，产物已更新。</span>
      </div>
    </template>
  </x-tooltip>
</template>

更多触发能力

<script setup lang="ts">
import { ref } from 'vue';

const visible = ref(false);
</script>

<template>
  <x-tooltip content="没有箭头" :show-arrow="false">
    <x-button>隐藏箭头</x-button>
  </x-tooltip>

  <x-tooltip v-model:popup-visible="visible" trigger="contextMenu" align-point content="跟随右键位置">
    <x-button>右键触发</x-button>
  </x-tooltip>
</template>

按需导入

import { Tooltip } from 'x-next';

导出项

名称	说明
Tooltip	主组件

Props

参数	说明	类型	默认值
popupVisible	气泡是否可见，受控模式，支持 v-model:popup-visible	boolean	-
defaultPopupVisible	默认是否可见，非受控模式	boolean	false
trigger	触发方式	'hover' | 'click' | 'focus' | 'contextMenu' | Array	'hover'
disabled	是否禁用 Tooltip	boolean	false
content	提示内容	string | number	-
position	弹出位置	'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br' | 'left' | 'lt' | 'lb' | 'right' | 'rt' | 'rb'	'top'
mini	是否展示为迷你尺寸	boolean	false
backgroundColor	气泡与箭头背景色	string	-
contentClass	气泡内容类名	string | any[] | Record<string, any>	-
contentStyle	气泡内容样式	CSSProperties	-
arrowClass	箭头类名	string | any[] | Record<string, any>	-
arrowStyle	箭头样式	CSSProperties	-
popupContainer	弹层挂载容器	string | HTMLElement	-
popupOffset	弹层偏移距离	number	10
popupTranslate	弹层移动距离	[number, number] | object	-
showArrow	是否展示箭头	boolean	true
alignPoint	是否跟随鼠标位置，常用于右键菜单	boolean	false
popupStyle	弹层定位节点样式	CSSProperties	-
animationName	弹出动画名称	string	'x-zoom-in-fade-out'
duration	动画持续时间	number | { enter: number; leave: number }	-
mouseEnterDelay	鼠标移入延迟，单位毫秒	number	100
mouseLeaveDelay	鼠标移出延迟，单位毫秒	number	100
focusDelay	聚焦延迟，单位毫秒	number	0
popupHoverStay	hover 触发时移入浮层是否保持显示	boolean	true
blurToClose	focus 触发时失焦是否关闭	boolean	true
clickToClose	点击触发器时是否允许关闭	boolean	true
clickOutsideToClose	点击外部是否关闭	boolean	true
unmountOnClose	关闭时是否卸载弹层节点	boolean	true
autoFitPopupWidth	是否将弹层宽度设为触发器宽度	boolean	false
autoFitPopupMinWidth	是否将弹层最小宽度设为触发器宽度	boolean	false
autoFixPosition	触发器尺寸变化时是否重新定位	boolean	true
updateAtScroll	容器滚动时是否更新弹层位置	boolean	false
autoFitPosition	是否自动调整位置适配视口	boolean	true
renderToBody	是否挂载到 body	boolean	true
preventFocus	点击弹层元素时是否阻止获取焦点	boolean	false
scrollToClose	滚动时是否关闭	boolean	false
scrollToCloseDistance	滚动关闭阈值	number	0
openedClass	打开时给触发元素添加的类名	string | any[] | Record<string, any>	-

Events

事件名	说明	回调参数
update:popupVisible	显隐状态变化时触发，用于 v-model:popup-visible	visible: boolean
popup-visible-change	显隐状态变化时触发	visible: boolean
show	显示动画结束后触发	-
hide	隐藏动画结束后触发	-
resize	内部尺寸变化时触发	-

Slots

插槽名	说明
default	触发提示的元素
content	自定义提示内容，优先级高于 content prop