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:bidirectionalityDR4 控制默认分隔符的镜像行为,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