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:bidirectionalityDR7 要求分层表面与其触发元素保持 start/end 关系。 - 调用方
id会断开 Toggle 的连接。 调用方的idprop 即使是undefined,也会替换对话框上的抽屉 id,因此在 AppShell 内,Toggle 的aria-controls不再指向任何元素,从而破坏component:AppShellFR13 和 AR3。architecture:public-component-apiINV5 可防止组件自有的无障碍属性被意外覆盖。 - 调用方的
aria-label会被丢弃。 MobileNav 自身的名称(FR10)会替换对话框上调用方的aria-label。architecture:public-component-apiINV5 要求受支持的 ARIA 输入能够到达该元素。 - 调用方的
onCancel永远不会运行。 MobileNav 自身的取消处理器会替换对话框上调用方的onCancel。architecture:public-component-apiINV5 和 INV7 要求受支持的事件输入能够到达该元素并进行组合。 - MobileNav 自带顶层、关闭保持和背景层。 MobileNav 自行调用
showModal(),通过自己的计时器在关闭期间保持对话框打开,并绘制自己的背景层渐隐。architecture:layer-runtimeINV14 要求图层使用运行时的顶层挂载、呈现保持和背景层着色,而不是自行构建。 - 减弱动态效果下的动画。 在减弱动态效果下,抽屉的滑动和背景层的淡入淡出仍会运行 0.01 秒,而不是对精细指针立即变化、或对触摸进行交叉淡化。
design:reduced-motionDR2 和 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-runtimeINV14 提供运行时顶层挂载、关闭请求传递、呈现保持、共享退出副本以及背景色调;MobileNav 决定何时关闭以及如何呈现,包括其抽屉运动和背景颜色(当前状态影响记录了目前的不足)。design:reduced-motionDR1–DR3 约束抽屉在减少动态效果下的运动;architecture:public-component-apiINV5 和 INV7 约束调用方id与onCancel缺口。family:overlay-dismissal负责共享的 Escape 与平台关闭排序,并将 MobileNav 记录为采用者。component:AppShell决定抽屉何时渲染,并在关闭过程中保持其可见。design:bidirectionalityDR7 约束自动侧间隙。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| 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:
labelprop、调用方的aria-labelledby优先级高于名称、字符串header的二级标题,以及其他 header 内容按原样渲染。 - FR11:仅在启用的 AppShell 移动布局中渲染、仅图标的 ghost Button、替换默认名称的 Toggle
label、菜单图标,以及替换它的children。 - FR12:转发的
ref和xstyle,以及被替换的调用方aria-label和onCancel。
决策日志¶
DEC-1 — 抽屉中的链接位于导航地标内¶
参考: component:MobileNav/DEC-1
决策者: cixzhang(待所有者评审)
通过地标导航的手机用户可以在抽屉中找到导航,就像桌面用户找到 SideNav 的导航一样。抽屉本身是模态对话框,不是地标,因此其 Content 区域承载该地标并采用对话框的名称。一个地标即可覆盖抽屉中填充的任何内容。
已否决:让抽屉不带地标,这样手机上的地标导航将完全找不到导航。
未决问题¶
- OQ1 — Drawer 是否应获得一个稳定的公共主题目标?(
human-api)当前目标到达的是 Navigation 覆盖层,而非主要的抽屉绘制表面;这是一个审计缺口,并非已确定的意图。
内容边界¶
本文件不重复使用方的 prop 表/示例、AppShell 响应式策略、共享层规则、当前审计结果或实现步骤。它会链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx