跳转至

MobileNav 组件契约

契约一览

区域 契约
公共契约 MobileNav 带有 isOpen、onOpenChange、header、width (320)、side(start、end、auto;默认 auto)、label 和 children;目标为带 side 状态的 mobile-nav;MobileNavToggle 带有 label 和 children。
行为 一个模态原生对话框,带有从某一内联边缘滑入的抽屉、带关闭(Close)按钮的头部,以及可滚动的内容区域。Escape、背景层和 Close 都会请求关闭;对话框保持打开,直到抽屉开始滑出并在滑出过程中关闭(FR5),随后焦点返回到打开它的控件。
最终用户影响 手机用户在包含焦点的抽屉中打开导航,锁定其背后的页面,以任意常规方式关闭它,并回到打开它的控件上。
构建者影响 无。
兼容性/就绪状态 记录已发布(shipped)行为;无公共变更。六个实现差距:自动侧选择使用物理位置、减弱动态效果下仍会播放动画、自带顶层、关闭保持和背景层、调用方 id 会断开 Toggle 的连接、调用方的 aria-label 和 onCancel 被丢弃(见“当前状态影响”)。
评审检查 拒绝:非模态抽屉;在滑出动画运行前就隐藏抽屉的关闭行为;焦点未返回到已连接的打开控件;点击抽屉内的背景层导致其关闭;或 Toggle 被渲染在已启用的 AppShell 移动布局之外。
管辖规则 family:overlay-dismissal;architecture:layer-runtime INV14;component:AppShell FR10–FR13;design:bidirectionality DR7;design:reduced-motion DR1–DR3;architecture:public-component-api INV5, INV7;architecture:component-theming-surface。

此表是评审投影;以下正文为准。

意图

MobileNav 在模态抽屉中呈现移动导航,并导出一个感知 AppShell 的 Toggle 按钮,用于打开和关闭它。它拥有抽屉的对话框、放置、动画、关闭时机、焦点返回、页面滚动锁定,以及 Toggle 与抽屉之间的链接。消费者用法位于 MobileNav.doc.mjs 中。

兼容性与迁移

  • 已发布默认行为保留:yes
  • 兼容性类别:记录已发布行为;运行时、DOM、样式、目标、别名和公共 API 均保持不变
  • 受控/非受控行为:isOpen 和 onOpenChange 控制抽屉;没有它们时,它跟随外层 AppShell 的抽屉状态(FR2)
  • 迁移决策:无

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

当前状态影响

  • 自动侧选择依据物理位置。 当 side="auto" 时,中心位于视口左半部分的触发元素会在内联起始(inline start)处打开抽屉,否则在内联末尾(inline end)处打开。在从右到左的布局中,内联起始是右边缘,因此每个触发元素都会在远侧打开抽屉。design:bidirectionality DR7 要求分层表面与其触发元素保持 start/end 关系。
  • 调用方 id 会断开 Toggle 的连接。 调用方的 id prop 即使是 undefined,也会替换对话框上的抽屉 id,因此在 AppShell 内,Toggle 的 aria-controls 不再指向任何元素,从而破坏 component:AppShell FR13 和 AR3。architecture:public-component-api INV5 可防止组件自有的无障碍属性被意外覆盖。
  • 调用方的 aria-label 会被丢弃。 MobileNav 自身的名称(FR10)会替换对话框上调用方的 aria-label。architecture:public-component-api INV5 要求受支持的 ARIA 输入能够到达该元素。
  • 调用方的 onCancel 永远不会运行。 MobileNav 自身的取消处理器会替换对话框上调用方的 onCancel。architecture:public-component-api INV5 和 INV7 要求受支持的事件输入能够到达该元素并进行组合。
  • MobileNav 自带顶层、关闭保持和背景层。 MobileNav 自行调用 showModal(),通过自己的计时器在关闭期间保持对话框打开,并绘制自己的背景层渐隐。architecture:layer-runtime INV14 要求图层使用运行时的顶层挂载、呈现保持和背景层着色,而不是自行构建。
  • 减弱动态效果下的动画。 在减弱动态效果下,抽屉的滑动和背景层的淡入淡出仍会运行 0.01 秒,而不是对精细指针立即变化、或对触摸进行交叉淡化。design:reduced-motion DR2 和 DR3 允许无位移,并且对于精细指针,不允许有动画属性。

