Tooltip
覆盖在 Base Tooltip family 之上的 shadcn 草案呈现。
本页以 Shadcn Rhea 为目标,支持profile的parts均显式选择Rhea;下文headless触发器/action-body缺口仍开放,尚不称整页外观统一。这不修改公共组件的兼容默认值,也不代表全部浏览器、原生宿主和视觉验收已完成。Surface/Text 等中性原子仍保留各自公开语义,外观主题由消费组合提供。
这个 draft family 包含 Group、Root、Trigger 与 Content。open state、controlled ownership、disabled、pointer/focus intent、delay 与 dismissal sequencing、aria-describedby、presence、Escape、renderer-owned Portal projection 与 anchored positioning 继续只由 Base Tooltip 持有。shadcn 层仅增加 Group layout、Trigger feedback 与紧凑 Content surface。
历史 API 比较来源为 shadcn-ui/ui f31ed81983653919dd4fe77aee4b4859f610f1dc 的 apps/v4/registry/new-york-v4/ui/tooltip.tsx,不是本页选择的外观 profile。该 Provider 默认 pointer delay 为0ms;Proto UI 保留 Base Group 的700ms open、100ms close和300ms skip。该 Content 默认 sideOffset 为0,Proto UI 保留4。Portal 仍归 renderer,Arrow 在受治理的几何通道缺失时仍不可用。
Content 选择 Rhea 样式源码:inline-flex、fit-content、20rem最大宽度、6px gap和rounded-xl,使用foreground/background主题色反转形成提示表面。2026-10-10 的 base-nova snapshot(SHA256 2f55867faecee2d3616cfd8c6a80b538909a21e62fdfa2788b1ead56093e5395)只保留为未选profile时的兼容参考。Trigger是带既有Proto反馈的headless语义owner,不是Button;替换演示旧作者paint仍需公共Rhea被动action-body组合,不能再增加焦点/激活owner。Arrow、transform-origin、方向motion、kbd后代样式及原生视觉验收仍开放。
从 @proto.ui/prototypes-shadcn/tooltip 导入该 family,或使用 proto-ui add react shadcn-tooltip 生成 React facade。Content 保持 supplementary、不可聚焦且非任务必要;交互式任务内容应使用 Popover 或 non-modal Dialog。
建议验收路径
Section titled “建议验收路径”- hover Account,确认 cold Tooltip 约 700ms 后打开;提前离开时不得闪现。
- 在 300ms warm window 结束前移动到 Notifications,确认 sibling 立即打开且始终只有一个 active owner。
- 用 Tab 聚焦任一 Trigger,确认立即打开、focus ring 可见,且 Trigger 没有 button role。
- 确认 Content portal 到 preview frame 外,仍通过
aria-describedby关联,且没有可聚焦 control 或 Arrow。 - 按 Escape,确认 Content 关闭且焦点留在 Trigger。
- 在 Web Components、React、Vue 与 Vue 2 的 Light/Dark 模式中重复检查。
相关 entities 仍为 draft;本页描述当前 cataloged direction,而不是稳定 compatibility guarantee。
npx @proto.ui/cli@latest add wc shadcn-tooltip
把 wc 换成 react、vue 或 vue2,即可生成对应宿主的 facade。
在 Button 上使用 Tooltip
Section titled “在 Button 上使用 Tooltip”可聚焦命令与 Tooltip 应共用一个 subject。将 draft authored hook useTooltipTrigger() 与命令行为组合,适配生成的原型,再把该组件直接放在 Tooltip Root 内与 Content 并列。不要用独立 Trigger 包裹另一个可聚焦 Button,否则会产生两个 Tab 停靠点。
import { definePrototype } from '@proto.ui/core';import { asButton, type ButtonProps, type ButtonExposes } from '@proto.ui/prototypes-base/button';import { useTooltipTrigger } from '@proto.ui/prototypes-base/tooltip';
export const tooltipButton = definePrototype<ButtonProps, ButtonExposes>({ name: 'app-tooltip-button', setup() { asButton(); useTooltipTrigger(); },});Button 保留 role、name、click signal、disabled state 与唯一焦点 owner;Tooltip 只追加 hover/focus intent 与自有 aria-describedby 关联。禁用 Tooltip Root 只关闭 Tooltip,命令仍可操作;禁用命令则同时抑制两者。useTooltipTrigger 没有 options,也不新增 outward exposes,要求同一 subject 已有焦点能力。独立 asTooltipTrigger 保留原焦点行为与 exposes。
复用已有样式原型时,可在 definePrototype 中保留该原型的静态 modules 声明,调用其 setup(def),再调用 useTooltipTrigger(),最后返回之前保存的 render function。这保留 family Button 呈现并只创建一个宿主;与下方独立 Trigger demo 的 passive action-body 样式工作分别追踪。
Root 传入 open 进入受控模式。Root 未自设延时时使用 Group 的延时。
| 属性 | 类型 | 默认值 |
|---|---|---|
defaultOpen | boolean | false |
disabled | boolean | false |
openDelay | number | 700 |
closeDelay | number | 100 |
skipDelay | number | 300 |
side | 'top' 'right' 'bottom' 'left' | top |
align | 'start' 'center' 'end' | center |
sideOffset | number | 4 |
alignOffset | number | 0 |
avoidCollisions | boolean | true |
collisionPadding | number | 0 |
openDelay、closeDelay、skipDelay 属于 Group。side 到 collisionPadding 属于 Content。Trigger 只增加 disabled。