Outline 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | items, activeId, onActiveIdChange, label, density, onNavigateStart, onNavigateEnd, offset, scrollContainerRef, hasScrollOnClick, 根 BaseProps, ref。 |
| 行为 | 一个带标签的同页标题链接导航列表,支持键盘移动、滚动跟踪当前标题,以及滑动指示器。 |
| 最终用户影响 | 用户可以看清自己在长页面中的位置,并通过指针或键盘跳转到任意标题,落在固定页眉下方。 |
| 构建者影响 | 构建者显式提供的 aria-label 本应用于命名导航;目前 label 或本地化默认值会替换它(FR1 差距)。 |
| 兼容性/就绪状态 | 已发布行为记录为当前行为;无 API、默认值或输出变更。四个实现差距列在“当前状态影响”下。 |
| 审查检查 | 拒绝被排除在 Tab 顺序之外的链接、未经命名例外而添加的箭头键移动、指向缺失目标的死链接、触发两次的回调,或丢失的焦点轮廓。 |
| 治理规则 | architecture:interaction-modality;architecture:component-theming-surface;architecture:public-component-api INV5–INV8;spec:AST-020 FR15;design:reduced-motion DR1–DR3;WCAG 2.2 SC 1.3.1、2.1.1、2.4.3、2.4.7。 |
此表是审查投影;以下正文具有权威性。
意图¶
Outline 提供同页标题导航:带标签的标题链接、垂直指示器轨道,以及跟随读者当前所在标题滑动的活动指示器。标题归文档所有。
消费者语法和示例属于 Outline.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes— 本地化的“目录”标签、默认密度、无偏移、最近的滚动祖先(否则为窗口)作为滚动根、点击时平滑滚动。 - 兼容性类别:记录已发布行为;无公共属性、默认值、DOM、目标或样式输出变更。
- 受控/非受控行为:当前标题通过
activeId和onActiveIdChange受控,或非受控并通过滚动跟踪。 - 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 调用方的
aria-label被替换(FR1)。 调用方 props 在组件的aria-label之前展开,因此调用方的aria-label会被label或本地化默认值替换;只有labelprop 能为导航命名,而architecture:public-component-apiINV5 允许调用方的显式输入到达元素。 - 导航后焦点仍停留在 Outline 上(FR4)。 激活链接会滚动到该章节,但焦点仍留在链接上,因此下一次按 Tab 会移过 Outline,通常回到内容顶部附近,而不是进入所选章节;而原生页内链接会移动顺序焦点的起始点(WCAG 2.2 SC 2.4.3)。
- 减弱动效下指示器仍会滑动(FR6)。 指示器的移动和大小调整过渡没有减弱动效分支,而
design:reduced-motionDR1–DR3 要求在精细指针上立即变化,在粗略指针上以 200 ms 或更短时间交叉淡入淡出。 - 减弱动效下导航仍平滑滚动(FR4)。 激活链接后始终平滑滚动到标题,而
design:reduced-motionDR1–DR3 要求组件启动的滚动在精细指针上立即落定,在粗略指针上以 200 ms 或更短时间交叉淡入淡出。
所有权边界¶
拥有
- 导航地标及其
outline目标、列表、标题链接及其outline-item目标、标签、指示器轨道,以及活动指示器及其outline-indicator目标。 - 列表内的键盘焦点、滚动跟踪、点击与键盘导航,以及导航回调。
不拥有 / 非目标
- 目标标题及其内容 — 归文档或产品调用方所有。
- 从 markdown 构建
items— 归module:Outline/parseOutlineFromMarkdown所有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Items | {id, label, level} 列表 |
按顺序排列的标题,标题级别为 1–6。 | 始终 | — | 调用方 | 稳定 | 级别会被限制为四层缩进。 |
| 当前标题 | 受控的 activeId;滚动追踪 |
标记为当前的标题。 | 始终 | 滚动追踪 | component:Outline |
稳定 | — |
| 标签 | string | 导航的无障碍名称。 | 始终 | 本地化默认值 | component:Outline |
稳定 | — |
| 密度 | default;compact |
链接内边距。 | 始终 | default |
component:Outline |
稳定 | 封闭联合;会被类型系统拒绝。 |
| 滚动范围 | offset;scrollContainerRef;hasScrollOnClick |
激活线和落点偏移;被滚动的容器(否则为最近的滚动祖先,否则为窗口);点击是否触发滚动。 | 始终 | 0;最近的滚动祖先;true |
component:Outline |
稳定 | — |
| 导航事件 | onNavigateStart;onNavigateEnd |
在链接导航开始以及其滚动落定时触发。 | 始终 | 无 | 调用方 | 稳定 | — |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | Outline 渲染一个承载 outline 目标的 nav,该 nav 反映 density,由 label 或本地化的“目录”命名,包含一个由 li 项组成的 ul(role="list"),每一项都有一个指向 #<id> 的链接,其标签以省略号截断;随后是一个 aria-hidden 指示器轨道和一个 aria-hidden 活动指示器。调用方显式提供的 aria-label 会传递到该 nav(architecture:public-component-api INV5)。实现差距:组件自身的 aria-label 会替换它(当前状态影响)。 |
当前源码与测试 |
| FR2 | 每个链接都带有 outline-item 目标,该目标反映 level,并且对于当前标题还反映 active;当前链接具有 aria-current="location"、主要文本颜色和半粗体字重。标题级别 1 和 2 共享第一个缩进,级别 3、4 和 5–6 分别采用第二、第三和第四个缩进。 |
当前源代码和测试 |
| FR3 | 每个链接都处于正常的 Tab 顺序中,除非本记录指定了例外(spec:AST-020 FR15),否则 Outline 不会在链接之间添加箭头、Home 或 End 移动;Tab 会在最后一个链接之后离开列表。 |
当前源代码和测试;spec:AST-020 FR15;WCAG 2.2 SC 2.1.1 |
| FR4 | 当链接的目标存在时,单击、回车或空格会将 #<id> 推入历史记录,并平滑滚动到该标题:当 offset 为 0 时,每个可滚动祖先(包括窗口)都会将标题滚动到顶部;当 offset 非零时,只有滚动根(scrollContainerRef,否则为最近的可滚动祖先,否则为窗口)进行滚动,最终使标题顶部位于滚动根顶部之下 offset 像素加上标题自身滚动边距的位置;onNavigateStart 在导航开始时触发,onNavigateEnd 在滚动稳定或读者通过手动滚动中断时恰好触发一次;如果没有滚动结束事件,则回退到超时;第二次导航会立即结束第一次导航;在滚动中途 Outline 卸载后,onNavigateEnd 不会触发。在减弱动态效果下,导航滚动不会移动:在精细指针上它会立即落定(design:reduced-motion DR3),在粗略指针上则会在 200 毫秒或更短时间内交叉淡入淡出(DR2)。当 hasScrollOnClick={false} 时,不会发生滚动:哈希被推入,标题被标记为当前,onNavigateEnd 立即触发。对缺失目标单击或回车,或任何修饰键组合,都留给浏览器处理;对缺失目标按空格键则不做任何事。跟随链接会将顺序焦点起点移动到目标位置,就像原生页内链接一样(WCAG 2.2 SC 2.4.3)。实现差距:在减弱动态效果下滚动也是平滑的;并且焦点停留在 Outline 链接上,因此下一次 Tab 会从 Outline 之后继续,而不是进入所选章节内部(当前状态影响)。 |
当前源代码和测试 |
| FR5 | 在非受控模式下,当前标题跟随读者在滚动根(scrollContainerRef,否则为最近的可滚动祖先,否则为窗口)中的滚动位置,使用一条按 offset 偏移的激活线以及每个标题自身的滚动边距;在任何标题越过该线之前,第一个标题为当前标题;一旦滚动根到达其末尾,最后一个标题即为当前标题;单击会在滚动稳定后将其标题标记为当前。在非受控模式下,onActiveIdChange 报告当前标题的每次变化(来自滚动或单击);在受控模式下,Outline 不跟踪滚动,由 activeId 决定,onActiveIdChange 报告单击所选择的标题。键盘焦点移动和组件自身的导航滚动不被视为手动滚动。 |
当前源代码和测试 |
| FR6 | 活动指示器是一条 2px 的 --color-icon-primary 条,位于内联起始处的 2px --color-border 轨道上,通过 CSS 锚点定位相对于当前链接放置,并以快速的标准过渡动画移动。在减少动效模式下,指示器不会移动:在精确指针上它会立即变化(design:reduced-motion DR3),在粗略指针上它会在 200 毫秒或更短时间内交叉淡入淡出(DR2)。实现差距:过渡没有减少动效分支,因此指示器仍然会滑动(当前状态影响)。 |
当前源码和测试 |
| FR7 | 键盘聚焦的链接在所有受支持的上下文中显示共享的焦点轮廓。 | 当前源码;浏览器证据;architecture:interaction-modality |
| FR8 | ref、DOM、data 和事件属性、xstyle、className 和 style 会传递到或组合在 nav 上;data-testid 会传递到它。 |
当前源码和测试;architecture:public-component-api INV5–INV8 |
允许的变化¶
- AV1 — 标题。 标题数量、标签、级别以及当前标题可以变化,而不改变组件结构。
- AV2 — 密度。 默认密度和紧凑密度使用相同的结构和目标。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 非受控滚动 | 当前标题跟随滚动而变化;onActiveIdChange 会报告它。 |
偏移量。 |
| 受控 | 由 activeId 决定;点击通过 onActiveIdChange 报告。 |
— |
| 键盘 | Tab 依次访问每个链接;Enter 和 Space 进行导航;方向键、Home 或 End 均不产生移动。 | — |
| 缺少目标 | 点击或按 Enter 时行为与普通链接相同;Space 不执行任何操作;不触发任何回调。 | — |
| 空状态 | 轨道和指示器仍会渲染;没有链接,因此没有 Tab 停靠点。 | — |
转换与优先级顺序¶
- ORD1 — 当前标题。 受控的
activeId→ 滚动位置。 - ORD2 — 激活。 修饰键组合,或在缺失目标上点击或按 Enter → 浏览器默认行为;在缺失目标上按 Space → 无操作;否则推入 hash、滚动并触发回调。
性能与资源¶
- PR1 — 滚动跟踪。 非受控状态下,Outline 在挂载期间监听其滚动根上的滚动事件;导航等待滚动结束,并带有超时回退;Outline 安装共享的按压控制器。
无障碍契约¶
- AR1 — 导航地标。
nav由调用方显式提供的aria-label命名,否则由label或本地化默认值命名(FR1 缺口),并且列表和列表项保持列表语义(WCAG 2.2 SC 1.3.1)。 - AR2 — 当前位置。 当前链接暴露
aria-current="location";指示器和轨道对辅助技术隐藏。 - AR3 — 链接按 Tab 顺序获得真实焦点。 每个链接通过正常的 Tab 顺序接收键盘焦点,并保持真实的 DOM 焦点,而不是
aria-activedescendant(spec:AST-020FR15)。
设计关系¶
| 结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Outline | 将标题导航和指示器分组。 | 当前源码和文档 | 辅助 | FR1 |
| Heading link | 导航到某个标题,并携带层级和激活状态。 | 当前源码和文档 | 突出 | FR2–FR4 |
| Label | 链接内的标题文本,用省略号截断。 | 当前源码和文档 | 突出 | FR1, FR2 |
| Indicator track | 活动标记后面的垂直轨线。 | 当前源码和文档 | 辅助 | FR6 |
| Active indicator | 与当前链接对齐的标记。 | 当前源码和文档 | 辅助 | FR6 |
Label 位于 outline-item 目标内部,并继承其文本样式。Indicator track 的目标暴露尚未确定(OQ2)。
主题化结构¶
{
"Outline": {"target": "outline"},
"Heading link": {"target": "outline-item"},
"Label": {"inherits": "outline-item"},
"Indicator track": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
},
"Active indicator": {"target": "outline-indicator"}
}
族系与系统关系¶
module:Outline/parseOutlineFromMarkdown从 markdown 构建items。architecture:interaction-modality负责焦点指示;FR7 应用该指示。architecture:component-theming-surface负责目标映射、继承的部件和未决处置。architecture:public-component-api负责调用方输入路由;FR1 记录aria-label缺口,FR8 应用其余部分。spec:AST-009负责无障碍树证据;验证映射标明了其缺口。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | Outline.test.tsx labelled-nav、default-label、class 和 track 测试;稳定的视觉基线 core-outline--basic(中性主题和探针主题) |
条目;默认标签;轨道和指示器 | 缺少 nav 名称、链接或指示器,或丢失 outline 类,均视为失败;默认大纲的更改会以更改后的状态返回以供审查。缺口:track 测试匹配任何 aria-hidden 元素,因此缺少轨道的测试仍会通过;没有测试覆盖 Label 包装器或其截断,或调用方的 aria-label;也没有无障碍树检查能证明地标名称(spec:AST-009 FR3)。 |
audit:Outline/a11y |
| FR2, AR2 | Outline.test.tsx 受控的 aria-current、条目类和 active-anchor 测试 |
受控当前项;激活排序 | 缺少 aria-current、outline-item 类、激活类或 data-level,或指示器之后出现激活链接,均视为失败。缺口:层级缩进没有单元测试。 |
audit:Outline/theming |
| FR3, AR3 | Outline.test.tsx 键盘测试套件;OutlineFocus.a11y.chromium.spec.ts Tab 路径 |
Tab 顺序中的每个链接;真实焦点;无方向键、Home 或 End 移动;最后一个链接后按 Tab 移出;一项和零项 | 某个链接被排除在 Tab 顺序之外、链接上有 tabindex、使用了 aria-activedescendant、用方向键/Home/End 移动焦点,或在最后一个链接之后 Tab 仍停留在列表内,均判定为失败。 |
audit:Outline/keyboard |
| FR4, ORD2 | Outline.test.tsx 导航回调和滚动作用域测试套件 |
点击、Enter、Space;稳定;超时;双重稳定;中断;目标缺失;修饰键;hasScrollOnClick={false};偏移落点 |
导航未滚动、回调触发零次或两次、目标缺失或修饰键组合被截获,均判定为失败。没有测试覆盖导航后焦点去向;没有测试覆盖减弱动态效果偏好下的导航滚动;没有测试覆盖第二次导航结束第一次导航、滚动中途卸载后 onNavigateEnd 未触发,或对缺失目标按下 Space;没有测试在导航成功后检查 hash 推送。 |
audit:Outline/behavior |
| FR5, ORD1 | Outline.test.tsx 滚动跟踪、受控、偏移、滚动边距和作用域容器测试 |
非受控滚动;受控 API;偏移;滚动边距;容器;键盘及自身滚动 | 当前标题忽略偏移或滚动边距、跟踪错误容器,或将键盘焦点或其自身滚动视为手动操作,均判定为失败。没有测试派发 scroll 事件,因此跟踪的 scroll 事件路径未被检查。 |
audit:Outline/behavior |
| FR6 | Outline.test.tsx 指示器测试 |
指示器存在;活动锚点顺序 | 缺少指示器判定为失败(缺少轨道不会,见 FR1)。差距:除基线外,指示器的位置、大小、颜色和运动没有自动化检查;没有测试覆盖减弱动态效果下的结果。 | audit:Outline/design |
| FR7 | OutlineFocus.a11y.chromium.spec.ts |
每个受支持的上下文 | 在 Chromium 中,聚焦的链接如果没有可见焦点轮廓则判定为失败。 | audit:Outline/a11y |
| FR8 | Outline.test.tsx class 测试;源代码审查 |
调用方 class | 差距:没有测试覆盖 ref、DOM props、style 或 xstyle 合并顺序。 |
audit:Outline/api |
| PR1 | Outline.test.tsx 稳定测试;源码审查 |
稳定和回退 | 在回退和滚动结束均结束后,回调失败。差距:监听器清理没有检查。 | audit:Outline/behavior |
| 主题结构映射 | scripts/check-knowledge.mjs |
规范结构和当前目标 | 缺失、多余或过时的映射将导致仓库验证失败。 | audit:Outline/theming |
决策日志¶
未记录任何内容。该记录描述已发布的行为。
未决问题¶
- OQ1 — Outline 是否应采用名为
spec:AST-020的 FR15 例外:长标题列表使用一个 Tab 停止点,并支持方向键、Home 和 End 移动? (human-api) 如果没有它,长标题列表中的每个链接都将耗费一个 Tab 停止点(FR3)。 - OQ2 — Indicator 轨道是否应获得一个稳定的公共主题目标? (
human-api) 目标暴露情况尚未确定;当前不可达性并不决定答案。
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实现步骤或系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx