跳转至

BreadcrumbItem 组件契约

契约概览

领域 契约
公共契约 BreadcrumbItem,包含 children、href、as、onClick、isCurrent、startIcon、menu 和 menuSize;目标为 breadcrumb-item、breadcrumb-item-menu-trigger 和 breadcrumb-menu。
行为 一个面包屑项:一个链接、一个链接样式的按钮、纯文本、当前页面,或同级菜单触发器,由 ORD1 决定。它会渲染自己的装饰性分隔符,在第一个面包屑项上隐藏。当没有其他项声明当前状态时,最后一项成为当前项。
最终用户影响 用户可沿层级向上导航、从面包屑项的菜单打开同级目标,并听到哪个面包屑项是当前页面。
构建方影响 无。
兼容性/就绪状态 记录已发布行为;无公共变更。两个实现缺口:自动当前页面状态在渲染后才应用,且可能落在列表项上(参见“当前状态影响”)。
审查检查 拒绝以下情况:当前项的内容所有者上没有 aria-current="page"(已记录的 <li> 回退除外)、暴露的分隔符、缺少名称/状态/控制链接的菜单,或关闭菜单时抢占有效的外部焦点。
治理规则 component:Breadcrumbs;family:navigation-destinations;family:overlay-dismissal;component:Popover;design:bidirectionality DR4;architecture:react-component-runtime INV1。

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

意图

BreadcrumbItem 在 Breadcrumbs 路径中呈现一个目标、操作、当前位置或同级菜单触发器。消费者用法位于 BreadcrumbItem.doc.mjs。

兼容性与迁移

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

消费者迁移说明应放在消费者文档和发布说明中。

当前状态影响

  • 自动当前状态在渲染后被修复。 当没有面包屑项设置 isCurrent 时,最后一项首次渲染时不带 aria-current,随后一个 Effect 检查 DOM 中的同级列表并添加 aria-current="page"。architecture:react-component-runtime INV1 要求渲染输出从有效状态开始,而不是在后续 Effect 中修复。
  • 自动当前状态可能落在列表项上。 当最后一项通过自定义 as 或 LinkProvider 链接渲染且该链接未转发其 ref 时,自动当前状态修复会将 aria-current="page" 设置在 <li> 上而链接上没有,因此链接不会被宣告为当前页面(FR3、AR2)。

所有权边界

拥有

  • 列表项根元素、根据当前公共输入选择的项内容分支,以及将文档化的项 ref 和 BaseProps 接口转发到该根元素。
  • 为其在路径中的位置渲染的装饰性分隔符容器。
  • 链接样式的操作或菜单触发器,以及 BreadcrumbItem 特有的菜单表面,包括它们当前的主题目标。
  • 当未提供显式菜单尺寸时,从父级 Breadcrumbs 变体推导菜单项尺寸。

不拥有 / 非目标

  • 导航地标、有序列表、路径标签、分隔符值或视觉变体——由 component:Breadcrumbs 通过公共父组件拥有。
  • 目标接受和自定义路由器交接——由 family:navigation-destinations 和共享链接所有者拥有。
  • 通用顶层托管、焦点约束、定位和轻量关闭——由 component:Popover 和 architecture:layer-runtime 拥有。
  • 共享的 Escape/平台关闭顺序——由 family:overlay-dismissal 拥有。
  • 菜单项数据、行语义、选择或子菜单行为——委托给 DropdownMenu 项管线。
  • 调用方提供的图标美术资源或任意子内容。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
项内容 必需的 ReactNode 提供可见的项标签,并可包含调用方拥有的内容。 每个项分支 必需 component:BreadcrumbItem 已发布 React 会渲染所提供的节点。
目标 提供或缺失 href 当项目未显式标记为当前项且没有菜单时,选择共享链接路径。 默认变体和支持变体 缺失 family:navigation-destinations 已发布 共享链接处理逻辑决定接受哪些目标。
操作 提供或缺失 onClick 当未提供目标或菜单时,选择原生链接样式的按钮;当提供了 href 时,则增强链接路径。 非当前项 缺失 component:BreadcrumbItem 已发布 menu 目前会抑制此输入,并在开发环境中发出警告。
当前页 true、false 或省略 true 显式将项目标记为当前项;false 将其排除;省略则使项目成为自动当前项候选。 每个分支,包括菜单触发器 省略 component:BreadcrumbItem 已发布 当没有项目显式标记为当前项时,若最后一个面包屑项省略了该 prop,则会接收 aria-current="page"。
链接渲染器 逐项的 as、provider 渲染器或原生锚点 选择接收已接受目标的组件。 非当前链接路径 provider 渲染器,然后是原生锚点 family:navigation-destinations 已发布 显式当前路径和菜单路径不使用它。
起始内容 提供或缺失 startIcon 在项目标签之前渲染调用方内容。 每个项目分支 缺失 调用方 已发布 调用方内容仍由调用方所有。
同级菜单 数据数组、组合的菜单内容或缺失 用菜单按钮和菜单面板替换链接/操作内容分支。 当前或非当前项目 缺失 component:BreadcrumbItem;菜单行委托 已发布 目前会抑制 href 或 onClick,并在开发环境中发出警告。
菜单尺寸 sm、md 或 lg 选择委托的菜单行尺寸。 菜单分支 支持型 Breadcrumbs 为 sm;否则为 md component:BreadcrumbItem 已发布 TypeScript 拒绝不支持的值。

