跳转至

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

主题构成

{
  "Container": {"target": "nav-icon"},
  "Icon": {"inherits": "nav-icon"}
}

组件族与系统关系

  • 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