Tooltip
Tooltip 与 Tooltip Group 基础原型
Base Tooltip 由 Root、Trigger 与 Content 组成;Tooltip Group 是同族的相邻协议,用于在多个 Root 间共享 delay defaults、warm window 与 active owner coordination。
- 首次 pointer hover 在
openDelay后打开,反向移动会取消 pending task。 - keyboard focus 立即打开,不等待 pointer delay。
closeDelay让指针可以从 Trigger 移入 Content;Content 本身不得包含可聚焦交互。- Trigger 只在 open 时以 additive
aria-describedby引用role="tooltip"的 Content。 - Escape 进入 Root 的统一 close request channel。
- Group warm window 内切换到 sibling Tooltip 时立即打开;前一个非受控 Tooltip 同步结束感知 presence,不保留可见退场重叠,
skipDelay到期后恢复首次延迟。 - Draft 生命周期规则:当前 active Root 卸载或终止销毁时,Group 立即恢复 cold 延迟;普通关闭仍保留
skipDelaywindow。保留 open fact 的 Root 重新挂载时再次登记;旧 cleanup 不得清除新 active Root,拒绝关闭的受控 Root 也不会被自动重新选主。
当前 Portal 由 Content 的 Overlay/renderer projection 持有,不单独提供 Base Portal 原型。Arrow 需要受治理的 geometry/positioning 通道,暂不属于当前 Base 保证。
<wc-base-tooltip-group id="tooltip-group-demo">
<wc-base-tooltip-root>
<wc-base-tooltip-trigger>Account</wc-base-tooltip-trigger>
<wc-base-tooltip-content class="tooltip-content">
View account settings and profile details.
</wc-base-tooltip-content>
</wc-base-tooltip-root>
<wc-base-tooltip-root>
<wc-base-tooltip-trigger>Notifications</wc-base-tooltip-trigger>
<wc-base-tooltip-content class="tooltip-content">
Review recent alerts and notification preferences.
</wc-base-tooltip-content>
</wc-base-tooltip-root>
</wc-base-tooltip-group>
<script type="module">
document.querySelector('#tooltip-group-demo').setProps({
openDelay: 500,
closeDelay: 150,
skipDelay: 700,
});
document.querySelectorAll('.tooltip-content').forEach((content) => {
content.setProps({ side: 'top', sideOffset: 8 });
});
</script>建议验收路径
Section titled “建议验收路径”- 把指针移入
Account,确认约 500ms 后出现 Tooltip;提前移出时不应闪现。 - Tooltip 打开后快速移到
Notifications,确认 sibling 在 warm window 内立即打开,且前一个立即消失、没有双 Tooltip 可见重叠。 - 等两个 Tooltip 都关闭超过 700ms,再次 hover,确认恢复 500ms 延迟。
- 使用 Tab 聚焦 Trigger,确认立即打开;按 Escape 后关闭且焦点仍留在 Trigger。
- 在工具栏切换 Web Components、React 与 Vue,重复上述交互。
在 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 样式工作分别追踪。
Tooltip 是工作区源码,没有公开的 proto-ui add 目标。传入 open 进入受控模式。
| 属性 | 类型 | 默认值 |
|---|---|---|
defaultOpen | boolean | false |
disabled | boolean | false |
openDelay | number | undefined |
closeDelay | number | undefined |
这些属性属于 Root。Trigger 的 disabled 默认 false。Content 接受 Transition 属性,side 默认 top,align 默认 center,sideOffset 默认 4,alignOffset 与 collisionPadding 默认 0,avoidCollisions 默认 true。Group 的 openDelay 默认 700,closeDelay 默认 100,skipDelay 默认 300。