行为和布局约定

ID 不变量 依据
FR1 项根节点是一个 <li>,承载公共 ref、带有路径变体的 breadcrumb-item 目标、data-testid、样式逃生舱以及其他 DOM props。 已发布的类型、源码、文档和测试;architecture:public-component-api
FR2 具有 href 且无菜单的非当前项使用共享链接渲染器,onClick 位于链接上;仅具有 onClick 的项使用样式化为链接的原生按钮;两者皆无的项渲染为文本内容。 发布的源代码、文档和测试
FR3 显式 isCurrent=true 会将内容渲染为文本(或菜单触发器)并携带 aria-current="page",同时忽略 href 和 onClick;显式为 false 则不参与;当列表中没有项携带 aria-current="page" 时,若列表最后一个子项省略该 prop,则其内容所有者会接收到它(当前状态影响记录会回退到 <li>);最后一个子项设置 isCurrent={false} 的路径没有当前面包屑。 发布的源代码、文档和测试
FR4 每个项都会在其内容之前渲染一个 aria-hidden 分隔容器,第一个项上隐藏该容器。内置的 / 在 RTL 中恰好镜像一次;调用方提供的分隔符按原样渲染。 源代码、聚焦测试和 design:bidirectionality DR4
FR5 菜单项暴露一个带 aria-haspopup="menu"、展开状态和 aria-controls 的菜单按钮,以及一个由触发器标注的 role="menu" 表面,包括非字符串触发器内容。点击、Enter、Space 和 ArrowDown 可打开它并聚焦其第一个项;Escape、Tab 和选择操作可关闭它;方向键在项之间移动且不循环,typeahead 跳转到匹配项。 APG Menu Button 模式、component:Popover、源代码、测试和浏览器证据
FR6 关闭菜单会保留新聚焦的外部控件。仅当关闭表面原本会使焦点无处可去时,焦点才返回触发器。 component:Popover 与浏览器焦点行为
FR7 菜单分支将项渲染、选择、行焦点和子菜单内容委托给共享的 DropdownMenu 项管线,数据来自数组或组合子元素。使用 menu 时,href 和 onClick 会被忽略,并记录一条开发警告。 发布的源代码和聚焦测试
FR8 在进入菜单管道之前,省略的 menuSize 在 supporting 变体下解析为 sm,否则解析为 md。 已发布源码和消费者文档
FR9 本地目标为 <li> 上的 breadcrumb-item、菜单按钮上的 breadcrumb-item-menu-trigger 以及菜单表面上的 breadcrumb-menu;前两者反映面包屑路径的变体。链接、按钮和菜单触发器绘制共享的焦点轮廓。 已发布文档、源码和主题测试
FR10 在打开的菜单中,按下(手指、笔或鼠标)落在已启用的项上并在各项上滑动时,会在抬起的那个项上通过该项自身的激活作用一次,高亮跟随指针;在外部抬起则不作用于任何项,鼠标在外部释放会关闭菜单。菜单为此采用 module:DropdownMenu/useMenuPress(family:action-groups FR1–FR5;module:DropdownMenu/useMenuPress DEC-7)。按在非项的调用方内容上,以及链接项上的 Ctrl-、Cmd- 或 Shift- 点击或中键点击,仍归该内容或浏览器自身处理,键盘和辅助技术行为保持不变。 当前源码和测试
FR11 在 AppShell 移动抽屉内,激活面包屑的链接或按钮会调用 onClick 然后关闭抽屉,除非在链接上使用 Ctrl-、Cmd-、Shift- 或 Alt- 点击会运行 onClick 并让抽屉保持打开以进行下一次操作,除非 onClick 取消了该点击,正如 component:TopNavItem FR5 和 component:SideNavItem FR10 所做;标记为 isCurrent 的面包屑不会导航,因此保持抽屉打开。 与 component:TopNavItem FR5 和 component:SideNavItem FR10 的一致性;缺陷修复

