跳转至

Icon 组件契约

意图

Icon 以一致的尺寸、颜色和无障碍语义呈现一个视觉符号。消费者用法仍记录在 Icon.doc.mjs 中。

兼容性与迁移

  • 已发布默认值保留:对于显式尺寸和独立 Icon,保留为 yes
  • 兼容性类别:组件自有的 Icon 插槽可以提供上下文默认值;显式 Icon 尺寸和独立的 md 回退保持不变
  • 受控/非受控行为:不适用
  • 迁移决策:无需消费者迁移;当所属 Astryx 组件应选择上下文默认值时,省略 size

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 接受语义图标键或提供的图标组件作为字形来源。
  • 将解析后的尺寸和条目可接收的变体传递给注册表条目。
  • 解析显式、组件自有的上下文以及独立的尺寸默认值。
  • 将 Icon 的尺寸、颜色、主题目标和无障碍语义应用于渲染的字形。

不拥有 / 非目标

  • 共享注册表的键解析和回退顺序——由共享图标系统拥有。
  • 所属 Astryx 组件为其图标插槽选择哪个上下文默认值——由该组件或家族契约拥有。
  • 字形在产品上下文中的含义,或附近的文本是否使其成为装饰性元素——由产品调用点拥有。
  • 交互、焦点或控件命名——由交互式父级拥有。
  • 由消费者提供或通过主题注册的图形资源。
  • 公共 Icon 尺寸提供方 API;上下文传输是实现细节。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
字形来源 语义键、带命名空间的扩展键或图标组件 选择视觉符号。 每次渲染 必需 component:Icon 稳定 TypeScript 拒绝不支持的内置字符串值。
尺寸 xsm、sm、md、lg 选择图标盒子尺寸。 每个渲染的字形 最近的组件自有默认值;否则为 md component:Icon 稳定 TypeScript 拒绝不支持的值。
颜色 已记录的语义值和调色板值 选择字形颜色或从上下文中继承。 每个渲染的字形 inherit component:Icon 稳定 TypeScript 拒绝不支持的值。
无障碍 装饰性或带有意义的标签 控制辅助技术是否接收该字形。 每个渲染的字形 装饰性 component:Icon 稳定 空标签使用装饰性行为。
变体 IconVariantMap 中的名称;活动主题列出自己的名称 为注册表字形请求主题的替代图形。 仅注册表字形;绝不应用于提供的组件 无 component:Icon 稳定 TypeScript 拒绝未知名称;未列出的变体渲染正常图形。

当前无法解析的带命名空间的键不会渲染任何内容。这是现有行为,并非有意的回退承诺。

行为与布局契约

需求标识其依据,以免观察到的代码被误认为是有意的决策。

ID 候选不变量 依据 草案审查状态
FR1 Icon MUST 从提供的语义键、带命名空间的键或图标组件中最多呈现一个字形。 已记录的承诺和当前测试。 意图已确定。
FR2 每个渲染的字形 MUST 携带 icon 主题目标,并将其解析后的大小和所选颜色作为目标数据反映。 当前源码、文档和主题测试。 意图已确定。
FR3 Icon MUST 将解析后的大小作为每个字形的宽度和高度应用,并在基于 1em 的图标源需要时附加字体大小。该尺寸契约 MUST NOT 承诺 HTML 或 SVG 元素类型。 人工决策、当前源码和测试。 意图已确定。
FR4 受支持的 SVG 和样式逃逸出口 MUST 保留其既定的合并和覆盖行为。 当前源码和回归测试。 当前兼容行为;更改前需验证。
FR5 显式的 Icon size MUST 优先生效。若未提供,Icon MUST 使用所属 Astryx 组件为其文档记录的图标插槽提供的最近默认值;若无此类默认值,Icon MUST 使用 md。 组件大小优先级和 Button 尺寸决策。 意图已确定。
FR6 在注册表模式中,Icon MUST 将 {size, variant} 传递给选中的条目,其中 size 是 ORD1 解析后的大小,variant 是请求的变体(当激活的主题列出该变体,且对于主题提供的条目,定义该条目的主题也列出该变体时),否则为 undefined。提供的图标组件 MUST NOT 接收 variant,Icon MUST NOT 将 variant 转发到 DOM,且 icon 目标 MUST NOT 反映它。 spec:AST-087 FR1–FR5 和 FR9。 意图已确定。
FR7 icon 目标 MUST 在其 size:* 选择器上保证 width 和 height,作为经评审的特定目标补充,从而让主题为每个尺寸设置维度。没有主题样式时,尺寸在根字号为 16px 时为 12、16、20 和 24px,并随根字号缩放。 spec:AST-087 FR10。 意图已确定。
FR8 对于每个名称,ref 都指向解析后的字形所渲染的 svg;当字形不渲染 svg 时,ref 为 null。之后替换自身 svg 的字形不会被追踪。 与 Icon 的公共 ref 类型 Ref<SVGSVGElement> 保持一致;缺陷修复。 意图已确定。

