Tooltip 文字提示

悬停或聚焦时显示的补充说明。十二种方位，自动翻转。

基础用法

<SrTooltip content="这是提示内容">
  <SrButton>悬停查看</SrButton>
</SrTooltip>

触发器由默认插槽提供，组件会给它加上事件监听与 ARIA 属性。

十二种方位

<SrTooltip content="上方居中" placement="top" />
<SrTooltip content="左上对齐" placement="top-start" />
<SrTooltip content="左下对齐" placement="top-end" />

-start 与 -end 表示沿主轴的对齐方式。以 top 为例： top-start 是提示框左边缘与触发器左边缘对齐，top-end 则右对齐。

空间不足时自动翻转

这是 Tooltip 最容易出问题的地方。

靠近视口顶部时，placement="top" 的提示框会被裁掉。 组件会检测可用空间并自动翻到下方——而不是让用户看不到内容。

翻转为什么是必需的

Tooltip 的内容只在悬停时可见。若被裁掉，用户悬停了、 什么都没看到、移开、再悬停——没有任何线索告诉他是"位置不对"。

这类"功能静默失效"最难被发现。宁可翻转到不那么理想的位置， 也不能什么都不显示。

延迟控制

showDelay / hideDelay 控制显示与隐藏的延时。

<SrTooltip content="立即显示" :show-delay="0" />
<SrTooltip content="等 600ms" :show-delay="600" :hide-delay="100" />

移动端建议关掉 Tooltip

触摸屏上没有悬停——用户"点一下"才可能触发， 而点击通常已经有别的含义了。

移动端常见做法是把提示内容直接写在界面上， 或用可点开的 SrPopover 这类组件替代。

箭头与宽度

<SrTooltip content="没有箭头" :arrow="false" />
<SrTooltip content="很长的内容…" max-width="200px" />

没有 maxWidth 时长文本会撑成很长的一行，既难读，也可能超出屏幕。

手动控制

v-model 可以直接控制显隐。

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

<template>
  <SrTooltip v-model="visible" content="手动控制">
    <SrButton>触发器</SrButton>
  </SrTooltip>

  <SrButton @click="visible = !visible">切换提示</SrButton>
</template>

Props

名称	类型	默认值	说明
content	string	—	提示文本
placement	见上文十二种	'top'	显示方位
trigger	'hover' | 'click'	'hover'	触发方式
disabled	boolean	false	是否禁用
showDelay	number	100	显示延迟（毫秒）
hideDelay	number	100	隐藏延迟（毫秒）
arrow	boolean	true	是否显示箭头
maxWidth	string	'240px'	最大宽度
modelValue	boolean	—	手动控制显隐

插槽

名称	说明
default	触发器元素
content	自定义提示内容（可放富文本）

无障碍

• 触发器自动获得 aria-describedby 指向提示内容， 读屏软件在聚焦时会朗读出来
• 键盘聚焦也触发显示，不是只有鼠标悬停—— 这是 aria-describedby 能生效的前提
• 提示容器带 role="tooltip"
• 提示内容不应包含交互元素（按钮、链接）—— 鼠标移向提示框时它会消失，根本点不到。 需要可交互内容请用 Popover 类组件