所有权边界

拥有

  • 导航覆盖层及其当前的 mobile-nav 目标。
  • 抽屉的放置和动画、稳定的 Header 和 Content 区域,以及 AppShell 状态、MobileNav 与 MobileNavToggle 之间的连接(FR1–FR12)。
  • 背景层的外观(FR13)。
  • 抽屉的导航地标(FR14)。
  • 两个导出组件的规范结构(canonical anatomy)。component:MobileNav 是父级拥有者;MobileNavToggle 没有自己的消费者文档,也没有单独的组件契约。

不拥有 / 非目标

  • 关闭和切换按钮表面 — 委托给 component:Button。
  • 头部或导航内容由调用方提供。
  • 为已渲染的 Drawer、Header 或 Content 区域提供公共目标;不存在这样的目标。
  • AppShell 的响应式策略、抽屉何时渲染以及其关闭保持 — 由 component:AppShell 所有。
  • 共享的 Escape 和关闭请求排序 — 由 family:overlay-dismissal 所有;共享层托管 — 由 architecture:layer-runtime 所有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Side start, end, auto 抽屉进入所沿的内联边缘;auto 根据打开者的位置选择。 每次打开时。 auto component:MobileNav 稳定 TypeScript 拒绝其他值。

行为与布局契约

ID 不变量 依据
FR1 MobileNav 渲染一个原生 <dialog> 导航浮层,其中包含一个 Drawer,带有稳定的 Header、关闭按钮和可滚动的 Content 区域。该浮层携带 mobile-nav 及解析后的 side;Drawer、Header 和 Content 不携带 MobileNav 公共目标。 当前源码、文档和测试
FR2 当提供 isOpen 和 onOpenChange 时,它们优先;否则抽屉读取并更改外层 AppShell 的抽屉状态。对话框在存在 AppShell 的抽屉 id 时使用该 id,否则使用自身的 id;调用方的 id 会替代两者(当前状态影响)。 当前源码和测试
FR3 打开时调用 showModal(),并将当前聚焦元素记录为打开者;焦点落在打开的抽屉内部的什么位置,此处不做约定。打开时,页面的滚动容器裁剪其溢出并保留滚动条槽:该容器是根元素;或者当 <body> 设置了自己的 overflow 且根元素的 overflow 保持 visible 时,该容器是 <body>。下拉刷新和页面回弹停止,因为模态下的滚动锁定会固定页面(spec:AST-094 FR19)。关闭时释放这三者。 当前源码和测试
FR4 原生取消请求(Escape)通过共享的关闭栈路由,并且仅当此抽屉处于栈顶时才请求关闭。点击 Drawer 外部的浮层会请求关闭;点击内部不会。名称为 @astryx.mobileNav.closeNavigation 的关闭按钮请求关闭。调用方在对话框上的 onClick 会在背景遮罩检查之前运行;其中调用 preventDefault() 的会取消该背景遮罩关闭。 当前源码和测试
FR5 在关闭请求之后,抽屉滑出,同时对话框保持打开;对话框在其滑出过渡期间内关闭,且不晚于请求后 250 ms(在下一个任务中,绝不会在发出请求的提交中,在减少动效或零长度过渡下也是如此)。在此之前重新打开会取消关闭。卸载会关闭对话框。对话框关闭后,剩余的滑出部分为惰性状态。 当前源码和测试
FR6 当对话框关闭时,如果记录的打开者仍然处于连接状态且不是文档 body,则焦点返回该打开者;否则不干预焦点。中断关闭的重新打开会保留原始打开者。 当前源码和测试
FR7 在没有减少动效偏好时,Drawer 从其解析后的内联边缘进入,从屏幕外到屏幕内,背景遮罩从透明淡入。在减少动效下,动效遵循 design:reduced-motion DR1–DR3(当前状态影响记录了目前的不足)。浮层裁剪屏幕外的抽屉,但不会成为滚动容器,并允许双指缩放。 当前源码和测试
FR8 side="start" 或 "end" 设置边缘。side="auto" MUST 保持 Drawer 与打开它的元素之间的起始和结束关系(design:bidirectionality DR7)。实现差距:每次打开时,它根据聚焦元素所在的视口物理半区进行解析(左半区选择 start,否则选择 end);打开时若无聚焦元素,则保持其上一个值;在任何打开之前,它为 end。 当前源码
FR9 Drawer 为 width 像素宽(默认 320),不得宽于视口的 85%,因此页面的一窄条会留在它旁边。 当前源码和测试
FR10 该对话框由 label 命名,否则由字符串 header,否则由 @astryx.mobileNav.navigation;调用方的 aria-labelledby 优先级高于这三者。字符串 header 渲染为二级标题;其他 header 内容按原样渲染。 当前源码和测试
FR11 MobileNavToggle 仅在 AppShell 报告其启用了移动导航的移动布局时渲染。它是一个仅图标的幽灵 Button,默认以 @astryx.mobileNav.toggle.open 命名,带有一个菜单图标,除非 children 替换它;它切换 Drawer,暴露 aria-expanded,并且其 aria-controls 携带 AppShell 的 Drawer id,该 AppShell 内的 MobileNav 会将其应用于自己的对话框,除非调用方的 id 替换了它。 当前源码、文档和测试
FR12 MobileNav 将其 ref、data-testid、其他 DOM props、className、style 和 xstyle 转发给对话框,但以下情况除外:其自身的 aria-label(FR10)替换调用方的(当前状态影响);调用方的 onCancel 永远不会运行(当前状态影响);调用方的 id 替换它的 id(FR2)。 当前源码和测试
FR13 MobileNav 的背景是主题的 --color-overlay,变暗且无模糊,在所有指针类型下均如此;在强制颜色模式下,Drawer 保持可见边缘。 负责人决策,2026-10-25:遮罩层保持主题控制,且在所有指针类型下均不模糊。
FR14 Content 区域是一个导航地标,其命名与对话框相同(FR10),因此依赖地标导航的人在手机上能找到 Drawer 的链接,就像他们在宽屏上找到 SideNav 的链接一样。无论填充其中的是 SideNav 项还是 TopNav 的 Drawer 内容,都位于这一个地标内。 负责人决策 DEC-1