允许的变化

  • AV1 — 图稿. 路径、视图框和内部结构可随图标源或主题而变化,而不改变 Icon 的单部分消费者结构。
  • AV2 — 渲染策略. Icon 可以直接渲染提供的图标组件,也可以为解析后的键使用内部包装器;这两种元素形态都不是公共结构。
  • AV3 — 主题与消费者样式. 现有的主题和样式逃逸出口可以更改视觉 CSS 属性,而不改变字形所有权。
  • AV4 — 上下文映射. 所属 Astryx 组件可将其自身的公共大小或变体映射到 Icon 默认值。该映射属于所属组件,且 MUST 保留显式 Icon 大小和独立回退值。

代表性状态

状态 必需不变式 允许的变化
语义键 一个已解析的字形携带 icon 目标。 主题、注册表或内置图形资源。
命名空间扩展键 已解析的扩展字形携带 icon 目标。 消费者或库拥有的图形资源。
提供的图标组件 提供的字形携带 icon 目标。 组件实现与 SVG 内部细节。
没有 size 的独立 Icon 解析后的尺寸为 md。 字形来源与颜色。
没有 size 的所属图标插槽 使用最近的文档化组件默认值。 所属组件声明的尺寸映射。
所属插槽中的显式 Icon 尺寸 显式 Icon 尺寸优先于上下文默认值。 任何受支持的 Icon 尺寸。
未解析的命名空间键 当前不渲染任何字形。 按意图不建立任何回退行为。
已列出的变体 当定义该条目的主题也列出相应变体时,条目接收尺寸和变体。 主题针对该请求的图形资源。
未列出或省略的变体 条目接收 variant: undefined。 主题的正常图形资源。
提供的组件上的变体 组件按原样渲染,不包含 variant。 组件实现。

转换与优先级顺序

  • ORD1 — 尺寸解析。 解析显式 Icon size → 最近的组件所属上下文默认值 → 独立 md 回退。
  • ORD2 — 呈现。 应用目标、已解析尺寸和组件颜色样式,然后按既定顺序合并消费者的 xstyle、className、内联 style 以及受支持的透传 props。

性能与资源

  • PR1 — 渲染工作。 Icon 不拥有监听器、观察器或布局测量;语义和尺寸解析在渲染期间同步完成。

无障碍契约

  • AR1 — 装饰性默认行为。 如果没有非空的 label,Icon MUST 默认对辅助技术隐藏其字形。
  • AR2 — 有意义的字形。 非空的 label MUST 将该字形作为具有该无障碍名称的图像暴露。
  • AR3 — 父级拥有的交互。 Icon MUST NOT 添加交互语义或焦点行为;交互父级拥有控件及其名称。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
字形 以已解析的尺寸和颜色承载已解析的视觉符号。 消费者或注册表选择图形资源;Icon 负责呈现。 依上下文而定 FR1, FR2, FR3, FR5

Glyph 是两种源码模式中唯一的消费者概念部件。当前实现可能直接渲染提供的图标组件,或将注册表解析出的图标放入内部包装器中;本契约有意不承诺 span、svg 或其他元素类型。

主题解剖结构

{
  "Glyph": {"target": "icon"}
}

家族与系统关系

  • architecture:component-size-cascade 拥有共享的“显式 → 最近提供者 → 组件回退”模式,并要求声明提供者所有权。Icon 保留自己的 xsm | sm | md | lg 轴,位于标准元素尺寸级联之外,并对组件所属默认值采用该优先级。
  • architecture:component-theming-surface 拥有 icon 目标的限定和验证规则。
  • architecture:icon-resolution-and-component-slots 在 Icon 渲染所选来源之前,拥有语义键和组件插槽的解析。
  • spec:AST-087 决定 variant 请求、主题列出的变体名称以及主题设置的尺寸维度。
  • architecture:public-component-api 拥有 Icon 公共 props 和可观察默认值的准入与兼容性规则。
  • 所属组件或组件族指定每个上下文相关的 Icon 尺寸映射。Button 组件族目前将 sm 和 md 控件映射到 sm Icon,将 lg 控件映射到 md Icon。
  • Icon 目前没有组件族契约。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1, FR3, FR5 Icon.test.tsx 尺寸测试套件与 IconButton.test.tsx 上下文尺寸测试套件 独立默认;Button 尺寸;显式覆盖;两种模式 若破坏源渲染、独立回退、上下文映射、显式优先级或跨模式尺寸,断言将失败。 audit:Icon/behavior
