跳转至

Breadcrumbs 组件契约

契约概览

领域 契约
公共契约 带有 children、separator(默认 /)、variant(default、supporting 或增强值;默认 default)和 label 的 Breadcrumbs;目标为带有 variant 的 breadcrumbs。
行为 一个带标签的导航地标,包含一个由 BreadcrumbItem children 组成的有序列表;它会告知自身表面中的每个项要使用的 separator 和 variant。
终端用户影响 屏幕阅读器用户会将这个路径视为名为“Breadcrumb”的地标,并听到它是有序列表;视力正常的用户会在整个路径中看到一致的分隔符和大小。
构建方影响 无。
兼容性/就绪状态 记录已发布行为;无公共变更。
审查检查 拒绝未标记的地标、不是有序列表的路径,或路径自身表面中忽略其 separator 或 variant 的项。
治理规则 component:BreadcrumbItem(每个项);design:bidirectionality DR4(分隔符镜像);architecture:component-theming-surface。

此表是审查投影;以下正文具有权威性。

意图

Breadcrumbs 显示页面在层级结构中的位置。它拥有路径的地标、列表、label、separator 和 variant;每个 crumb 的行为归属于 BreadcrumbItem。消费者的用法见 Breadcrumbs.doc.mjs。

兼容性与迁移

  • 已发布的默认值保留:yes
  • 兼容性分类:记录已发布行为;无公共变更
  • 受控/非受控行为:不适用
  • 迁移决策:无

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

所有权边界

拥有

  • 导航地标、其 label、有序列表、其换行布局,以及自身表面中每个项所接收的 separator 和 variant(FR1–FR4)。

不拥有 / 非目标

  • 每个 crumb 的元素、当前页面状态、separator 渲染、菜单,以及 breadcrumb-item、breadcrumb-item-menu-trigger 和 breadcrumb-menu 目标——由 component:BreadcrumbItem 拥有。
  • 目标位置处理——由 family:navigation-destinations 通过 BreadcrumbItem 拥有。
  • 截断或折叠长路径——未提供;列表会换行。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 属主 稳定性 无效值行为
Variant default、supporting、增强值 每个项的正文或 supporting 文本字号。 整个路径。 default component:Breadcrumbs 稳定 除 supporting 外的值都会让项获得默认字号。
Separator 任意节点;默认 / 显示在每个项(第一个除外)之前的字形。 整个路径。 / component:Breadcrumbs 稳定 按给定值渲染。

行为与布局契约

ID 不变量 依据
FR1 Breadcrumbs 渲染一个由 label 命名的 <nav>,否则使用已翻译的 @astryx.breadcrumbs.label(“Breadcrumb”);调用方的 aria-label 或 aria-labelledby 会替换该名称。它携带带有 variant 的 breadcrumbs、转发的 ref、data-testid 以及其他 DOM props。 当前源码和测试
FR2 <nav> 包含一个持有 children 的 <ol>;该列表没有标记或缩进,并将项按一行排列且可换行。 当前源码和测试
FR3 路径自身表面中的每个后代 BreadcrumbItem 都会收到该路径的 separator 和 variant;在层内渲染的面包屑项则获得默认值,这是 spec:AST-038 FR7 的要求。 当前源码和测试
FR4 className、style 和 xstyle 在组件样式之后合并到 <nav> 上。 当前源码

允许的变化

  • AV1 — 分隔符。 任何节点都可以替换 /。
  • AV2 — 主题样式。 主题按变体重新设置 breadcrumbs 的样式。

代表性状态

状态 必需的不变量 允许的变化
默认轨迹 具名地标;有序列表;/ 分隔符。 项内容。
辅助变体 项使用辅助尺寸。 —
自定义分隔符 项显示给定的分隔符。 字形。
窄容器 项换行到更多行。 行数。

转换与优先级顺序

  • ORD1 — 标签。 调用方的 aria-label 或 aria-labelledby,然后是 label,再然后是翻译后的默认值。

性能与资源

  • 无资源规则。

无障碍契约

  • AR1 — 地标与列表。 FR1 和 FR2:一个具名的导航地标,包含一个有序的面包屑列表。

设计关系

结构或状态 设计需求 表示权威 层级角色 组件契约
轨迹 面包屑组成的可换行行。 当前来源与公开文档 辅助 FR1、FR2
项 一个面包屑。 component:BreadcrumbItem 辅助 FR3
分隔符 轨迹范围内面包屑之间的字形。 component:BreadcrumbItem 辅助 FR3
图标 可选的面包屑起始内容。 component:BreadcrumbItem 辅助 —

尚未记录结构主题映射;该区块在迁移期间是可选的。将四个结构部分与 Breadcrumbs.doc.mjs 列出的四个目标进行映射(其中三个目标由 BreadcrumbItem 通过委托拥有)的工作被推迟。

家族与系统关系

  • component:BreadcrumbItem 渲染每个面包屑及其分隔符。
  • design:bidirectionality DR4 控制默认分隔符的镜像行为,BreadcrumbItem 实现了该行为。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1、AR1 Breadcrumbs.test.tsx 地标测试;Breadcrumbs.a11y.test.tsx 默认和自定义标签 缺少地标或名称将失败。 audit:Breadcrumbs/accessibility
FR2 Breadcrumbs.test.tsx 有序列表测试 多个项 非列表的轨迹将失败。 audit:Breadcrumbs/anatomy
FR3 Breadcrumbs.test.tsx 分隔符与变体测试 默认、自定义分隔符、辅助 忽略轨迹设置的项将失败。 audit:Breadcrumbs/behavior
FR1 Breadcrumbs.test.tsx ref 和 test-id 测试 根属性 丢失的 ref 或 test id 将失败。 audit:Breadcrumbs/api

根据源代码可知,尚没有针对性测试:层内的面包屑获取默认值(FR3);breadcrumbs 目标及其 variant 状态、其他 DOM 属性,以及调用方的 aria-label 或 aria-labelledby 替换名称(FR1);列表的标记、缩进和换行行(FR2);以及 FR4。

决策日志

未记录组件本地的决策。

开放问题

无。

内容边界

本文件不重复使用方属性表、示例或项行为。它提供到其所有者的链接。

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