允许的变化

  • AV1 — Drawer 边缘。 Drawer 可以通过显式或由触发元素派生的 side 行为解析为逻辑起始或结束。
  • AV2 — Header 内容。 Header 可以包含通过 Heading 渲染的字符串、调用方提供的内容,或仅包含关闭按钮。
  • AV3 — 导航内容。 调用方提供的导航内容可以变化,而不会成为 MobileNav 自身结构的组成部分。
  • AV4 — 切换按钮的存在。 在启用的 AppShell 移动上下文之外,切换按钮不存在。

代表性状态

状态 必需不变量 允许的变化
独立抽屉 导航覆盖层包含 Drawer、Header、Close button 和 Content。 调用方控制打开状态,并可以选择边缘。
AppShell 抽屉 相同的抽屉解剖结构使用 AppShell 移动端状态。 Header 和导航内容仍归调用方所有。
AppShell 移动端切换按钮 切换按钮控制并引用当前抽屉。 自定义按钮内容可替换菜单字形。
非移动/禁用宿主 切换按钮不渲染。 MobileNav 仍由父级契约拥有。
关闭中 对话框保持打开,同时抽屉开始滑出并在滑出动画内关闭(FR5);然后焦点返回。 时长由主题决定。
关闭中途重新打开 待处理的关闭被取消;焦点保持在抽屉内。 —

转换与优先级顺序

  • ORD1 — 打开状态。 isOpen,然后是 AppShell 的抽屉状态。
  • ORD2 — 名称。 调用方的 aria-labelledby,然后是 label,然后是字符串 header,然后是翻译后的默认值。
  • ORD3 — 关闭延迟。 受对话框滑出过渡和 250 ms 限制;在减少动态效果或零长度过渡下,延迟会被安排为下一个任务。

性能与资源

  • PR1 — 清理。 待处理的关闭定时器会在重新打开和卸载时清除;页面滚动器的裁剪、过度滚动停止以及滚动条 gutter 都会在关闭和卸载时释放。