FR2, FR4 Icon.test.tsx 主题目标反映与样式属性测试套件 两种源模式;每种颜色和尺寸;省略颜色;className、style 和 xstyle 移除目标、在任一模式下丢失 data-color 或 data-size,或破坏覆盖组合,断言将失败。 audit:Icon/theming
FR2, FR3(渲染) IconAudit.a11y.chromium.spec.ts 传感器回执 语义键与图标组件;每种尺寸和颜色;浅色和深色下的 Neutral 与 Butter;从右到左;320px 若字形缺少其目标数据、颜色未绘制其令牌、Neutral 主题下的尺寸未按 12、16、20 和 24px 递增、注册表图形未填满其盒子,或字形被变换,则回执失败。 audit:Icon/theming
AR1, AR2, AR3 Icon.test.tsx 无障碍名称测试套件与 IconAudit.a11y.chromium.spec.ts 无障碍名称回执 装饰性、带标签、显式 ARIA 覆盖;会写入自身 aria-hidden 的带标签图标组件 更改默认或带标签语义,或在带标签字形上保留组件自身的 aria-hidden,都会导致无障碍断言失败。 audit:Icon/accessibility
FR6 Icon.test.tsx 变体测试套件 列出的、未列出的与省略的变体;无活动列表;被替换列表下的继承条目;提供的组件 未列出的变体,或其定义主题未列出的变体,到达某个条目;或者 variant 到达提供的组件或 DOM。 audit:Icon/behavior
FR7 Icon.test.tsx 主题尺寸维度测试套件 每种尺寸在有和无主题样式下,两种源模式 主题化尺寸不改变字形尺寸,或未设置主题的尺寸发生变化,则断言失败。 audit:Icon/theming
FR8 Icon.test.tsx 的“ref 为每个名称到达渲染后的 svg”测试套件 图标组件;语义名称;带命名空间的键;文本字形;字形变更(组件到组件、svg 到文本);跨重渲染的函数条目;卸载 对于任何名称类型,ref 保持为空,或持有的不是渲染后的 <svg>,都会失败;以下情况同样失败:文本字形上的非空 ref、被替换字形上遗留的 ref、每次重渲染都会重新附加的 ref,以及卸载后仍保持设置的 ref。 audit:Icon/ref
主题解剖映射 scripts/check-knowledge.mjs 标准消费方结构与当前目标 缺失、多余、带前缀或过期的映射无法通过仓库验证。 audit:Icon/theming

决策日志

DEC-1 — 跨源模式的单一概念 Glyph

参考: component:Icon/DEC-1 决策者: cixzhang, 2026-08-30

无论视觉符号来自语义键还是提供的组件,使用方都会以同一个视觉符号来设置主题并进行理解。因此,Glyph 映射到现有的 icon 目标,同时不固化任一模式当前的元素形态。Icon 为每个来源应用宽度和高度,并在基于 1em 的来源需要时添加字号。这保持了一个一致的图标盒子,同时不承诺 span、svg 或其他元素。

已否决:将 wrapper 与 SVG anatomy 各自单独成条目,因为那些描述的是实现策略,而非稳定的消费者概念。

DEC-2 — 拥有方组件可提供上下文相关的 Icon 默认值

引用: component:Icon/DEC-2 决策者: cixzhang, 2026-09-23

用户应看到与拥有该 slot 的 Astryx 组件成比例的图标,而无需每个调用方重复指定尺寸。因此,拥有该 slot 的组件可以提供默认值,而显式指定的 Icon 尺寸仍具有最高优先级,独立使用的 Icon 保持 md。Provider 对象、hooks 和 context 形态仍然是私有实现细节,而非公开 API。

已否决:在每个组合中无条件使用 md 默认值,迫使每个调用方重复指定由拥有方推导出的尺寸,并将 provider 机制暴露为公开 API。

未决问题

无。

内容边界

本文件不重复面向消费者的 prop 表/示例、当前审计结果、实现步骤或系统规则,而是链接到这些内容的归属方。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx