跳转至

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 或本地化默认值替换;只有 label prop 能为导航命名,而 architecture:public-component-api INV5 允许调用方的显式输入到达元素。
  • 导航后焦点仍停留在 Outline 上(FR4)。 激活链接会滚动到该章节,但焦点仍留在链接上,因此下一次按 Tab 会移过 Outline,通常回到内容顶部附近,而不是进入所选章节;而原生页内链接会移动顺序焦点的起始点(WCAG 2.2 SC 2.4.3)。
  • 减弱动效下指示器仍会滑动(FR6)。 指示器的移动和大小调整过渡没有减弱动效分支,而 design:reduced-motion DR1–DR3 要求在精细指针上立即变化,在粗略指针上以 200 ms 或更短时间交叉淡入淡出。
  • 减弱动效下导航仍平滑滚动(FR4)。 激活链接后始终平滑滚动到标题,而 design:reduced-motion DR1–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-020 FR15)。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
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