跳转至

SideNavSection 组件契约

契约概览

领域 契约
公共契约 SideNavSection,包含 title、subtitle、endContent、isHeaderHidden 和 children;目标为 side-nav-section。
行为 一组带有标签的 SideNav 项。当设置了 isHeaderHidden 或导航轨折叠时,其标题在展开的导航轨中可见,在视觉上隐藏但仍可被读取。
最终用户影响 屏幕阅读器用户在任何导航轨状态下都能听到每个组的标题;视力正常的用户只能在展开的导航轨中看到分区标题。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公开变更。一个实现差距(参见当前状态影响)。
审查检查 拒绝没有由标题命名的 role="group" 的区段,或拒绝从无障碍树中移除的隐藏标题。
治理规则 architecture:public-component-api INV5–INV6;architecture:component-theming-surface。

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

意图

SideNavSection 将相关的 SideNav 项分组到一个标题下。它负责该组的语义及其标题的可见性。消费者用法见 SideNavSection.doc.mjs。

兼容性与迁移

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

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

当前状态影响

  • 隐藏的标题保持其末尾内容可聚焦。 当标题在视觉上隐藏时(isHeaderHidden 或折叠的导航轨),放在 endContent 中的控件会保留在 Tab 键顺序中,同时被裁剪到视线之外,因此键盘用户会落在一个他们看不到的控件上。WCAG 2.4.7 要求可见焦点。OQ1 询问隐藏的标题是否渲染 endContent。

所有权边界

拥有

  • 组元素、其名称、标题可见性和根样式(FR1–FR4)。

不拥有 / 非目标

  • 项的渲染和嵌套——由 component:SideNavItem 和 component:SideNav 拥有。
  • 放置在 endContent 中的交互式内容——由该内容本身拥有。

公共概念

除了消费者 props 之外,没有组件局部的概念。

行为与布局契约

ID 不变量 依据
FR1 根元素是一个 div,带有 role="group" 和指向标题的 aria-labelledby。它承载 side-nav-section、转发的 ref、data-testid 和其他 DOM props;这些属性不能覆盖 role 和标签。 当前源码与测试
FR2 标题显示标题文本、可选的副标题,以及在内联末尾的 endContent,后面跟着各项。 当前源码与测试
FR3 当 isHeaderHidden 为 true 或导航轨折叠时,标题在视觉上隐藏但仍保留在无障碍树中,因此组保持其名称。 当前源码与测试
FR4 className、style 和 xstyle 在组件样式之后合并到根元素上。 当前源码与测试

允许的变体

  • AV1 — 标题内容。 副标题和末尾内容可以不存在。

代表性状态

状态 必需不变量 允许的变体
展开的导航轨 可见标题;有名称的组。 末尾内容。
标题隐藏 隐藏的标题仍为组提供名称。 —
折叠的导航轨 隐藏的标题仍为组提供名称。 —

转换与优先级顺序

  • 无优先级规则。

性能与资源

  • 无资源规则。

无障碍契约

  • AR1 — 有名称的组。 FR1 和 FR3。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
标题区 标题、副标题、尾端内容。 当前源码与公共文档 辅助 FR2, FR3

SideNavSection.doc.mjs 没有声明自己的结构,因此没有记录结构主题化映射。

家族与系统关系

  • component:SideNav 在其列表中承载区段。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1, FR2, FR4 SideNav.test.tsx SideNavSection 套件 Title, subtitle, end content, props 丢失 role、name 或转发的 prop 会导致失败。 audit:SideNavSection/accessibility
FR3 SideNav.test.tsx 隐藏 section 标题测试 header 被隐藏 从树中移除 header 会导致失败。 audit:SideNavSection/accessibility
RTL 关系 RTL 审计精选的 D2 目标(apps/storybook/rtl-audit/targets.json),针对 SideNav / Section / End content Section 标题和 end content;LTR 和 RTL 标题若不在 end content 的 inline start 处,则 D2 失败。 audit:SideNavSection/i18n-rtl

以上内容从源码读取,尚无聚焦测试:转发的 ref、side-nav-section 目标,以及优先于调用方 props 的 role 和 label(FR1);header 的部件顺序与 end 放置(FR2);在折叠的 rail 中隐藏 header(FR3);以及根元素上的 xstyle(FR4)。

决策日志

未记录任何组件级决策。

未决问题

  • OQ1 — 隐藏的 header 是否渲染 endContent?(human-api)目前会渲染,因此其中的控件在隐藏状态下仍可聚焦(当前状态影响)。

内容边界

本文件不重复消费者 prop 表或示例,而是链接到其所有者。

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