BottomSheetSwitcher 组件契约¶
意图¶
BottomSheetSwitcher 负责协调一组互斥的 BottomSheet 子项序列,每个子项都在自己的原生对话框中呈现(DEC-1),且不添加 prop 或更改默认值。其公开生命周期状态为 deprecated(spec:AST-017 FR26、DEC-3、DEP-0015):它仍受支持并持续维护,本记录中的每项要求继续有效;而替代方案——每个步骤由单个状态值驱动的独立 BottomSheet,当步骤从已打开的步骤内部发生变化时,component:BottomSheet FR10 会就地替换该 BottomSheet——正是受维护的文档、模板、stories 和智能体指南所教授的内容。移除只会在未来声明的 minor 版本中通过 [breaking] 变更进行。以下关于模态性、标识符和主题化的问题仍保持开放。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:非破坏性;公开 props、默认值、导出、视觉输出和过渡行为保持不变,唯一例外是:在减少动态效果下,交接遵循
design:reduced-motion(FR3),这是spec:AST-017FR3 下仅影响视觉的动态变化。ref解析到的元素以及它会在交接时发生变化这一事实,均属于实现而非公开契约(DEC-2)。单独呈现的 switcher 流程行为与发布时一致,但有三项修复:从某一步骤引发的 toast 会渲染在该流程上方且可被按下(FR10、component:BottomSheetFR13),而此前它渲染在流程后方;某个活动 sheet 在服务端设置的流程在 hydration 之前保持关闭,随后不带进入动画地稳定打开该 sheet(component:BottomSheetFR17),而此前它会在实时页面上绘制为打开状态;某个步骤在打开时若带有符合条件的data-autofocus字段(带hasAutoFocus的TextInput),则会在每个引擎中都聚焦该字段(component:BottomSheetAR4),而此前 Chromium 聚焦的是该步骤的面板。当其他 sheet 已打开时呈现的 switcher 流程,是component:BottomSheetFR12 所描述的堆栈中的一层;这是堆栈的行为,而非对 switcher 自身契约的更改。 - 生命周期:
deprecated(DEC-3、DEP-0015)。弃用不会增加任何生产运行时行为,也不会在渲染的应用程序中产生警告(spec:AST-017FR29);@deprecated元数据位于BottomSheetSwitcher、BottomSheetSwitcherProps以及BottomSheet的sheetId的 TypeScript 声明上,消费者文档中则包含替代路径(FR29a、FR29b)。 - 受控/非受控行为:
activeSheet仍然完全受控 - 迁移决策:DEC-3;该迁移即 DEP-0015 的迁移。
消费者迁移说明应放在消费者文档和发布说明中。
DEP-0015 — 弃用 BottomSheetSwitcher,改用独立步骤 sheet¶
| 字段 | 值 |
|---|---|
| id | DEP-0015 |
| cleanup | 暂无;该移除已决定在未来的一个已声明的次版本中进行。 |
| package | @astryxdesign/core |
| surface | BottomSheetSwitcher, BottomSheetSwitcherProps, and the sheetId prop of BottomSheet |
| 旧契约 | 多步骤流程是一个 BottomSheetSwitcher,其 activeSheet 通过 sheetId 指定一个嵌套的 BottomSheet;步进会运行 FR2–FR3 和 FR8 的交接 |
| 替代方案 | 每个步骤使用一个独立的 BottomSheet,通过 isOpen={step === id} 控制,并由一个状态值驱动;在同一次更新中,从打开步骤内部的控件(或当焦点位于其中时从代码)关闭当前打开的步骤并打开下一步,会运行相同的交接(component:BottomSheet FR10),对模态流程和 hasScrim={false} 流程均适用。由流程的 sheets 外部的控件更改步骤——即非模态流程旁边的页面控件,或当焦点位于页面控件上时代码执行操作——则是一次关闭和一次打开,带有各自的 push 和 pop 动画;而切换器会在任何 activeSheet 更改时运行其交接;当焦点位于步骤内或文档 body 上时代码执行操作,仍然会运行交接(component:BottomSheet FR10 的执行者位于步骤内部,或不存在)。 |
| 直接负责方 | DEC-3 此处;component:BottomSheet DEC-2 和 FR10 负责替代行为。所有者:cixzhang、imdreamrunner |
| 警告 | 在声明上标注 @deprecated;消费者文档、模板、stories 和发布说明中指明替代项。无运行时警告(spec:AST-017 FR29) |
| migration | 按流程有序且可测试:(1) 用一个 step 值替换 activeSheet / onActiveSheetChange;(2) 为每个步骤设置 isOpen={step === 'id'} 和 onOpenChange={isOpen => !isOpen && setStep(current => (current === 'id' ? null : current))},取代 sheetId="id";(3) 移除包装器,将其 hasScrim 移到每个步骤上;(4) 保持步骤控件不变(setStep('next'));(5) 由外部控件驱动的流程(非模态流程旁的一个页面控件,或焦点位于页面控件上时代码执行)会得到 push/pop 动画而不是交接动画——将该控件移入步骤,或接受该动画;焦点位于步骤内或 body 上时代码执行仍保留交接动画;(6) 切换器的其他 props:onCancel 成为每个步骤上受保护的 onOpenChange——在流程必须保持打开时忽略 false——从而保留步骤的 dialog 角色;独立 sheet 将 Escape、平台关闭、scrim 点击和滑动都报告为 onOpenChange(false),且不提供原因,因此该保护在适用期间会让步骤保持打开,而切换器的 onCancel 只能否决取消请求;单独否决 Escape 没有等价物,唯一的逐路径手段是 purpose(form 保留 Escape 并阻止 scrim 点击和滑动;required 阻止全部三项并将步骤暴露为 alertdialog);没有逐事件否决;使用方的 aria-label / aria-labelledby 成为每个步骤的 label,它命名其 dialog;ref、id、data-testid、className、style、xstyle 以及其他 dialog props 没有 dialog 级别的等价物——独立 sheet 的 ref 和基本 props 到达其面板 <div>,而其 dialog 是内部实现——因此需要 dialog 的测试或锚点应查询面板的 closest('dialog'),并且丢弃 dialog 级别的样式 |
| codemod | 无;重写移动了调用方所拥有的状态,且足够简短,易于阅读 |
| downstream | 受维护的已发布接口面在弃用补丁(spec:AST-017 FR29c)中迁移:CLI 块模板和 stories。@astryxdesign/lab 被标记为 private,并且仅以 @canary dist-tag 发布到 npm,从不作为稳定的 latest 版本发布;spec:AST-017 将其称为“仅限 canary 的私有 Lab 包”(FR27),将私有包列入其非目标(non-goals),将它们排除在已发布的兼容性承诺(FR2)之外,并指出仅限 canary 的接口面不承担稳定的兼容性承诺;本记录将此解读为 FR29c 中的“受维护的 Astryx 包”不涵盖 Lab,因此在此解读下 Lab 的迁移是可选的;Lab 没有 switcher 消费者,因此没有受维护的接口面使用 switcher。spec:AST-017 是否按此方式解读,由其所有者定夺。switcher 自身的 stories 仍保留作为其带标签的参考。 |
| transition | 无先前的迁移记录 |
| 状态 | deprecated:仍受支持,已记录其替代方案,运行时保持不变 — 弃用补丁 spec:AST-017 FR28 要求在移除之前,通过声明和文档(FR29a、FR29b)体现。 |
| 开放决策 | 哪个已声明的次要版本会移除该表面,以及重命名的兼容导出是否先于移除;这两者中的任意一项都属于已声明次要版本的 [breaking] 变更(spec:AST-017 FR28、FR31)。 |
| 目标计划 | 在未来的一个已声明次要版本中通过 [breaking] Changeset 移除;未指定发布版本 |
所有权边界¶
拥有
- 每个直接嵌套的 BottomSheet 子项的原生对话框的展示生命周期:哪个会被展示、在交接期间保留或关闭。
- 哪个子 sheet 是活跃的、在交接期间保留的或隐藏的。
- 哪个 sheet 对话框承载该流程(其 ref、
id和关闭注册),以及哪个绘制该流程的唯一遮罩,此外还有 Escape/平台关闭路由以及流程的最终焦点返回。焦点约束属于原生模态对话框;该流程的唯一页面滚动锁会在整个模态流程期间保持(DEC-1)。 - 流程包装器:用于在局部对非模态 sheet 对话框进行排序的隔离表面(
spec:AST-027FR2)。
不拥有 / 非目标
- 子级 sheet 的面板、内容、手柄、高度、吸附点、滑动机制或局部视觉样式——由
component:BottomSheet拥有。 - 页面级堆叠或裁剪逃逸——由
architecture:layer-runtime和spec:AST-027拥有。 - 已呈现 sheet 的堆栈、其顺序、其单个可见 scrim,以及独立 sheet 之间的替换交接——由
component:BottomSheetDEC-2 拥有。切换器流程仅作为一个层级参与(此处为 FR10,彼处为 FR12);它不自行与其他 sheet 排序。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 活动 sheet | null 或一个嵌套的 BottomSheet sheetId |
选择唯一可交互的子级,或关闭流程 | 所有呈现方式 | null 表示关闭;该 prop 为必填 |
component:BottomSheetSwitcher |
已弃用(DEP-0015) | 当前契约不会为非匹配或重复的 id 提供安全的公共回退 |
| 共享呈现 | 通过 hasScrim 表示 true / false |
选择当前模态的带 scrim 宿主,或非模态的无 scrim 宿主 | 整个流程 | true |
component:BottomSheetSwitcher |
已弃用(DEP-0015) | 仅限布尔值 |
| 子级身份 | 每个直接 BottomSheet 子级上的非空 sheetId |
将受控的选择、标签、用途和过渡状态与子级关联 | 直接嵌套的 BottomSheet 子级 | 无 | component:BottomSheet |
已弃用(DEP-0015) | 空 id 会发出警告并保持隐藏;重复 id 的行为未作规定 |
| 关闭请求 | onActiveSheetChange(null) |
在不从调用方夺取控制权的情况下,报告一次被允许的隐式关闭 | 根据活动子级用途,通过 Escape/平台关闭、scrim 点击或滑动 | 无 | component:BottomSheetSwitcher;family:overlay-dismissal 拥有排序 |
已弃用(DEP-0015) | 调用方可保留其受控值 |
| Dialog 表面 | 继承的 dialog props 加上 ref 和 onCancel |
Dialog props 和 handlers(包括 onCancel)会到达每个 sheet dialog;ref、id 和 data-testid 解析到宿主 dialog,在 sheet 挂载期间,对象 ref 的宿主 dialog 绝不为 null(DEC-2)。 |
整个流程 | 无 | component:BottomSheetSwitcher |
已弃用(DEP-0015) | 组件自有的语义和 handlers 保留优先级 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 对于每个受控的 activeSheet 值,零个或一个子面板处于可交互状态;在过渡期间,所有其他子面板均被隐藏,或以惰性(inert)状态保留并设置 aria-hidden。 |
当前源代码、文档和测试 |
| FR2 | 每个子面板拥有一个原生对话框。打开面板时,其对话框只呈现一次;交接(handoff)时,进入的面板的对话框显示在保留面板的对话框之上,并且仅在其面板淡出后才关闭保留的对话框。当返回到某个其对话框仍打开在较新面板之下的面板时,会重新呈现该对话框,使可交互面板位于最顶层。 | DEC-1 |
| FR3 | 在交接期间,进入的面板位于保留面板之上。较高的保留面板向下对齐至较矮的进入面板,并且保留面板仅在所需的变换动效完成后才淡出。在减少动态效果(reduced motion)模式下,交接遵循 design:reduced-motion:不运行任何变换动效,面板按相同顺序交叉淡入淡出(DR2)或立即切换(DR3)。 |
当前源代码和过渡测试;design:reduced-motion DR2、DR3 |
| FR4 | 关闭时,离开的面板在其退出过程中保持保留,随后关闭对话框。模态流程(modal flow)会将焦点恢复到该模态流程打开时捕获的元素。 | 当前源代码和焦点测试 |
| FR5 | hasScrim=true 使用 showModal()、原生背景层和原生焦点包含,并锁定页面滚动:在模态流程呈现期间页面不会滚动,下拉刷新和页面回弹会在其后方停止,因为模态下方的滚动锁定会稳住页面(spec:AST-094 FR19),如同 UIKit 模态呈现背后的行为;该锁定在交接期间持续保持,绝不在步骤之间释放后重新获取;它仍会保持在被某一步骤打开的 Dialog 下方;只有在流程退出后才会释放(DEC-1)。hasScrim=false 使用 show(),不带背景层或滚动锁定,并保持页面可交互。在非模态流程中,sheet 对话框会在切换器的隔离流程包装器内以局部值自行排序(DEC-1);该包装器携带的页面级值仍是 spec:AST-027 合规性差距。 |
DEC-1;spec:AST-027 FR2、FR4、FR8 |
| FR6 | 活动子级的用途决定隐式关闭行为:info 允许 Escape、遮罩层点击和滑动;form 允许 Escape;required 阻止全部三种方式,并暴露 alertdialog。 |
当前 BottomSheet 文档和切换器测试 |
| FR7 | 可见期间,切换器参与 family:overlay-dismissal;一次 Escape 或平台关闭请求只会到达最顶层的呈现层,后代层级会获得更深的逻辑层作用域。 |
family:overlay-dismissal 和审计回归测试 |
| FR8 | 同一时间只有一个背景层绘制流程的遮罩层:被保留的 sheet 的对话框会在交接期间持续持有它,当被保留的对话框关闭时,进入的对话框会无淡化地接管它。来自正在退出的 sheet 的过期手势无法改变流程的遮罩层,卸载被保留的 sheet 也无法让其对话框保持打开,或让流程的模态层被持续持有。 | DEC-1;当前测试 |
| FR10 | 在其他模态面板仍处于打开状态时呈现的模态切换器流程,是 component:BottomSheet 栈中的一层:活动步骤的对话框即该层,并在流程自身的交接过程中保持流程在栈中的位置;当被覆盖时,流程的各对话框会像被覆盖的面板一样退后并被阻止交互;其背景层是透明的,而较低层面的面板拥有唯一的 scrim,且其关闭注册不再生效;当它在一个较低面板之上关闭时,焦点按照 component:BottomSheet FR9 返回到该面板中。模态流程的宿主对话框是一个被动的全局 toast 出口,类似独立 scrim 面板的宿主对话框;它跟随每次交接,并由栈在各面板之间排序(component:BottomSheet FR13)。在减少动态效果下,流程步骤的移动方式与 component:BottomSheet FR15 所述一致,即与独立面板(FR3)使用相同的面板动效。在某个步骤的内容中渲染的独立面板会堆叠在流程之上,并随该步骤一并离开。在 replace 操作中,步骤绝不会与独立面板配对。 |
component:BottomSheet DEC-2, FR12 |
| FR9 | 切换器会将通用的对话框属性、样式输入和组合处理器(包括 onCancel)转发到每个面板对话框,因此无论哪个面板对话框触发事件,处理器都会触发;它只在宿主对话框上渲染 id 和 data-testid,从而使每个值在文档中只出现一次;它将自身的 ref 附加到宿主对话框上,并保留其自身的 ARIA 与关闭行为。在面板挂载期间,对象 ref 的 current 永远不会是 null。回调 ref 在交接时遵循 React 的语义:它返回的清理函数会在其从旧宿主分离时运行;没有返回清理函数的回调 ref 会在分离时以 null 调用,随后以新宿主调用。 |
DEC-1, DEC-2; architecture:public-component-api INV8 |
允许的变化¶
- AV1 — 子内容与面板几何。 子内容、高度、吸附点(snap points)和面板样式可在
component:BottomSheet下变化,而不改变切换器的单活动子协议。 - AV2 — 过渡时序。 主题动效令牌可以改变时序,同时保留 FR3 中的顺序和惰性。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 已关闭 | 每个面板对话框都已关闭,且任何子项都不可交互。 | 子面板可以保持已挂载但隐藏。 |
| 首次打开 | 匹配到的子项在其自己的对话框中可见且可交互。 | 子项自身决定高度和内容。 |
| 交接 | 进入的子项在其自身对话框中可交互;保留的子项对话框保持打开、惰性,并在淡出前对无障碍 API 隐藏;当流程拥有遮罩时持续绘制唯一遮罩——当较低层 sheet 拥有堆栈遮罩时保持透明(FR10、component:BottomSheet FR6)。 |
对齐偏移取决于测量到的面板几何形状。 |
| 关闭中 | 退出中的子项在退出动画完成前保持保留且惰性;模态焦点和滚动所有权保持到关闭为止。 | 主题控制的时长。 |
| 模态 | 原生模态宿主、背景遮罩、原生焦点约束和页面滚动锁定均处于激活状态。 | 活动子项的 purpose 控制隐式关闭。 |
| 非模态 | 原生非模态宿主没有背景遮罩或滚动锁定,背景内容保持可交互。 | 当前的裁剪/层叠限制是一个合规性差距,而非允许的例外。 |
| 堆叠 | 该流程被独立模态 sheet 覆盖,或覆盖独立模态 sheet:作为被覆盖层级,其对话框退后并被阻止交互,整个堆栈只显示一个遮罩(FR10)。 | 在 component:BottomSheet DEC-2 下的退后几何形状。 |
变换与优先级顺序¶
- ORD1 — 交接完成。 选择下一个子项 → 将前一个子项标记为保留且惰性 → 启动进入变换及任何必需的保留对齐 → 等待两个变换完成 → 淡出保留子项 → 隐藏它。在减弱动态效果下,变换步骤被跳过,进入和保留的子项交叉淡入淡出或立即切换(
design:reduced-motionDR2、DR3),同时保持此顺序。 - ORD2 — 标签优先级。 使用方的
aria-label优先;否则使用方的aria-labelledby优先;再否则由活动或保留子项的标签为对话框命名。
性能与资源¶
- PR1 — 唯一绘制的遮罩。 在模态流程中,静止时恰好呈现一个 sheet 对话框;交接期间呈现两个,但只绘制一个背景遮罩。原生模态性在模态流程的子项交接期间保持不变,因为 sheet 对话框全程是模态的,并且整个流程持有一次页面滚动锁定,而非每一步都锁定。非模态流程不绘制背景遮罩,也不持有滚动锁定。
- PR2 — 稳定的子项注册。 父组件重新渲染以及 consumer ref 身份的变化不会注销已挂载的子项,也不会取消进行中的交接。
无障碍契约¶
- AR1 — 对话框语义。 模态呈现暴露
aria-modal;必需子项将隐式对话框角色改为alertdialog;每个可见流程都有使用方提供或由活动子项派生的无障碍名称。 - AR2 — 焦点与惰性。 模态焦点保持在对话框内部,保留的子项为惰性并带
aria-hidden,焦点在最终退出后返回。 - AR3 — 有序关闭。 Esc 键和平台关闭遵循
family:overlay-dismissal,包括 IME 保护和顶层排序。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Sheet 对话框 | 透明的逐 sheet 宿主;活动 sheet 的宿主是流程的交互和无障碍边界(DEC-1) | 当前源码和公开文档;逐 sheet 条款见 DEC-1 | 结构性 | FR2、FR5、AR1 |
| Sheet 面板 | 将可见面板、内容、手柄和手势呈现委托给 BottomSheet | component:BottomSheet 作为观察上下文 |
显著 | FR1、FR3 |
| 遮罩 | 可选的原生背景,在模态呈现中压暗并阻止页面交互;一次仅由一个 sheet 对话框绘制它(DEC-1) | 当前源码和公开文档;单绘制者条款见 DEC-1 | 辅助 | FR5、FR8 |
主题化解剖结构¶
{
"Sheet dialogs": {
"none": {
"reason": "intentional: The transparent dialogs are hosting, positioning, event, and focus machinery rather than a stable painted part."
}
},
"Sheet panels": {
"delegatesTo": {"owner": "component:BottomSheet", "target": "bottom-sheet"}
},
"Scrim": {
"none": {
"reason": "reachability-gap: The native backdrop of the sheet dialog that owns the scrim paints it but has no current public theming target."
}
}
}
家族与系统关系¶
family:overlay-dismissal拥有最顶层 Escape 与平台关闭顺序的所有权;switcher 在可见时采用这一共享所有者。architecture:layer-runtime拥有原生对话框行为与当前托管方式。architecture:component-theming-surface拥有结构(anatomy)限定与目标(target)处置。architecture:public-component-api与spec:AST-002拥有已发布的 prop、DOM、ref 与兼容性表面。spec:AST-027将非模态show()加页面级z-index的通路识别为迁移缺口,而非例外。独立 sheet 的非模态路径托管在 top layer(顶层)中(component:BottomSheetFR11);switcher 自身的非模态流程包装器保留了这个缺口,而其弃用状态决定该缺口应通过移除来关闭,而不是通过重新托管来关闭。spec:AST-017中的 FR26、FR28 与 FR29 规定了生命周期状态、弃用补丁,以及 DEP-0015 所遵循的无运行时警告规则。component:BottomSheet的 DEC-2 拥有流程所参与的堆栈,以及弃用所指向的替换模式。
验证映射¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR4, FR8 | BottomSheetSwitcher.test.tsx |
已关闭、首次打开、按任一完成顺序进行的交接、快速替换、卸载、关闭;在 reduced motion 下于粗指针和细指针上各进行一次交接 | 子元素在错误时机变为可交互、被保留的子元素过早消失、第二层背景遮罩被绘制,或 sheet 对话框的生命周期断裂。在 reduced motion 下,交接不得移动 sheet;在粗指针上,交接不得交叉淡入淡出。 | audit:BottomSheetSwitcher/behavior |
| FR5–FR7, AR1–AR3 | BottomSheetSwitcher.test.tsx;BottomSheetNativeModal.a11y.browser.spec.ts;useScrollLock.test.ts 用于页面的 overscroll |
模态/非模态、信息型/表单型/必填型、嵌套层级、IME、焦点返回、各引擎中的滚动锁定、非模态局部排序 | 模态性、关闭顺序、命名、inert 状态、滚动锁定或焦点行为出现偏差,或 sheet 对话框采用页面级 z-index。 | audit:BottomSheetSwitcher/accessibility |
| FR9 | BottomSheetSwitcher.test.tsx;导出检查 |
ref 在打开/交接/关闭/卸载各阶段中的表现、callback ref 清理、id 只设置一次、DOM/ARIA/data/事件、class、style、xstyle |
受支持的输入项被丢弃或重复,对象型 ref 在 sheet 挂载期间为 null 或跳过了清理,或某个输入项意外覆盖了组件自身的语义。 | audit:BottomSheetSwitcher/api |
| Theming anatomy | scripts/check-knowledge.mjs;主题化测试 |
对话框、被委托的 sheet 面板、scrim(遮罩层) | 不参与绘制的宿主获得了 target,被委托的面板失去其所有者,或 scrim 缺口在未经评审的情况下消失。 | audit:BottomSheetSwitcher/theming |
| FR10 | component:BottomSheet 的堆叠测试套件(switcher 作为其中一个层级的场景);真实浏览器中对某个流程堆叠在独立 sheet 之上和之下时进行 dim 与 recede 采样 |
switcher 底部被独立 sheet 覆盖、switcher 位于独立 sheet 之上、某个步骤的内容中包含一个 sheet、流程在较低 sheet 之上关闭 | 两个背景遮罩被绘制,被覆盖的层级没有退后,被覆盖的流程响应了 Escape,或流程关闭覆盖某个 sheet 时焦点落到 body 上。 |
audit:BottomSheetSwitcher/behavior |
| DEP-0015 | 声明与使用方文档检查(switcher 与 component:BottomSheet 的使用方文档);三个声明上的 @deprecated 元数据;CLI 模板与 story 源文件 |
switcher 的声明、文档、模板和 stories,以及 BottomSheet 的使用方文档 | 某个声明缺少 @deprecated,受维护的模板、story 或 BottomSheet 的使用方文档将 switcher 作为多步骤路径进行介绍,或生产运行时分支、日志或输出随弃用而改变。 |
audit:BottomSheetSwitcher/api |
决策日志¶
DEC-1 — 每个步骤拥有自己的原生对话框;切换器负责协调¶
参考: component:BottomSheetSwitcher/DEC-1
决策者: imdreamrunner,2026-10-20
切换器步骤是一个带有自身原生对话框的 BottomSheet,像独立 sheet 一样被呈现和关闭,因此一种 DOM 形态可同时服务于独立 sheet 和切换器步骤,浏览器也按步骤提供模态性:页面 inert、焦点包含、Escape 和平台关闭触发 cancel,以及背景遮罩。切换器只拥有单个对话框无法决定的事:呈现、保留或关闭哪个对话框;那个从保留对话框移交给进入对话框的遮罩层,且无淡入淡出;当流程返回到某个仍打开在较新对话框下方的 sheet 时重新呈现它;保留对话框关闭时,焦点保持在活动 sheet 中;焦点返回流程的打开者;通过共享的关闭栈,让 cancel 受活动步骤的 purpose 门控;以及流程唯一的页面滚动锁——从模态流程呈现那一刻起持有,直到它退出之后——因此两个打开对话框之间的交接绝不会释放并重新获取该锁。切换器的唯一元素是一个流程包装器:在模态流程中没有盒模型,在非模态流程中则是隔离表面,sheet 对话框在其中以局部值排序。
已否决:由一个切换器拥有的对话框将每个步骤作为面板托管,因为那样步骤就不是 sheet,而且每个独立 sheet 机制都需要第二个仅切换器专用的实现。
已否决:在原生焦点包含之上再加脚本焦点陷阱,因为浏览器已经在模态对话框中包含焦点,而陷阱会与其 inert 特性对抗。
已否决:在非模态步骤的对话框上使用页面级 z-index,因为 spec:AST-027 FR4 禁止新的页面层级;包装器才是隔离的拥有者。
DEC-2 — 宿主对话框的身份是实现细节,而非契约¶
参考: component:BottomSheetSwitcher/DEC-2
决策者: imdreamrunner,2026-10-20
切换器的 ref、id 和 data-testid 会到达托管流程的对话框:活动 sheet 的、退出 sheet 在其退出期间的,以及流程关闭时最后托管它的对话框或第一个已挂载 sheet 的;因此只要 sheet 已挂载,对象 ref 就绝不会是 null,标识属性也只会出现一次。具体是哪个元素,以及它会在交接时变化,属于实现细节。已发布的文档(v0.7.1 BottomSheetSwitcher.doc.mjs)将 ref 描述为“转发到那一个共享原生对话框的 Ref”,并将切换器描述为“它的 ref 和共享 DOM props 以该对话框为目标”。在挂载时只复制一次 ref.current 的代码仍会保留一个真实的 <dialog>,但交接之后该元素可能不再是宿主;请在使用时读取 ref.current,或使用回调 ref,以跟随流程。提供给切换器的 DOM props 和处理函数(className、style、onCancel、onToggle、aria-* 等)会到达每个 sheet 对话框,而 id 和 data-testid 仅在宿主上,因此处理函数会为引发事件的任意 sheet 对话框触发。所有者规定这一托管方式——移动的宿主和每个对话框的 props 都一样——在 spec:AST-017 FR3 下属于非破坏性,因为没有视觉输出和公共 API 表面发生变化。
已否决:将移动的 ref 归类为破坏性变更,因为没有公共 API、文档化交互或视觉输出发生变化。
DEC-3 — 切换器已弃用,改用独立步骤 sheet¶
参考: component:BottomSheetSwitcher/DEC-3
决策者: imdreamrunner,2026-10-23
多步骤流程写作每个步骤一个独立的 BottomSheet,由一个状态值驱动;在同一个更新中关闭当前打开的步骤并打开下一步,无论是从打开步骤内部的控件触发,还是从焦点位于该步骤内时的代码触发,都会执行切换器在其步骤之间执行的那种交接(component:BottomSheet FR10),不需要 sheetId,也不需要包装器,模态和非模态流程皆然。替代方案以不同方式处理的唯一情况,是由流程 sheet 之外的控件改变步骤——非模态流程旁边的页面控件,或焦点位于页面控件上时代码执行操作。这种情况由切换器交接,而独立 sheet 则用各自的动效关闭和打开,因为从 sheet 外部看,一次关闭和一次打开是两个 sheet 各自的变化,而不是同一个人在步骤之间的移动;在焦点位于步骤内或文档 body 上时代码执行操作,则保留交接(component:BottomSheet FR10:操作者位于步骤内部,或不存在操作者)。因此,切换器不再有自己的职责,并被标记为 deprecated(DEP-0015):它继续按发布时的方式工作,本记录的所有要求仍然有效,其声明带有 @deprecated,维护的文档和模板会讲解替代方案,且生产运行时行为没有任何变化。移除是未来已声明的次要版本中的 [breaking] 变更(spec:AST-017 FR28、FR31),此处不做决定。
已否决:将切换器保留为唯一受支持的流程 API,因为同样的交接那时需要两种实现,调用者必须为同一个 UI 在两种心智模型之间做选择。
已否决:在随替代方案发布的同一个版本中移除切换器,因为补丁版本不能携带 [breaking] 变更(spec:AST-017 FR25、FR31),而且已发布的流程必须继续工作。
已否决:在渲染时输出开发模式警告,因为整个组件的弃用会通过其声明和文档体现出来(spec:AST-017 FR29)。
Open questions¶
- OQ1 — 模态性和 scrim 绘制是否应继续通过
hasScrim耦合,还是成为独立的公共概念? (human-api) - OQ2 — 不匹配或重复的子级
sheetId应采用何种安全行为? (human-api) - OQ3 — 切换器所拥有的 scrim 是否应获得一个公共主题化目标? (
human-api)
Content boundary¶
本文件不重复使用方 props 表、审计评分、截图、BottomSheet 面板机制、共享关闭规则或层托管迁移步骤;它会链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx