dotsharp

Tooltip 工具提示 ​

悬停或键盘聚焦触发元素时出现的浮层，两种形态：

  • variant="plain"（默认）：单行深色文字，只描述触发元素，不接收交互。
  • variant="rich"：带标题、正文与可选操作的卡片，指针可以从触发元素移进浮层。

默认出现在触发元素上方（placement="top"），空间不足时自动翻到对面并贴住视口边缘。

基础用法 ​

把触发元素放进默认插槽，label 是提示文字。出现有 500ms 的悬停延迟，键盘聚焦则立即出现。

vue
<script setup lang="ts">
import { Button, IconButton, Tooltip } from "@sharpdotnut/dotsharp";
import deleteIcon from "@iconify-icons/material-symbols/delete-outline";
import infoIcon from "@iconify-icons/material-symbols/info-outline";
</script>

<template>
  <Tooltip label="基础提示">
    <IconButton :icon="infoIcon" label="信息" />
  </Tooltip>
  <Tooltip label="删除这条记录">
    <IconButton :icon="deleteIcon" label="删除" />
  </Tooltip>
  <Tooltip label="悬停 500ms 后出现">
    <Button variant="tonal">悬停我</Button>
  </Tooltip>
</template>

富工具提示（Rich） ​

title 是标题，text 是正文，action-label 生成底部的文字按钮；点击按钮会发出 action 事件并关闭提示。 正文与操作也可以分别用 #content、#action 插槽替换。

最近一次操作：尚未触发

vue
<script setup lang="ts">
import { ref } from "vue";
import { Button, Tooltip } from "@sharpdotnut/dotsharp";

const lastAction = ref("尚未触发");
</script>

<template>
  <Tooltip
    variant="rich"
    title="富工具提示"
    text="富工具提示用于强调某个需要用户注意的元素或功能，可以包含更多说明。"
    action-label="查看详情"
    @action="lastAction = '已点击查看详情'"
  >
    <Button>富提示</Button>
  </Tooltip>
</template>

富提示宽度上限 320px，正文用 --ds-text-muted，标题与正文之间留 4px。指针移进卡片时保持展开， 移出后 120ms 才收起，因此在卡片里点操作不会因为穿过间隙而消失。

方位 ​

placement 支持 top / bottom / left / right。首选方位放不下时会自动翻到对面，再贴住视口边缘。

vue
<Tooltip label="上方" placement="top">
  <Button variant="outlined">上方</Button>
</Tooltip>
<Tooltip label="下方" placement="bottom">
  <Button variant="outlined">下方</Button>
</Tooltip>
<Tooltip label="左侧" placement="left">
  <Button variant="outlined">左侧</Button>
</Tooltip>
<Tooltip label="右侧" placement="right">
  <Button variant="outlined">右侧</Button>
</Tooltip>

受控展开 ​

v-model:open 可以读写展开状态。悬停、聚焦、Escape 与操作按钮都会同步写回，因此可以直接据此做埋点或联动。

vue
<script setup lang="ts">
import { ref } from "vue";
import { Button, Tooltip } from "@sharpdotnut/dotsharp";

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

<template>
  <Tooltip label="由按钮控制" v-model:open="controlled">
    <Button variant="tonal">受控提示</Button>
  </Tooltip>
  <Button variant="outlined" @click="controlled = !controlled">
    {{ controlled ? "收起" : "展开" }}
  </Button>
</template>

禁用 ​

disabled 时悬停与聚焦都不再展开；展开过程中禁用会立即收起。

vue
<Tooltip label="不会出现" disabled>
  <Button variant="outlined">已禁用</Button>
</Tooltip>

API ​

属性类型默认值说明
v-model:openbooleanfalse展开状态；悬停、聚焦与 Escape 会写回
variant"plain" | "rich""plain"纯文字提示 / 带标题与操作的卡片
labelstring—plain 的文字
titlestring—rich 的标题
textstring—rich 的正文；#content 插槽优先
action-labelstring—rich 底部操作文字；#action 插槽优先
placement"top" | "bottom" | "left" | "right""top"首选方位，放不下时翻面
disabledbooleanfalse禁用所有展开方式
show-delaynumber500悬停出现延迟（毫秒），聚焦不受影响
插槽说明
default触发元素，任意可聚焦内容
content替换 plain 的文字或 rich 的正文
action替换 rich 底部的操作按钮
事件参数说明
action—点击 rich 的操作按钮时触发
  • 其余属性与事件透传到包裹触发元素的根 span；根元素固定 inline-flex。
  • 浮层用 fixed 定位并紧跟在触发元素之后渲染，因此 Tab 可以从触发元素进入富提示的操作按钮； 窗口滚动、缩放时重新测量。
  • plain 变体把文字通过 aria-describedby 关联到单个触发元素（多个元素时退回根元素）；rich 变体的面板是 role="dialog"，标题用 aria-labelledby 关联。

可访问性 ​

  • plain 提示是纯描述，不接收焦点与指针；按 Escape 收起，键盘用户不会被困在提示里。
  • rich 提示里可以放按钮：提示紧跟触发元素渲染，Tab 可进入面板；焦点移入面板时保持展开，按 Escape 或在面板内点击操作后关闭，焦点回到触发的第一个可聚焦元素。
  • 图标按钮必须始终提供 label，不要把唯一的说明只写进 Tooltip —— 触摸与读屏用户不一定能看到它。