允许的变体

  • AV1 — 链接渲染器。 原生锚点和自定义路由组件可以在 DOM 实现上有所不同,同时保持共享的目标约定。
  • AV2 — 调用方内容。 标签和起始内容可以是任何可渲染的 React 内容;该项拥有周边语义,而非调用方的美工或标记。
  • AV3 — 菜单内容。 数据驱动和组合式内容可以通过委托管道产生操作、分区、分隔线、可选项或子菜单。
  • AV4 — 主题。 当前目标和语义令牌可以改变绘制,而项角色、焦点归属和分支行为保持稳定。

代表性状态

状态 必需不变量 允许的变体
目标链接 共享的链接路径、可见的键盘焦点和接受的目标行为仍然可用。 原生或自定义路由渲染器;可选的起始内容。
操作按钮 原生按钮语义和提供的点击处理仍然可用。 默认或辅助排版。
显式当前项 当前页面状态在渲染的内容所有者上暴露。 纯内容或菜单触发器。
自动当前 当最后一个面包屑省略该 prop 时,仅当不存在显式当前项时,它才会接收当前页面状态。 链接或文本内容保持在其已发布的分支中。
已关闭菜单 触发器暴露 aria-haspopup="menu",控制菜单,并报告折叠状态。 数据驱动或组合的行;当前或非当前触发器。
已打开菜单 命名菜单可在顶层访问,焦点进入其第一个符合条件的行。 行种类、子菜单内容和显式菜单尺寸。
已解除菜单 一次解除即关闭表面;有效的外部焦点被保留,被困焦点返回触发器。 Escape、选择、Tab 或原生轻量关闭。

转换与优先级顺序

  • ORD1 — 内容分支。 首先评估显式当前状态;在当前或非当前任一状态下,menu 选择菜单分支。否则 href 选择链接分支,然后 onClick 选择操作分支,最后保留纯文本内容。
  • ORD2 — 链接渲染器。 逐项的 as 优先于 LinkProvider,后者优先于原生锚点。
  • ORD3 — 菜单尺寸。 显式 menuSize 优先;否则辅助型解析为 sm,而所有其他父级变体解析为 md。

性能与资源

  • PR1 — 委托的层资源。 BreadcrumbItem 不创建独立的全局监听器或观察器;菜单生命周期和焦点资源继续委托给 Popover 和共享菜单 hooks。
  • PR2 — 自动当前状态协调。 当前来源在渲染后通过检查渲染出的兄弟列表来解析省略的当前状态。这是记录在“当前状态影响”下的缺口,而非已批准的实现要求。

无障碍契约

  • AR1 — 轨迹语义。 父级 Breadcrumbs 地标和有序列表拥有聚合的面包屑语义;每个条目仍为一个列表项。
  • AR2 — 当前状态。 当前条目的内容所有者暴露 aria-current="page";列表项包装器不重复该属性。实现缺口:当自定义链接未转发其 ref 时,自动当前状态回退到 <li>(当前状态影响)。
  • AR3 — 原生交互。 链接使用链接语义,仅操作项使用原生按钮,菜单项使用 APG 菜单按钮关系。
  • AR4 — 菜单名称。 菜单表面由其触发器标记,包括可见项内容为非字符串 React 节点的情况。
  • AR5 — 焦点。 键盘焦点在链接和菜单/操作按钮上可见。菜单进入、焦点包含、Escape 返回和外部焦点保留遵循 FR5–FR6。
  • AR6 — 分隔符。 分隔符内容对辅助技术隐藏,同时对视力正常的读者保持方向正确。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
条目根 携带当前排版和 breadcrumb-item 目标。 当前来源与公共文档 辅助 FR1, FR9
链接或操作内容 使用原生语义和共享焦点指示器,而不引入另一个内容目标。 当前来源;architecture:interaction-modality 辅助 FR2, AR3, AR5
当前内容 使用已发布的非颜色文本强调以及当前页面语义。 当前来源与客观非颜色通信 突出 FR3, AR2
分隔符 对辅助技术保持装饰性,并通过上下文 bidi 角色镜像。 客观 bidi 行为 辅助 FR4, AR6
菜单触发器 在原生焦点所有者上绘制菜单触发器目标。 当前来源与公共文档 辅助 FR5, FR9, AR3–AR5
菜单表面 在 Popover 的共享层表面内绘制 breadcrumb-menu 细化。 component:Popover 加上当前 BreadcrumbItem 目标清单 突出 FR5–FR9
起始内容 渲染调用方内容,而不占有其视觉设计或语义。 调用方内容;组合时使用 component:Icon 上下文相关 AV2

家族与系统关系

  • component:Breadcrumbs 提供分隔符和变体。
  • design:bidirectionality DR4 管理内置分隔符的镜像。
  • family:navigation-destinations 负责原生和自定义链接路径的目标检查与交接。BreadcrumbItem 组合共享链接所有者。
  • family:overlay-dismissal 负责最顶层 Escape/平台关闭路由。BreadcrumbItem 通过 Popover 参与。
  • component:Popover 负责通用菜单表面托管、焦点包含和被困焦点返回;BreadcrumbItem 负责其触发器与细化目标。
  • architecture:component-theming-surface 负责目标限定、放置和状态反射。
  • architecture:public-component-api 和 spec:AST-002 负责已发布的 API、优先级、无效状态预防和兼容性审查。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR3, AR1–AR3 Breadcrumbs.test.tsx 分支、test-id 和 current-state 测试套件 链接、操作、显式当前项、省略最后一项 某个分支更改了语义元素、丢失当前状态,或使公共根契约发生偏移。 audit:BreadcrumbItem/api-behavior
FR4, AR6 Breadcrumbs.test.tsx 分隔符、镜像样式类和自定义分隔符测试 内置斜杠、自定义分隔符 上下文分隔符无法恰好镜像一次,或暴露给 AT。 audit:BreadcrumbItem/rtl
FR5–FR8, AR3–AR5 Breadcrumbs.test.tsx 菜单测试套件 字符串和 ReactNode 标签、点击/键盘打开、行、选择、Escape、外部关闭 菜单失去其名称/状态、焦点进入错误的所有者,或关闭行为抢走了有效的外部焦点。 audit:BreadcrumbItem/accessibility-behavior
FR9 Breadcrumbs.test.tsx 主题目标测试;themingTargets.test.ts 项、菜单触发器、菜单表面;默认/支持 目标消失、移入不参与绘制的内部机制,或失去变体体现。 audit:BreadcrumbItem/theming
AR1–AR2 Breadcrumbs.a11y.test.tsx 和 Breadcrumbs.a11y.chromium.spec.ts 轨迹、显式当前项、自动当前项、选择退出 角色、名称、状态或焦点期望发生回归。 audit:BreadcrumbItem/accessibility-behavior
FR10 Breadcrumbs.test.tsx menu-crumb 套件(触摸和鼠标滑动) 触摸和鼠标在各项上滑动 移除该接管行为会使滑动测试失败。 —
FR11 Breadcrumbs.test.tsx 移动端抽屉套件:面包屑链接会关闭抽屉,包括仅凭位置成为当前项的最后一项;标有 isCurrent 的面包屑项则会让抽屉保持打开。 TopNav 和 SideNav 抽屉中的链接与按钮面包屑项;当前面包屑项;抽屉外的面包屑项 抽屉中不带修饰键的面包屑项按下后抽屉仍保持打开、带修饰键点击面包屑链接后抽屉关闭、当前面包屑项按下后抽屉关闭,或抽屉外面包屑项按下后抽屉关闭,均会导致失败。 —

从源码阅读到,尚无专项测试:

  • FR1:<li> 上的项 ref 和其他 DOM 属性。
  • FR3:最后一项带有 isCurrent={false},导致轨迹中没有当前项。
  • FR4:内置斜杠在 RTL 布局中恰好镜像一次。
  • FR5:Enter 和 Space 打开菜单,点击聚焦第一行,Tab 关闭菜单,方向键在两端停止而不会循环,以及 typeahead 行为。
  • FR7:menu 存在时 onClick 会被忽略。
  • FR8。
  • FR9:链接、按钮和菜单触发器上的共享焦点轮廓。

决策日志

没有记录任何组件本地决策。

开放问题

  • OQ1 — 冲突的交互属性。 已发布的 menu + href 或 menu + onClick 组合是否应继续采用基于警告的优先级,还是应通过兼容性计划使其不可表示?(human-api)
  • OQ2 — 自动当前项的归属。 省略 isCurrent 时是否仍应将其作为自动检测的当前项候选;如果是,应使用哪种 React 管理的机制来替代渲染后的 DOM 协调?(human-api)

内容边界

本文件不重复消费者 prop 表、菜单项 API、审计分数、运行证据、截图、实现步骤,或共享的导航、层级、关闭和主题规则。它链接到这些内容的所属文档。

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