可访问性契约

  • AR1 — 模态对话框。 打开的抽屉是一个带有可访问名称的模态原生对话框(FR3、FR10);其背后的页面处于惰性状态。
  • AR2 — 焦点返回。 FR6。
  • AR3 — 切换按钮接线。 FR11 的 aria-expanded 和 aria-controls。
  • AR4 — 缩放。 抽屉打开时,捏合缩放仍然可用。
  • AR5 — 导航地标。 FR14。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
Navigation overlay 承载模态导航层及其背景层。 当前源码与公开文档 辅助 FR1、FR4、FR13
Drawer 绘制滑动式移动导航表面。 当前源码与公开文档 主要 FR1、FR7–FR9
Header 将可选头部内容与常驻的 Close button 排列在一起。 当前源码与公开文档 辅助 FR1、FR10
Content 为调用方提供的导航内容提供滚动区域。 当前源码与公开文档 主要 FR1
Close button 关闭当前抽屉。 component:Button 辅助 FR4
Toggle button 打开或关闭 AppShell 拥有的移动抽屉状态。 component:Button 辅助 FR11

Drawer 是主要的绘制表面,但当前唯一的 MobileNav target 位于全视口对话框覆盖层上。它的 none 处置是一个事实性的可达性缺口,并非决定 Drawer 必须保持不可主题化。Header 和 Content 同样没有当前的本地 target。Close 和 Toggle 保留 Button 所有权。

主题化解剖结构

{
  "Navigation overlay": {"target": "mobile-nav"},
  "Drawer": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the painted drawer panel"
    }
  },
  "Header": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the stable header row"
    }
  },
  "Content": {
    "none": {
      "reason": "reachability-gap: No current public target is applied to the scrollable content region"
    }
  },
  "Close button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Toggle button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  }
}

家族与系统关系

  • architecture:component-theming-surface 负责解剖结构资格认定、target 映射、委托以及事实性的 none 处置。
  • architecture:layer-runtime INV14 提供运行时顶层挂载、关闭请求传递、呈现保持、共享退出副本以及背景色调;MobileNav 决定何时关闭以及如何呈现,包括其抽屉运动和背景颜色(当前状态影响记录了目前的不足)。
  • design:reduced-motion DR1–DR3 约束抽屉在减少动态效果下的运动;architecture:public-component-api INV5 和 INV7 约束调用方 id 与 onCancel 缺口。
  • family:overlay-dismissal 负责共享的 Escape 与平台关闭排序,并将 MobileNav 记录为采用者。
  • component:AppShell 决定抽屉何时渲染,并在关闭过程中保持其可见。
  • design:bidirectionality DR7 约束自动侧间隙。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR2, FR10, FR12 MobileNav.test.tsx 打开和关闭;有字符串标题和无标题;独立抽屉上的调用方 id 丢失对话框、名称、关闭按钮或转发的属性将导致失败。 audit:MobileNav/anatomy
FR2, FR3, FR4 MobileNav.test.tsx;MobileNavCloseEdgeCases.test.tsx;MobileNavScrollbarGutter.test.tsx;MobileNavRootScrollClaim.test.tsx Escape 键、背景遮罩、内容点击、关闭按钮 错误的关闭来源或未解除的滚动锁定将导致失败。 audit:MobileNav/behavior
FR4 layerDismissalFamilies.test.tsx 中的 MobileNav 用例 在必需 Dialog 上按 Escape 键;在最顶层时取消以及不在最顶层时取消 非最顶层时关闭,或最顶层时不关闭,均视为失败。 audit:MobileNav/behavior
FR5, ORD3 MobileNavCloseVisibility.test.tsx;MobileNavCloseEdgeCases.test.tsx;MobileNavCloseTiming.test.ts 关闭、减少动态效果、重新打开、卸载、250 毫秒界限 在滑出动画结束前关闭,或对话框卡住,均视为失败。 audit:MobileNav/behavior
FR5 MobileNavTouchPresentation.a11y.chromium.spec.ts(关闭后的滑出动画) 对话框已关闭、抽屉仍在滑出;抽屉处于打开状态 点击正在退出的抽屉并触发其中内容,或关闭后浏览器无障碍树仍暴露该对话框或其链接,均视为失败。 audit:MobileNav/behavior
FR6, AR2 MobileNavFocus.test.tsx 独立模式、AppShell、Escape 键、触发元素被移除 焦点未返回,或返回过早,均视为失败。 audit:MobileNav/accessibility
FR7 MobileNavEntryAnimation.test.tsx 起始和结束边界 缺少起始样式或滚动容器遮罩,均视为失败。 audit:MobileNav/behavior
FR11, AR3 MobileNavToggle.test.tsx;MobileNavReopen.test.tsx 关闭、打开、重新打开 展开状态或 id 链接失效即失败。 audit:MobileNav/accessibility
AR4 MobileNavPinchZoom.a11y.chromium.spec.ts 触摸视口上打开的抽屉 捏合缩放被阻止即失败。 audit:MobileNav/accessibility
FR9 MobileNav.test.tsx 抽屉宽度上限测试;MobileNavWidth.a11y.chromium.spec.ts 窄视口上的默认 width 与较宽 width 抽屉宽度超过视口的 85% 即失败。 audit:MobileNav/behavior
FR14 对打开状态的抽屉进行 Chromium 无障碍树检查,包含 SideNav 项和 TopNav 抽屉内容 来自 SideNav 抽屉模式的抽屉,以及来自 TopNav 抽屉的抽屉 树中没有显示导航地标、显示未命名的地标、显示与对话框名称不同的名称,或显示两个嵌套地标(spec:AST-009 FR3:计算角色和名称需要无障碍树证据) audit:MobileNav/accessibility
主题结构映射 scripts/check-knowledge.mjs;themingTargets.test.ts 规范父级结构与当前目标 缺失、多余、带前缀、过期或重复分配的映射会使仓库验证失败。 audit:MobileNav/theming
RTL 关系 RTL 审计整理的 D4 目标(apps/storybook/rtl-audit/targets.json),作用于 MobileNav / Default(抽屉已打开) 打开状态的抽屉;LTR 和 RTL 在 RTL 中未移动到页面镜像侧的抽屉不符合 D4。证据缺口:该 story 将其触发器居中,因此文档中描述的 side="auto" 远侧 RTL 抽屉(FR8)未被观察到。 audit:MobileNav/i18n-rtl
FR13 modalBackdrop.test.tsx;ModalBackdrop.a11y.browser.spec.ts,在 Chromium 和 WebKit 中运行 手机宽度下的手指触摸;桌面宽度下的鼠标;任一指针下的强制颜色模式 在任一宽度下背景上存在 backdrop-filter,或在强制颜色模式下没有可见边缘,均视为失败。 audit:MobileNav/theming

已从源码读取,但尚无聚焦测试:

  • FR1:不同的 Drawer、Header 和 Content 元素,以及带有 side 状态的 mobile-nav 目标。
  • FR2 和 FR11:对话框在 AppShell 外部的自有 id,以及调用方的 id 在 AppShell 内部替换 AppShell 的抽屉 id。
  • FR4:调用方的 onClick 在背景检查之前运行,以及其 preventDefault() 取消行为。
  • FR8 的已实现解决方案。
  • FR10 和 ORD2:label prop、调用方的 aria-labelledby 优先级高于名称、字符串 header 的二级标题,以及其他 header 内容按原样渲染。
  • FR11:仅在启用的 AppShell 移动布局中渲染、仅图标的 ghost Button、替换默认名称的 Toggle label、菜单图标,以及替换它的 children。
  • FR12:转发的 ref 和 xstyle,以及被替换的调用方 aria-label 和 onCancel。

决策日志

参考: component:MobileNav/DEC-1 决策者: cixzhang(待所有者评审)

通过地标导航的手机用户可以在抽屉中找到导航,就像桌面用户找到 SideNav 的导航一样。抽屉本身是模态对话框,不是地标,因此其 Content 区域承载该地标并采用对话框的名称。一个地标即可覆盖抽屉中填充的任何内容。

已否决:让抽屉不带地标,这样手机上的地标导航将完全找不到导航。

未决问题

  • OQ1 — Drawer 是否应获得一个稳定的公共主题目标?(human-api)当前目标到达的是 Navigation 覆盖层,而非主要的抽屉绘制表面;这是一个审计缺口,并非已确定的意图。

内容边界

本文件不重复使用方的 prop 表/示例、AppShell 响应式策略、共享层规则、当前审计结果或实现步骤。它会链接到这些内容的所有者。

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