文字提示 tooltip

反馈与浮层组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

悬停或聚焦触发器即出；指针停在提示上也不收起

<script setup lang="ts">
import {
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <XhTooltipRoot>
    <XhTooltipTrigger>保存</XhTooltipTrigger>
    <XhTooltipPositioner>
      <XhTooltipContent>
        写入草稿箱，不会发布
        <XhTooltipArrow />
      </XhTooltipContent>
    </XhTooltipPositioner>
  </XhTooltipRoot>
</template>

朝向

placement 是请求值，空间不够时由定位引擎避让；箭头跟着最终落定的那一面走

<script setup lang="ts">
import {
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const placements = [
  { value: "top", label: "上方" },
  { value: "right", label: "右侧" },
  { value: "bottom", label: "下方" },
  { value: "left", label: "左侧" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <XhTooltipRoot
      v-for="p in placements"
      :key="p.value"
      :placement="p.value"
      :open-delay="0"
    >
      <XhTooltipTrigger>{{ p.label }}</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>
          请求朝向 {{ p.value }}
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
  </div>
</template>

延时

openDelay 默认 700ms 用来防误触，closeDelay 默认 300ms 留出指针走位的余地；聚焦不走这两段等待

<script setup lang="ts">
import {
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <XhTooltipRoot>
      <XhTooltipTrigger>默认（700 / 300）</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>停够 700ms 才出来</XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>

    <XhTooltipRoot :open-delay="0" :close-delay="0">
      <XhTooltipTrigger>无延时</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>指针一进就出，一走就收</XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>

    <XhTooltipRoot :open-delay="1500">
      <XhTooltipTrigger>慢一点（1500）</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>用 Tab 聚焦它，立刻就出来</XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
  </div>
</template>

禁用

disabled 只关掉提示本身，被包裹的触发器照样可点、可聚焦

已点 0 次

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const clicks = ref(0);
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <XhTooltipRoot disabled>
      <XhTooltipTrigger @click="clicks++">点我（提示已关）</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>这段话不会出现</XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
    <span>已点 {{ clicks }} 次</span>
  </div>
</template>

语气

六种语气换的是浮层实心底与其上的文字色，箭头一并跟着走；把指针停在触发器上（或用 Tab 聚焦）看差别

<script setup lang="ts">
import {
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const tones = [
  { value: "brand", label: "品牌" },
  { value: "neutral", label: "中性" },
  { value: "success", label: "成功" },
  { value: "warning", label: "警告" },
  { value: "danger", label: "危险" },
  { value: "info", label: "信息" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <XhTooltipRoot
      v-for="t in tones"
      :key="t.value"
      :tone="t.value"
      placement="bottom"
      :open-delay="0"
    >
      <XhTooltipTrigger>{{ t.label }}</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>
          tone = {{ t.value }}
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
  </div>
</template>

尺寸

三档换的是浮层的内边距与字号，不写 size 即缺省档；把指针停在触发器上（或用 Tab 聚焦）看差别

<script setup lang="ts">
import {
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const sizes = [
  { value: "sm", label: "小" },
  { value: undefined, label: "缺省" },
  { value: "lg", label: "大" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <XhTooltipRoot
      v-for="s in sizes"
      :key="s.label"
      :size="s.value"
      placement="bottom"
      :open-delay="0"
    >
      <XhTooltipTrigger>{{ s.label }}</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>
          size = {{ s.value ?? "未指定" }}
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
  </div>
</template>

受控

传了 open 就由宿主说了算；悬停、聚焦、Escape 都只发意图，最终写不写由外面这份状态决定

最近意图：（还没动过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const open = ref(false);
const log = ref<string[]>([]);

// 只留最近三条意图
function onOpenChange(details: { open: boolean }) {
  log.value = [details.open ? "要展开" : "要收起", ...log.value].slice(0, 3);
}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <XhTooltipRoot
      v-model:open="open"
      placement="bottom"
      :open-delay="0"
      @open-change="onOpenChange"
    >
      <XhTooltipTrigger>把指针停上来</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>
          显隐完全跟着 open 走
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>

    <XhButton variant="outline" @click="open = !open">
      {{ open ? "收起" : "展开" }}
    </XhButton>
    <span>最近意图：{{ log.join(" ← ") || "（还没动过）" }}</span>
  </div>
</template>

长文案

提示到了宽度上限就换行，不会拉成一条横线；上限是 content 上的 --xh-tooltip-max-w 槽位

<script setup lang="ts">
import {
  XhTooltipArrow,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const text = "导出会把当前筛选条件下的全部行写进文件，行数很多时要等上一会儿。";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 24px">
    <XhTooltipRoot placement="bottom" :open-delay="0">
      <XhTooltipTrigger>缺省上限</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent>
          {{ text }}
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>

    <XhTooltipRoot placement="bottom" :open-delay="0">
      <XhTooltipTrigger>放宽到 360px</XhTooltipTrigger>
      <XhTooltipPositioner>
        <XhTooltipContent style="--xh-tooltip-max-w: 360px">
          {{ text }}
          <XhTooltipArrow />
        </XhTooltipContent>
      </XhTooltipPositioner>
    </XhTooltipRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-tooltip>
Vue 组件	XhTooltipArrow XhTooltipContent XhTooltipPositioner XhTooltipRoot XhTooltipTrigger
组合式函数	useTooltip
状态机	tooltipMachine
皮肤	@xihan-ui/styles/tooltip.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="tooltip"：trigger · positioner · content · arrow

Props

属性	类型	必填	说明
open	boolean
defaultOpen	boolean
placement	Placement		请求的浮层朝向，默认 bottom；空间不足时由定位引擎避让。
dir	Direction		文字方向，缺省 ltr。只改写浮层在行内轴上 start 与 end 的落点。
offset	number		浮层与锚点的间距（px）。
openDelay	number		悬停进入到展开的等待毫秒，默认 700。
closeDelay	number		悬停移出到收起的等待毫秒，默认 300。
disabled	boolean		只关闭提示本身，不影响被包裹控件的可用性。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定提示的底色与其上的文字色。
size	Size		尺寸：sm / md / lg，决定内边距与字号档位。
onOpenChange	(details: TooltipOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：closed · opening · open · closing

事件：POINTER.ENTER · POINTER.LEAVE · POINTER.DOWN · FOCUS · BLUR · ESCAPE · OPEN · CLOSE · after.openDelay · after.closeDelay · CONTROLLED.OPEN · CONTROLLED.CLOSE

判据：isOpenControlled · isDisabled · isFocusOpened

connect API

useTooltip 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
open	boolean
setOpen	(next: boolean) => void
getTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getArrowProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	not disabled	焦点进入 trigger 立即展开、离开立即收起，都不走延时
Escape	focus in trigger, 展开或等待展开中	立即收起，不等 closeDelay