Badge 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | 一个只读的单行标签,带有必需的 label、可选的前置 icon,以及一个可由主题扩展的 variant(默认 neutral)。 |
| 行为 | Badge 从不换行,其宽度与标签一致;当标签超过可用空间时,会在 Badge 内部以省略号截断,并且字符串或数字标签也会写入根元素的 title。 |
| 最终用户影响 | 读者会看到紧凑的状态或类别标签,且标签保持在容器内;辅助技术会读取完整标签文本。 |
| 构建者影响 | 无;本记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 没有 API 或默认值变更。FR3 是一项可见且不破坏兼容性的布局修正:网格单元格或堆叠容器交叉轴上的单个 Badge 会保持其标签宽度。当前状态影响下列出了一项实现缺口。 |
| 审查检查项 | 若 Badge 发生换行或逃出容器、title 由富标签派生、Badge 自行添加 role、Tab 停靠点或 live region,或者某个 variant 未体现在 badge 上,则应拒绝。 |
| 治理规则 | architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2,INV6,INV14。 |
此表是审查投影;下文正文具有权威性。
意图¶
Badge 用简短、不可交互的标签标记一个状态或类别。它负责标签的单行几何、溢出处理,以及主题可扩展的内置色调的封闭集合。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:没有公开 prop 或默认值变更。DOM 和样式输出有所变化:不含从右到左字母的纯文本标签会获得
dir="ltr",并且标签会隔离其文本(unicode-bidi: isolate)。FR3 是一项可见且不破坏兼容性的布局修正:网格单元格或堆叠容器交叉轴上的单个 Badge 会保持其内容宽度,而不是拉伸到单元格或堆叠容器 - 受控/非受控行为:不适用;Badge 不持有状态
- 迁移决策:无
使用方的迁移说明属于使用方文档和发布说明。
当前状态影响¶
- 被截断的标签尾部仅对指针可用(AR4)。 键盘和触摸用户无法查看长标签被截断的尾部;只有指针悬停在原生
title上时才会显示。辅助技术仍会从 DOM 接收完整文本。
所有权边界¶
拥有
- Badge 根元素、其可选的前置 Icon 插槽,以及标签容器。
- 单行几何、内边距、圆角、字体排印,以及省略号溢出处理。
- 内置的
variant色调,以及variant在badge主题目标上的体现。 - 从字符串或数字标签派生根元素
title。
不拥有 / 非目标
- 产品显示哪种状态或类别、其措辞,以及 Badge 是否合适——由产品调用点和
Badge.doc.mjs中的使用方指南负责。 - 所提供图标的图形、尺寸和无障碍暴露——由所提供节点负责(传入 Icon 时为
component:Icon)。 - 类标签和仅圆点的状态呈现——由
component:Token和component:StatusDot负责。 - 每种色调使用的颜色令牌的对比度——由当前主题负责。
公开概念¶
| 概念 | 封闭值或状态 | 含义 | 按 variant/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
色调(variant) |
语义:neutral、info、success、warning、error;颜色:blue、cyan、green、orange、pink、purple、red、teal、yellow;主题扩展 |
选择 Badge 的填充和文本颜色。 | 所有 Badge | neutral |
component:Badge |
稳定 | 主题添加的值会体现在 badge 上,且不会获得组件填充或颜色(FR6);TypeScript 会拒绝未注册的值。 |
| 标签 | 字符串、数字或富节点 | Badge 的可见内容。 | 始终渲染;必需 | 必需 | component:Badge |
稳定 | 空字符串会渲染空标签,且不生成 title。 |
| 图标 | 存在;不存在 | 可选的调用方提供的节点,显示在标签之前。 | 所有徽章 | 不存在 | component:Badge |
稳定 | 不存在时不渲染图标,也不渲染占位。 |
行为和布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 徽章渲染一个 inline-flex span 根元素,在两个轴向上居中;块级尺寸为 --spacing-5(在 spec:AST-102 FR4 下设置文本大小后,至少会达到该尺寸;当前固定尺寸只是一个间距值),无块级内边距,内联内边距为 --spacing-2,圆角为 --radius-full,字体族继承自父级,文本使用 --text-supporting-size 和 --text-supporting-leading,字重为 --font-weight-medium。 |
当前源码 |
| FR2 | 当提供 icon 时,它直接渲染在根元素内部、标签容器之前,并通过 --spacing-1 分隔;标签始终渲染在自身的标签容器中。 |
当前源码和测试 |
| FR3 | 徽章为单行,且从不换行。根元素宽度与内容一致,因此不会拉伸以填满网格单元格或堆叠布局的交叉轴;它被限制在容器的内联尺寸内,并且可能收缩到小于其内容尺寸;放不下的标签会在标签容器内以尾部省略号截断,而不会溢出徽章。 | 当前源码和使用方文档 |
| FR4 | 非空字符串标签或任何数字标签都会将根元素的 title 设置为该标签文本,无论标签是否被截断。富节点或空字符串标签不会设置 title。 |
当前源码和测试 |
| FR5 | variant 默认为 neutral。neutral 使用 --color-neutral 填充,并使用主要文本颜色;info、success、warning 和 error 使用各自醒目的状态填充色(--color-<status>)和对应的 --color-on-<status> 文本颜色,并在强制颜色模式下保留 CanvasText 轮廓;每种颜色变体都绘制其浅色背景,并使用匹配的有色文本。 |
当前源码和使用方文档 |
| FR6 | badge 目标元素会为每个值携带解析后的 variant,包括主题通过 BadgeVariantMap 添加的值。主题添加的值不会获得组件填充色或文本颜色,因此在主题绘制之前,它会在透明背景上以继承的文本颜色渲染 FR1 几何形状。 |
当前源码和可扩展轴测试 |
| FR7 | ref 可到达根 span 元素。受支持的 DOM、ARIA、data 和事件 props 都会到达根元素;xstyle、className 和 style 按该顺序合并到组件样式之后。 |
当前源码和测试 |
| FR8 | 徽章不使用任何 hooks、测量或仅客户端 API,因此在服务端和客户端的渲染结果一致。 | 当前源码和服务端安全测试 |
允许的变体¶
- AV1 — 主题绘制。 主题可以更改
badge的任何视觉属性,包括每个variant的填充、文本颜色、高度和圆角,而不改变其结构、单行规则或title规则。 - AV2 — 标签内容。 标签长度和内容可以变化;截断位置取决于可用的内联尺寸。
代表状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 默认 | 中性色调、单行,title 等于字符串标签。 |
标签文本。 |
| 带 Icon | Icon 在 inline-start 侧渲染于 Label 容器之前。 | Icon 图形和尺寸。 |
| 计数 | 数字标签渲染为文本,并将 title 设置为其字符串形式。 |
色调。 |
| 长标签、窄容器 | Badge 保持在其容器内,标签以省略号结尾。 | 裁剪位置。 |
| 丰富标签 | 节点在 Label 容器内渲染,且不设置 title。 |
节点内容。 |
| 主题新增变体 | data-variant 命名新增的值;不应用任何组件填充或颜色。 |
新增值的主题绘制。 |
转换与优先级顺序¶
- ORD1 — 根属性。 组件类与
data-variant→ 组件样式 →xstyle→className→style→ 派生的title→ 其余调用方 props。 - ORD2 — 内容顺序。 Icon,然后是 Label 容器,按逻辑内联顺序排列。
性能与资源¶
- PR1 — 静态渲染。 Badge 不注册任何监听器、观察器、计时器或副作用,也不执行任何布局测量。
无障碍契约¶
- AR1 — 静态文本。 Badge 不自行添加 role、Tab 停靠点或实时区域,并将其标签作为普通文本按阅读顺序暴露,因此更改后的标签不会被播报。调用方传入的
role或tabIndex会透传(FR7)。 - AR2 — 文本中的含义。 Badge 将
label渲染为文本,色调颜色是对该文本的补充。空标签会渲染出仅有颜色、无障碍树中无任何内容的 Badge;提供有意义的标签是调用方的责任。 - AR3 — 图标暴露被委托。 Badge 不会向所提供 Icon 添加名称、role 或
aria-hidden;其暴露方式由所提供节点自身决定(在component:Icon下,没有标签的 Icon 是装饰性的)。 - AR4 — 完整文本保留在 DOM 中。 裁剪仅是视觉上的:完整标签仍保留在无障碍树中,FR4 的
title将其暴露给指针悬停。实现差距:键盘和触摸用户无法查看被裁剪的尾部。
设计关系¶
| 组成部分或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Badge 根 | 一个紧凑的单行胶囊,其色调表示状态或类别。 | 当前源码 | 辅助 | FR1, FR3, FR5, FR6 |
| Icon | 一个可选的前导字形,有助于识别 Badge 类型。 | 当前源码与文档 | 辅助 | FR2, AR3 |
| Label | 承载 Badge 含义的文本或数字。 | 当前源码与文档 | 突出 | FR3, FR4, AR2, AR4 |
主题化:根是唯一的 badge 目标,并反映 variant。Label 容器和 Icon 插槽不添加任何目标:标签继承 badge,所提供的 Icon 保留其自身样式并继承 Badge 文本颜色。
家族与系统关系¶
architecture:public-component-api拥有 ref、透传和样式输入规则;FR7 将它们应用于根span。architecture:component-theming-surface拥有目标限定、状态映射和可扩展轴规则;FR6 记录 Badge 的可扩展variant轴及其无主题回退。
验证映射¶
| 契约 | 验证 | 代表状态 | 突变或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR2, FR7 | Badge.test.tsx |
Icon、ref、透传 | 移除 Icon、ref 或透传 prop 会导致 DOM 断言失败。差距:Icon 在 Label 之前的顺序未经过测试。 | audit:Badge/behavior |
| AR1–AR3 | 源码审查 | 默认、带 Icon | 差距:如果 Badge 添加了自己的 role、Tab 停靠点、实时区域或图标语义,不会有自动化检查失败。 | audit:Badge/a11y |
| FR5 | Badge.test.tsx 中的 data-variant 断言;在浏览器中查看 Badge.stories.tsx 的变体夹具 |
success 和 purple 的映射;所有色调的渲染 |
若这些色调丢失 data-variant,测试将失败。差距:没有自动化检查覆盖 neutral 默认值的映射或任何色调的绘制;绘制变化仅在渲染后的夹具中可见。 |
audit:Badge/theming |
| FR4, AR4 | Badge.test.tsx 完整标签测试套件 |
字符串、数字、富文本和空标签 | 从富文本或空标签设置 title,或对字符串或数字标签省略 title,都会失败。缺口:现有检查未断言被截断的标签在无障碍树中保持完整。 |
audit:Badge/a11y |
| FR1, FR3 | 在浏览器中使用 Badge.stories.tsx 的长标签样例 |
紧凑空间中的长标签 | 标签换行或溢出徽标时,在渲染出的样例中可见。 | audit:Badge/layout |
| FR3 | 在 Core/Badge 的 In layouts 故事上运行 BadgeInLayouts.a11y.chromium.spec.ts |
一个徽标单独位于 Grid 单元格和 VStack 中;一个徽标位于拥挤的 HStack 中 | 徽标的宽度与单元格或栈容器相同、网格或栈中出现被裁切的标签,或徽标溢出所在行、在拥挤的行中显示完整标签,均失败。 | audit:Badge/layout |
| FR6 | extensibleAxes.test.ts、themingTargets.test.ts |
BadgeVariantMap、badge 目标 |
从目标反射或文档的 visualProps 中移除 variant 会导致结构检查失败。缺口:没有测试渲染主题添加的值,因此未使用主题时的回退仅通过源码审查验证。 |
audit:Badge/theming |
| FR8, PR1 | serverSafeComponents.test.ts |
导入图 | 向 Badge 添加 hook 或仅客户端导入会导致服务端安全不变量失败。 | audit:Badge/behavior |
design:bidirectionality DR2 |
MixedDirectionText.a11y.chromium.spec.ts |
https://、.com、+3、@alice、iPhone جديد 和 example.com موقع,分别位于 RTL 与 LTR 下(Mixed Direction 故事) |
在 RTL 下发生弱字符或中性字符重排的标签(//:https、com.、3+、alice@),或带有前导拉丁词且该词按从左到右排版的从右到左文本,会按每个字符的渲染位置判定失败。 |
audit:Badge/layout |
决策日志¶
无记录。该记录描述的是已发布行为。
未决问题¶
- OQ1 — 如何让被截断标签的完整文本触达键盘和触屏用户?(
human-design)可选方案包括:仅在标签被截断时显示一个经过测量的工具提示,这会使 Badge 成为客户端组件并在截断时保持可聚焦;或者将恢复完整文本的工作留给调用方。
内容边界¶
本文件不重复使用方属性表/示例、当前审计结果、实现步骤或组件族/系统规则。它仅链接到这些内容的归属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx