Tooltip 工具提示

基于 reka-ui 的 Tooltip 原语构建的新粗野主义风格工具提示，悬停时显示信息文字。通过 TooltipProvider 为所有后代工具提示提供全局配置，支持自定义延迟、受控模式等。

预览

Preview

安装

pnpm dlx brutx-vue@latest add tooltip

用法

基础用法

<script setup>
import { TooltipRoot as Tooltip, TooltipTrigger } from 'reka-ui'
import { TooltipProvider, TooltipContent, Button } from 'brutx-ui-vue'
</script>

<template>
    <TooltipProvider>
        <Tooltip>
            <TooltipTrigger as-child>
                <Button variant="outline">Hover me</Button>
            </TooltipTrigger>
            <TooltipContent>
                <p>This is a tooltip</p>
            </TooltipContent>
        </Tooltip>
    </TooltipProvider>
</template>

配合 Provider 使用

用 TooltipProvider 包裹你的应用（或某个区域）以启用工具提示：

<script setup>
import { TooltipProvider } from 'brutx-ui-vue'
</script>

<template>
    <TooltipProvider>
        <router-view />
    </TooltipProvider>
</template>

触发延迟

通过 TooltipProvider 的 delayDuration 属性控制从指针进入触发元素到工具提示打开的延迟时间（毫秒）。也可以在单个 Tooltip 上通过 delayDuration 覆盖全局设置。

<TooltipProvider :delay-duration="0">
    <Tooltip>
        <TooltipTrigger>
            <Button>立即显示</Button>
        </TooltipTrigger>
        <TooltipContent>
            <p>无延迟</p>
        </TooltipContent>
    </Tooltip>
</TooltipProvider>

<TooltipProvider>
    <Tooltip :delay-duration="1500">
        <TooltipTrigger>
            <Button>长延迟</Button>
        </TooltipTrigger>
        <TooltipContent>
            <p>覆盖为 1500ms</p>
        </TooltipContent>
    </Tooltip>
</TooltipProvider>

受控模式

通过 open 和 @update:open 控制工具提示的显示状态：

<script setup>
import { ref } from 'vue'
import { TooltipRoot as Tooltip, TooltipTrigger } from 'reka-ui'
import { TooltipProvider, TooltipContent, Button } from 'brutx-ui-vue'

const isOpen = ref(false)
</script>

<template>
    <TooltipProvider>
        <Tooltip v-model:open="isOpen">
            <TooltipTrigger as-child>
                <Button variant="outline">受控工具提示</Button>
            </TooltipTrigger>
            <TooltipContent>
                <p>当前状态：{{ isOpen ? '打开' : '关闭' }}</p>
            </TooltipContent>
        </Tooltip>
    </TooltipProvider>
</template>

子组件

组件	说明
TooltipProvider	上下文提供者（必需的祖先组件）
Tooltip	根组件（从 reka-ui 的 TooltipRoot 重新导出）
TooltipTrigger	悬停时触发工具提示的元素
TooltipContent	工具提示内容面板

API 组成

此包的 TooltipProvider 和 TooltipContent 是本地封装，完整属性见下方 API 参考；Tooltip 与 TooltipTrigger 是来自 Reka UI 的原语，以下保留它们的原语属性。

TooltipProvider

从 reka-ui 的 TooltipProvider 重新导出，为所有后代工具提示提供全局配置。

Tooltip

从 reka-ui 的 TooltipRoot 重新导出，管理单个工具提示的状态。

属性	类型	默认值	说明
defaultOpen	boolean	—	非受控模式下的初始打开状态
open	boolean	—	受控的打开状态
delayDuration	number	700	覆盖 Provider 的延迟时间，针对单个工具提示自定义
disableHoverableContent	boolean	—	继承自 Provider，可单独覆盖
disableClosingTrigger	boolean	false	为 true 时，点击触发元素不会关闭工具提示
disabled	boolean	false	为 true 时，禁用此工具提示
ignoreNonKeyboardFocus	boolean	false	为 true 时，仅键盘聚焦才触发

TooltipTrigger

触发器组件，悬停或聚焦时打开工具提示。

属性	类型	默认值	说明
as	string | Component	'button'	渲染的元素类型
asChild	boolean	—	将样式渲染到子元素上

TooltipContent

工具提示内容面板，使用新粗野主义风格。默认通过 Portal 渲染到 body。

Reka UI 原语事件

Tooltip

事件	参数	说明
update:open	value: boolean	打开状态变化时触发

TooltipContent

事件	参数	说明
escapeKeyDown	KeyboardEvent	按下 Escape 键时触发，可阻止默认行为
pointerDownOutside	Event	在外部按下指针时触发，可阻止默认行为

Reka UI 原语插槽

Tooltip

插槽	作用域	说明
default	{ open: boolean }	作用域插槽，提供当前打开状态

TooltipTrigger / TooltipContent

插槽	作用域	说明
default	—	默认插槽内容

API 参考

TooltipContent

TooltipContent — 属性

名称	类型	默认值	说明
class	string | undefined	undefined	追加到 Portal 中工具提示内容面板的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/tooltip/TooltipContent.vue 解析值 undefined 来源 TooltipContent.vue:13 packages/ui/src/components/tooltip/TooltipContent.vue
to	string | HTMLElement | undefined	undefined	指定 Portal 挂载目标，可以是 CSS 选择器字符串或 HTMLElement；未指定时挂载到 body。
详情 声明类型 string | HTMLElement | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/tooltip/TooltipContent.vue 解析值 undefined 来源 TooltipContent.vue:14 packages/ui/src/components/tooltip/TooltipContent.vue
forceMount	boolean | undefined	—	即使工具提示关闭也强制挂载内容，便于由 Vue 动画库等控制显示过渡。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
ariaLabel	string | undefined	—	为内容面板提供无障碍名称；当面板内容不足以说明其用途时可设置。
详情 声明类型 string | undefined 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
asChild	boolean | undefined	—	将内容面板属性与交互行为合并到唯一子元素，并由子元素替代默认面板元素。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
as	AsTag | Component | undefined	—	指定内容面板使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情 声明类型 AsTag | Component | undefined 字面量 "a" "button" "div" "form" "h2" "h3" "img" "input" "label" "li" "nav" "ol" "p" "span" "svg" "template" "ul" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
sideOffset	number | undefined	6	设置内容面板与触发器之间的距离，单位为像素。
详情 声明类型 number | undefined 默认值详情 声明 floatingContentSideOffsets.tooltip 来源: packages/ui/src/components/tooltip/TooltipContent.vue 解析值 6 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
align	"center" | "start" | "end" | undefined	—	设置内容相对于触发器的首选对齐方式；发生边界碰撞时可能调整。
详情 声明类型 "center" | "start" | "end" | undefined 字面量 "center" "end" "start" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
collisionPadding	number | Partial<Record<"right" | "bottom" | "left" | "top", number>> | undefined	6	设置内容进行碰撞检测时与边界的留白；数字应用于各边，也可分别指定各方向的像素值。
详情 声明类型 number | Partial<Record<"right" | "bottom" | "left" | "top", number>> | undefined 默认值详情 声明 floatingContentSideOffsets.tooltip 来源: packages/ui/src/components/tooltip/TooltipContent.vue 解析值 6 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
side	"right" | "bottom" | "left" | "top" | undefined	—	设置内容相对触发器的首选显示方向；启用碰撞处理时可翻转到其他方向。
详情 声明类型 "right" | "bottom" | "left" | "top" | undefined 字面量 "bottom" "left" "right" "top" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
alignOffset	number | undefined	—	沿 start 或 end 对齐方向额外偏移的像素数。
详情 声明类型 number | undefined 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
avoidCollisions	boolean | undefined	—	启用后根据边界空间调整首选 side 与 align，避免内容越过碰撞边界。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
collisionBoundary 可空	Element | (Element | null)[] | null | undefined	—	参与碰撞检测的边界元素；默认使用视口，也可传入一个或多个额外元素。
详情 声明类型 Element | (Element | null)[] | null | undefined 字面量 null 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
arrowPadding	number | undefined	—	设置箭头与内容边缘之间的留白，避免箭头越过圆角。
详情 声明类型 number | undefined 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
sticky	"partial" | "always" | undefined	—	设置沿对齐轴的粘附策略；partial 在触发器仍部分可见时保持内容在边界内，always 则始终保持。
详情 声明类型 "partial" | "always" | undefined 字面量 "always" "partial" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
hideWhenDetached	boolean | undefined	—	触发器完全离开视口或边界时隐藏内容。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
positionStrategy	"fixed" | "absolute" | undefined	—	设置浮层使用 fixed 或 absolute CSS 定位策略。
详情 声明类型 "fixed" | "absolute" | undefined 字面量 "absolute" "fixed" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue
updatePositionStrategy	"always" | "optimized" | undefined	—	设置浮层位置更新策略；always 每帧更新，optimized 使用优化后的更新时机。
详情 声明类型 "always" | "optimized" | undefined 字面量 "always" "optimized" 默认值详情 未声明默认值 — 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue

TooltipContent — 插槽

名称	签名或类型	说明
#default	{}	渲染工具提示面板中的说明内容。
详情 声明类型 {} 来源 TooltipContent.vue packages/ui/src/components/tooltip/TooltipContent.vue

TooltipProvider

TooltipProvider — 属性

名称	类型	默认值	说明
delayDuration	number | undefined	400	指针进入触发器后打开工具提示前的等待时间，单位为毫秒；默认 400。
详情 声明类型 number | undefined 默认值详情 声明 DEFAULT_DELAY_DURATION 来源: packages/ui/src/components/tooltip/TooltipProvider.vue 解析值 400 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
skipDelayDuration	number | undefined	—	关闭一个工具提示后，在此毫秒数内进入另一个触发器时跳过打开延迟。
详情 声明类型 number | undefined 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
disableHoverableContent	boolean | undefined	—	启用后，指针离开触发器时即关闭内容；指针不能移入内容区域继续保持打开。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
disableClosingTrigger	boolean | undefined	—	启用后，点击触发器不会关闭已打开的工具提示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
disabled	boolean | undefined	—	禁用此 Provider 下的所有工具提示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
ignoreNonKeyboardFocus	boolean | undefined	—	忽略非键盘产生的焦点；只有匹配 :focus-visible 的键盘焦点才会触发工具提示。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue
content	TooltipContentProps | undefined	—	为此 Provider 下的 TooltipContent 设置默认定位与挂载选项；单个内容组件可以覆盖。
详情 声明类型 TooltipContentProps | undefined 默认值详情 未声明默认值 — 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue

TooltipProvider — 插槽

名称	签名或类型	说明
#default	{}	放置受此 Provider 配置管理的 Tooltip 组件。
详情 声明类型 {} 来源 TooltipProvider.vue packages/ui/src/components/tooltip/TooltipProvider.vue

可访问性

• 键盘操作：按 Escape 键关闭工具提示
• ARIA 属性：工具提示内容可被屏幕阅读器朗读，通过 ariaLabel 提供更精确的屏幕阅读器描述
• 焦点管理：工具提示在悬停和聚焦时出现，支持 ignoreNonKeyboardFocus 避免非键盘操作触发