NavIcon 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | NavIcon 需要必需的 icon;目标为 nav-icon。 |
| 行为 | 一个仅展示的圆形强调色容器,中等元素尺寸的正方形,用于显示调用方的图标。 |
| 最终用户影响 | 用户在导航标题中看到一致的产品标识;NavIcon 除了调用方的图标外,不会向可访问性树添加任何内容。 |
| 构建方影响 | 无。 |
| 兼容性/就绪度 | 记录已发布行为;无公共变更。 |
| 审查检查 | 拒绝发出除 nav-icon 之外的任何目标,或拒绝向容器添加交互语义。 |
| 治理规则 | architecture:component-theming-surface;architecture:public-component-api。 |
此表是审查投影;下文正文具有权威性。
意图¶
NavIcon 在圆形导航容器内渲染调用方提供的图标内容,通常作为 TopNavHeading 或 SideNavHeading 的徽标。消费者用法见 NavIcon.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;容器仅发出标准
nav-icon目标 - 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 圆形容器及其当前的
nav-icon主题目标。
不拥有 / 非目标
- 通过
icon提供的图标图形或组件——由调用方拥有,包括其可访问名称或装饰状态。 - 交互语义——NavIcon 仍是仅展示容器。
- 标题在 NavIcon 周围应用的间距——由
component:TopNavHeading和component:SideNavHeading拥有。
公共概念¶
除消费者 props 外,没有组件本地概念。
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | NavIcon 渲染一个 <span> 圆形容器,居中,两个轴均按 --size-element-md 设置尺寸,使用强调色和强调前景色绘制,其中包含 icon。 |
当前源代码、文档和测试 |
| FR2 | 该容器仅携带标准 nav-icon 目标。 |
当前源代码、文档和测试 |
| FR3 | 该容器转发其 ref、data-testid 及其他 DOM props,并在组件样式之后合并 className、style 和 xstyle。它不添加任何 role、name 或焦点停靠点。 |
当前源代码和测试 |
允许的变化¶
- AV1 — 图标图形。 调用方提供的图标图形和实现可以变化,而不会成为 NavIcon 所拥有的构成部分。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 任意图标 | 相同的圆形容器和目标。 | 图标图形。 |
转换与优先级顺序¶
- 无优先级规则。
性能与资源¶
- 无资源规则。
可访问性契约¶
- AR1 — 透明容器。 NavIcon 不贡献任何语义;调用方的图标决定辅助技术感知到的内容(FR3)。
设计关系¶
| 构成或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 容器 | 呈现圆形强调色绘制表面。 | 当前源代码和公共文档 | 支持性 | FR1, FR2 |
| 图标 | 呈现调用方提供的视觉内容。 | 调用方提供的内容 | 取决于上下文 | FR1 |
主题构成¶
组件族与系统关系¶
architecture:component-theming-surface拥有该目标及其限定。architecture:public-component-api拥有转发输入如何组合。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR3 | NavIcon.test.tsx 内容、ref 和 test-id 套件 |
调用方提供的图标 | 移除容器、内容、ref 或 test id 将导致失败。 | audit:NavIcon/anatomy |
| FR2 | NavIcon.test.tsx 目标名称套件;themingTargets.test.ts |
规范目标类 | 如果规范目标缺失或被重命名,或者移除了 navicon 别名,目标断言将失败;额外目标会导致 themingTargets.test.ts 失败。 |
audit:NavIcon/theming |
| 主题解剖映射 | scripts/check-knowledge.mjs |
规范解剖结构和当前目标 | 缺失、多余、带前缀、过期或由别名支持的映射会导致仓库验证失败。 | audit:NavIcon/theming |
从源码读取,且目前尚无聚焦测试:容器的圆形形状、大小和强调色(FR1);以及其他 DOM 属性、className、
style 和 xstyle 的合并,以及缺少 role、name 或焦点停留点
(FR3)。
决策日志¶
未记录任何组件局部决策。
未决问题¶
无。
内容边界¶
本文件不重复使用者属性表、示例、实施步骤或系统规则。它链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx