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