InfoTip 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | @astryxdesign/core 的 InfoTip,具有 content、label(一个本地化的“更多信息”)、size(sm)、转发到按钮的 ref,以及 BaseProps 的 xstyle、className 和 style。@astryxdesign/lab 导出是对其一个版本的弃用再导出。 |
| 行为 | 一个已命名的原生信息图标按钮,通过 useTooltip 的 show() 和 hide() 固定其帮助内容:悬停和聚焦预览帮助;点击、轻触、Enter 或 Space 将其固定打开,直到 Escape、再次按下、在外部按下或焦点离开;鼠标或笔在由悬停显示的工具提示上按下时会将其保持在原位,而不会隐藏后再次显示。 |
| 最终用户影响 | 使用鼠标、触摸、键盘或屏幕阅读器的用户均可打开、保持打开并关闭“i”图标背后的帮助,并在它固定时听到一次播报。 |
| 构建者影响 | 当需要在标签、值或指标旁提供帮助时,请使用 InfoTip,而不是在 Tooltip 内部组合图标。Lab 调用者需更改导入。 |
| 兼容性/就绪度 | 在 Core 0.7.7 中发布;@astryxdesign/lab 导出是对其一个版本的弃用再导出(FR4)。 |
| 审查检查项 | 拒绝 InfoTip 自身的图层、文档监听器、定时器或关闭规则;按钮周围的包装元素;不是已命名原生按钮的触发器;固定按下传播至其周围的行、卡片或标签;在鼠标或笔按下时闪烁的预览;未翻译的默认名称;或超出 FR3 所列的额外 prop。 |
| 约束规则 | component:Tooltip FR9, FR10, FR12, AR6;architecture:public-component-api INV21;spec:AST-094 FR42;spec:AST-017(生命周期)。 |
此表是审查投影;下文正文为权威依据。
意图¶
InfoTip 是基于 useTooltip 的 show() 和 hide() 之上的信息图标预设。它拥有触发器按钮、其图标、其名称、其默认值,以及固定和关闭帮助的按下行为,因此产品中每个“i”的读法和行为都一致;Tooltip 拥有预览、固定保持和播报。消费者用法位于 InfoTip.doc.mjs 中。
兼容性与迁移¶
- 保留已发布的默认值:是。Core 在 0.7.7 中发布了 InfoTip,0.7.8 移除了其包装元素(DEC-1,已修订);Lab 组件的 props 保持其含义。
- 兼容性类别:增量的 Core 导出;Lab 组件以相同的 props 迁至 Core,并通过
useTooltip的show()和hide()固定帮助,而不是通过touchTrigger="tap"打开。 - 受控/非受控行为:仅非受控;打开状态属于 Tooltip。
- 迁移决策:DEC-1;
@astryxdesign/lab的InfoTip导出作为一个版本的弃用再导出保留,随后被移除。
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
- 在标准间距下,sm 盒子在精细指针下为 20×20 像素(某些主题将其渲染为 22×22 像素);当调用者使其他目标保持 24 像素间距时,它通过间距例外满足 WCAG 2.5.8,并且
spec:AST-094FR42 保持桌面盒子不变。
所有权边界¶
拥有
- 触发器按钮、其信息图标、其可访问名称和默认值,以及触摸命中区域(FR1, AR1)。
- 通过
useTooltip的show()和hide()固定并关闭帮助的按下行为,以及按钮的aria-describedby、aria-expanded和aria-controls(FR2)。
不拥有 / 非目标
- 帮助何时预览、固定帮助如何关闭、其播报、其表面,以及其 Escape 顺序——由
component:TooltipFR3–FR10 和 FR12 以及family:overlay-dismissal拥有。 - 信息图标素材的解析——由图标注册表(
architecture:icon-resolution-and-component-slots)拥有。 - 富交互帮助——
component:HoverCard。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Size | xsm, sm, md, lg |
信息图标的大小:12、16、20 或 24 像素。 | 每个 InfoTip。 | sm |
component:InfoTip |
稳定 | TypeScript 会拒绝其他取值。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | InfoTip 渲染一个由 label 命名的 <button type="button">,否则使用翻译后的 @astryx.infoTip.label(“更多信息”),其中包含注册表中 size 尺寸的 info 图标。 |
DEC-1; WCAG 2.2 SC 4.1.2; architecture:icon-resolution-and-component-slots |
| FR2 | InfoTip 通过一次传入 content 的 useTooltip 调用渲染按钮与浮层,且不包含任何包裹元素;Tooltip 的 ref 与热区 ref 在按钮上合并。按钮带有 aria-describedby(指向帮助内容)、aria-expanded(仅在固定时为 true)以及 aria-controls(在帮助显示时指向浮层)。单击、触摸、Enter 或 Space 会通过 show() 固定帮助内容;对已固定帮助执行相同的按压则会通过 hide() 将其关闭;该按压在 React 树中停止传播,因此按钮所在的行、卡片或标签不会触发行为。鼠标或触控笔在悬停显示的提示上按下时,会在指针按下时通过 show() 使其保持固定,因此 Tooltip 的按下关闭(component:Tooltip FR6)会使其保持打开:它不会隐藏后再次显示,随后的单击会将其固定。触摸和键盘只能通过单击来固定。InfoTip 本身不添加浮层、文档监听器、计时器、公告或解除规则:预览、固定帮助的关闭方式以及公告均属于 Tooltip 的 FR3–FR10 和 FR12。 |
DEC-1; component:Tooltip FR9, FR10, FR12; architecture:public-component-api INV21 |
| FR3 | 公共 props 为 content(必填;简短且非交互的帮助内容)、label、size、转发到按钮的 ref,以及 BaseProps 的 xstyle、className 和 style;InfoTip 不接受任何关于打开状态、位置或触发方式的 props。宿主的 data-* 属性会传递到按钮;其名称及 FR2 中的属性仍归组件所有。 |
DEC-1 |
| FR4 | @astryxdesign/lab 的 InfoTip 导出会重新导出 Core 组件,并以静态元数据标记为弃用,持续一个发布版本,之后被移除。 |
spec:AST-017 FR29, FR29a |
允许的变化¶
- AV1 — 图标图形。 主题可以替换注册表的
info图形。 - AV2 — 帮助文本。
content会变化;它保持简短且不可交互。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 关闭 | 一个带有信息图标的命名按钮;aria-expanded="false"。 |
尺寸。 |
| 预览 | Tooltip 在悬停或获得键盘焦点时显示,并描述该按钮。 | — |
| 固定 | Tooltip 保持打开,aria-expanded="true",播报一次。 |
— |
转换与优先级顺序¶
- ORD1 — 名称。 首先是
label,然后是翻译后的默认值。
性能与资源¶
- PR1 — 自身不引入资源。 InfoTip 除了其按钮的点击和指针按下处理器,以及 AR1 所需的共享点击区域监视之外,不添加任何文档监听器、观察器、定时器或图层;它带来的其他资源只有 Tooltip 的资源。
无障碍契约¶
- AR1 — 触发器是一个命名按钮。 该按钮位于 Tab 键顺序中,具有名称 (FR1),并且在粗指针下,只要邻居留出空间,就能通过一个不可见的点击区域达到 44 px:该点击区域从不与邻居的目标重叠,并被限制在近邻之间间隙的一半(
spec:AST-094FR42)。 - AR2 — 帮助是一个切换提示。
component:TooltipAR6:键盘和触摸用户无需悬停即可固定和关闭帮助,按钮报告aria-expanded,并且帮助在固定时播报一次。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 触发器按钮 | 一个承载图标的小圆形按钮。 | 当前源 | 支持性 | FR1, AR1 |
| 信息图标 | 注册表中尺寸为 size 的 info 图形。 |
Icon 注册表 | 支持性 | FR1 |
| 帮助浮层 | Tooltip 的浮层,包含 content。 |
component:Tooltip |
突出 | FR2 |
主题化结构¶
{
"Trigger button": {
"none": {
"reason": "unsettled: InfoTip's own button paints but has no public theming target yet; adding an `info-tip` target is a future owner decision"
}
},
"Info icon": {"delegatesTo": {"owner": "component:Icon", "target": "icon"}},
"Help surface": {
"delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
}
}
none 状态记录当前的可达性,而触发按钮的目标曝光尚未确定(architecture:component-theming-surface INV3)。信息图标的图案来自图标注册表,帮助表面则属于 Tooltip(architecture:component-theming-surface INV5)。
家族与系统关系¶
component:Tooltip拥有预览、show()保持、通告和表面;InfoTip 完全构建在useTooltip之上(DEC-1)。family:overlay-dismissal通过 Tooltip 拥有 Escape 顺序。architecture:icon-resolution-and-component-slots拥有info图案。- InfoTip 和 Tooltip 是同一个 API,原因如 DEC-1 所述:InfoTip 完全构建在
useTooltip的公共show()和hide()之上,并且不添加自己的层、定时器或关闭规则,正如component:MoreMenu构建在 DropdownMenu 之上一样。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | InfoTip.test.tsx 的 button、name、catalog-default、icon-size 和 hit-area 用例;InfoTipTouch.a11y.chromium.spec.ts 的粗指针可达性、相邻目标和细指针用例;InfoTipAudit.a11y.chromium.spec.ts 在细指针下、亮色与暗色及两种主题下的 button、name、icon-size、round-box、focus-outline 和 spacing-exception 检查 |
默认与自定义 name;每种 size;紧挨 label 的按钮 | 不是具名按钮的触发器、未翻译的默认值、尺寸不符的图标、粗指针下在相邻元素留出空间时仍小于 44 px 或触及相邻目标的热区,或细指针下在 24 px 内有相邻目标时仍小于 24 px 的方框,均判定为失败。 | audit:InfoTip/accessibility |
| FR2, AR2 | InfoTip.pin.test.tsx;InfoTip.test.tsx 的按压用例;InfoTipAudit.a11y.chromium.spec.ts 的 hover、keyboard-focus、click-pin、key-pin 和 Escape 用例;TouchTrigger.a11y.chromium.spec.ts 中 InfoTip 的 press-to-pin 和 pinned-under-a-mouse 套件 |
悬停和聚焦预览;点击、轻触、Enter、Space 固定;再次按压、按压外部、焦点离开和 Escape 关闭;对悬停预览的鼠标或触控笔按压;ClickableCard 内的按钮、Item 行和 <label> |
未固定也未关闭的按压、在鼠标或触控笔按压下关闭并重新打开的预览、缺失或过期的 aria-expanded 或 aria-controls、同时激活卡片、行或带标签控件的按压,或 InfoTip 拥有的包装器、层或 document 监听器,均判定为失败。 |
audit:InfoTip/behavior |
| FR3 | InfoTip.test.tsx 的 props 用例:类型检查器拒绝其他 props,且 ref、xstyle、className、style 和宿主 data-* 属性到达按钮 |
content、label、size、ref、xstyle、className、style |
超出上述范围的 prop,或未到达按钮的 ref,均判定为失败。 |
audit:InfoTip/api |
| FR4 | Lab 的 InfoTip.test.tsx 身份与弃用用例 |
Lab 导入 | 不是 Core 组件的 Lab 导出,或缺少弃用元数据,均判定为失败。 | audit:InfoTip/api |
| 主题解剖映射 | scripts/check-knowledge.mjs |
三个解剖部分及其布局 | 缺失、多余或过时的映射,或委托给其所有者未声明的目标,都会导致仓库验证失败。 | audit:InfoTip/theming |
决策日志¶
DEC-1 — InfoTip 是 useTooltip 的 show 和 hide 之上的预设¶
参考: component:InfoTip/DEC-1
决策者: cixzhang,2026-10-31;修订于 2026-11-03
“i”图标背后的帮助提示与按下时固定的 tooltip 是同一类工作,因此 InfoTip 只提供具名按钮、其图标、其默认值,以及用于固定的按压,并且完全构建在 useTooltip 的公开 show() 和 hide() 之上(component:Tooltip FR12)。Tooltip 本身没有切换选项:InfoTip 的固定方式与任何应用中的切换式按钮相同。完全构建在另一个公共 API 之上的组件与后者同属一个 API(architecture:public-component-api INV21;spec:AST-107 DEC-2 和 DEC-3 的推理适用于构建在公共工厂之上的组件),正如 component:MoreMenu 构建在 DropdownMenu 之上一样,因此 InfoTip 不会为 Tooltip 的工作增加第二种方式。
已拒绝:一个通用的 toggletip 组件,它会重复 Tooltip 和 HoverCard 的预览。
开放问题¶
无。
内容边界¶
本文件不重复 Tooltip 的打开、关闭或播报规则、消费者 prop 表格或示例。它链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx