组件 · 数据展示

Tooltip 文字提示

悬停/聚焦时显示简短说明；由 TooltipTrigger + TooltipContent 等部件组成。

入口 @selrux/ui/tooltip · 源码 src/components/tooltip/index.ts · 5 个组件 · 发布状态 preview

使用建议

避免：把长文放入 Tooltip
避免：杜撰 openDelay 以外的未导出属性
限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx

123456789import {
  Tooltip,
  TooltipArrow,
  TooltipContent,
  TooltipPortal,
  TooltipTrigger,
  resolveTooltipSize,
  // …共 7 个导出
} from '@selrux/ui/tooltip';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

代码演示

基础用法

悬停或聚焦触发器时显示简短说明。

方向

side 为 top / bottom / left / right。

延迟与禁用

openDelay / closeDelay 控制时机，disabled 时不弹出。

尺寸与对齐

Tooltip 的 size；TooltipContent 的 align（start / center / end）、sideOffset 与 collisionPadding。

受控

open + onOpenChange 由外部控制；defaultOpen 为非受控初始值；closeDelay 设定离开后的关闭宽限。

API

属性覆盖：示例用到 12 / 12 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

TooltipPortal.container：Portal 挂载目标，默认 body；文档页无需更换挂载点

Tooltip 根。无布局 DOM。

属性	说明	类型	默认值
`size`	提示字号与内边距档位；省略取 Provider → md。	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`disabled`	为真时禁止打开；变为 true 立即抑制可见提示与资源。	`boolean`	-
`openDelay`	指针首次悬停延迟（ms），有限非负数；键盘聚焦不延迟。默认 500。	`number`	`500`
`closeDelay`	指针离开触发器与内容后的宽限（ms）。默认 100。	`number`	`100`
`open`	受控打开；与 defaultOpen 互斥。	`boolean`	-
`defaultOpen`	非受控默认打开；挂载时读取一次。	`boolean`	-
`onOpenChange`	请求变更；不强改父状态。	`((open: boolean, details: OverlayChangeDetails) => void)`	-
`children`	复合子树：Trigger / Portal 等。	`ReactNode`	-

TooltipArrow

TooltipArrow。

属性	说明	类型	默认值
`children`	装饰内容；默认空。	`ReactNode`	-

另有 278 项原生属性与事件继承自 HTMLAttributes，原样透传。

TooltipContent

TooltipContent。

属性	说明	类型	默认值
`style`	普通样式；必要定位属性由实现写入，不可被绕过失效。	`CSSProperties`	-
`side`	首选物理侧；默认 top。	`"top" \| "bottom" \| "left" \| "right"`	`top`
`align`	对齐；默认 center。	`"start" \| "end" \| "center"`	`center`
`sideOffset`	侧向间距（CSS px）；省略用库默认 4。	`number`	`4`
`collisionPadding`	碰撞内边距（CSS px）；省略用库默认 8。	`number`	`8`
`onEscapeKeyDown`	Esc 按下时调用；preventDefault 可取消关闭请求。	`((event: KeyboardEvent) => void)`	-
`children`	只读提示内容。	`ReactNode`	-

另有 277 项原生属性与事件继承自 HTMLAttributes，原样透传。

TooltipPortal

TooltipPortal。

属性	说明	类型	默认值
`container`	挂载目标；省略默认 body；显式 null 等待就绪。	`PortalContainerInput`	`body`
`children`	Portal 子树。	`ReactNode`	-

TooltipTrigger

TooltipTrigger。

属性	说明	类型	默认值
`render`	与 children 互斥；传 render 时禁用。	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	-
`children`	不传 render 时的按钮内容。	`ReactNode`	-

另有 285 项原生属性与事件继承自 ButtonHTMLAttributes / HTMLAttributes，原样透传。

导出类型：OverlayAlign、OverlayChangeDetails、OverlayChangeReason、OverlaySide、PortalContainerInput、TooltipArrowProps、TooltipContentProps、TooltipPortalProps、TooltipProps、TooltipSize、TooltipTriggerProps

函数与常量

名称	说明	签名 / 类型
`resolveTooltipSize`	按显式值、最近 Provider、md 的顺序解析尺寸。	`(size: TooltipSize \| undefined, configured: TooltipSize \| undefined) => TooltipSize`
`tooltipSizes`	合法尺寸集合。	`Set<TooltipSize>`

摘自源码 JSDoc。

Tooltip.openDelay：指针首次悬停延迟（ms），有限非负数；键盘聚焦不延迟。
TooltipContent.onEscapeKeyDown：Esc 按下时调用；preventDefault 可取消关闭请求。