跳转至

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