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 — 有意义的字形。 非空的
labelMUST 将该字形作为具有该无障碍名称的图像暴露。 - AR3 — 父级拥有的交互。 Icon MUST NOT 添加交互语义或焦点行为;交互父级拥有控件及其名称。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 字形 | 以已解析的尺寸和颜色承载已解析的视觉符号。 | 消费者或注册表选择图形资源;Icon 负责呈现。 | 依上下文而定 | FR1, FR2, FR3, FR5 |
Glyph 是两种源码模式中唯一的消费者概念部件。当前实现可能直接渲染提供的图标组件,或将注册表解析出的图标放入内部包装器中;本契约有意不承诺 span、svg 或其他元素类型。
主题解剖结构¶
家族与系统关系¶
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控件映射到smIcon,将lg控件映射到mdIcon。 - 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