跳转至

Drawer 组件契约

契约概览

领域 契约
公开契约 @astryxdesign/core 从包根路径和 ./Drawer 子路径导出 Drawer、DrawerProps、DrawerHeader 和 DrawerHeaderProps(DEC-3);@astryxdesign/lab 不导出它们。DrawerProps 扩展 BaseProps<HTMLDialogElement>,单独声明 ref,要求 isOpen、onOpenChange、label 和 children,接受 purpose(required、form 或 info;默认 info)、可选的 padding 间距步进(FR16),以及可选的 experimental 对象(DEC-4),并且没有 hasCloseButton。稳定 API 准入和兼容性归属 architecture:public-component-api;DrawerHeader 记录在 component:DrawerHeader。
行为 Drawer 的可见性由调用方控制,用于一个相对于视口、全高度的逻辑侧边覆盖层。hasScrim 在原生打开时选择 showModal() 或手动 Popover API 宿主;打开期间更改该值不受支持。共享的图层关闭堆栈在整个渲染生命周期内门控 Escape 和平台关闭,purpose 与 Dialog 中一样决定 Escape、平台关闭和遮罩点击是否请求关闭。Drawer 本身不渲染关闭控件。浏览器顶层(top layer)在两种呈现方式中都拥有绘制顺序;退出时渲染当前子元素;完成关闭后,焦点返回到打开时聚焦的元素。
终端用户影响 抽屉自身不绘制关闭控件;当调用方在 DrawerHeader 标题行中组合关闭按钮时,该按钮才会出现。form 抽屉忽略遮罩点击,required 抽屉忽略 Escape、平台关闭和遮罩点击;模态 required 抽屉会被宣告为警告对话框(alert dialog)。共享的顶层/IME Escape 路由、顶层绘制顺序、每次请求一次关闭,以及焦点返回在两种呈现方式中均适用。
构建方影响 从 @astryxdesign/core/Drawer 或 Core 根路径导入。若要显示可见的关闭操作,请在 Layout 的 header 插槽中组合 <DrawerHeader title onOpenChange>,就像在 Dialog 中组合 DialogHeader 一样。默认情况下,Content 区域按 --spacing-4 向内缩进;padding={0} 会使 Content 区域变为全宽通栏。在 Dialog 会设置 purpose 的地方设置 purpose。状态和内容仍由调用方拥有;Drawer 在退出期间渲染调用方当前的子元素。同级组合是当前给使用方的指导;如果使用方的 onKeyDown 阻止了默认行为,则会取消 Escape 关闭。
兼容性/就绪状态 记录已发布行为;无公开变更。Drawer 是一个 Core 组件,从 @astryxdesign/core/Drawer 导入(DEC-3)。五个实现差距列于“当前状态影响”之下。
审查检查 拒绝区域性、停靠式或块轴模型;拒绝“模态性与遮罩目前相互独立”的说法;拒绝重新引入 Drawer 本地 Escape 注册表、页面级 z-index 区间或 Drawer 自有关闭按钮;拒绝与 Dialog 的 purpose 相背离的关闭策略;拒绝声称混合呈现或嵌套堆叠在共享堆叠契约之外仍得到保证;拒绝任何残留的 @astryxdesign/lab 导出;拒绝 architecture:public-component-api 尚未承认的稳定 API/主题兼容性声明。
治理规则 family:overlay-dismissal; architecture:layer-runtime; architecture:container-padding; spec:AST-027/DEC-3; design:reduced-motion。

此表为评审投影;以下正文为权威内容。

意图

Drawer 在浮动于当前页面之上且不使其重排的全高侧边面板中呈现上下文相关细节或控件。它支持带遮罩的模态检查,以及非模态的主从检查,后者使后方页面保持可用。

本记录涵盖仅限视口的 Core 组件:其共享的层生命周期、与 Dialog 对齐的关闭控件与关闭策略(DEC-1),以及其容器内边距(DEC-2)。它不引入 scope 概念。特别是,它不会复活区域、窗格作用域或容器定向的 Drawer 模型。

兼容性与迁移

  • 已发布默认行为保留:yes。
  • 兼容性分类:记录已发布行为;无公共变更。Core 从根路径和 ./Drawer 子路径导出 Drawer;@astryxdesign/lab 不导出。
  • 容器内边距(FR16, DEC-2):padding prop 或主题中 drawer 上的 padding 通过容器 token 为内容区域提供内缩。两者均未设置时,内缩量为 --spacing-4,与 Dialog 一致;padding={0} 保持通栏(full-bleed)内容区域。块末安全区内缩在所有模式下均生效。
  • 实验性表面(DEC-4):移动端全视口覆盖是可选 experimental prop 对象中的 isFullWidthOnMobile 选项,不在稳定兼容性承诺范围内(spec:AST-017/FR21)。省略 experimental 时保留 56px 页面露出。
  • 受控/非受控行为:Drawer 自有路径未变;调用方提供 isOpen,而通过公共 dialog ref 进行的直接原生变更不在该保证范围内。
  • 迁移决策:无。

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

  • Drawer 构建自己的顶层、退场和背景。 Drawer 挂载自己的模态与 popover 宿主,运行自己的退出保持,并绘制自己的遮罩。architecture:layer-runtime INV14 要求 layer 使用运行时的顶层挂载、呈现保持、退出副本和背景色调。
  • 减少动态设置下,每次指针操作仍保留 0.01 秒滑动。 在减少动态设置下,滑动和遮罩过渡仍会运行 0.01 秒。对于精确指针,design:reduced-motion 的 DR1 禁止位移,DR3 不允许任何动画属性;触控用户不会获得不透明度淡入淡出——这正是 DR2 所要求的。
  • 只有在粗粒度主指针下,手指的输入才会在入场期间被保持。 在这种情况下,如果抽屉仍在入场时发生点按或拖动,则不会命中任何内容;对于非模态抽屉,只有面板上的输入会被保持。当主指针为精确指针且屏幕也支持触控(如触屏笔记本电脑)时,入场期间手指点击遮罩会关闭 info 抽屉,而点按或拖动会到达面板。spec:AST-094 FR35 会保持指针输入,直到入场完成。
  • 调用方提供的 onCancel 永远不会运行。 Drawer 在调用方 props 之后设置自己的 onCancel,因此调用方的 onCancel 会被丢弃。architecture:public-component-api INV5 要求被接受的事件输入到达元素。
  • 容器内边距记录中未列出 Drawer。 Drawer 的内容区域发布其内缩量(FR16, DEC-2),但 architecture:container-padding 未将 Drawer 列为其容器发布者之一。

所有权边界

拥有

  • 视口相对的侧边面板表面、逻辑边缘、inline-size 预算,以及入场/退场动效。
  • 模态遮罩的外观(FR20)。
  • 当前呈现输入:在原生打开时,其值选择 showModal() 或手动 Popover API 宿主。打开期间更改该值不受支持。
  • Drawer 本地的焦点进入/返回、purpose 关闭策略、未取消的背景点击处理,以及在受控退出期间保留其宿主并继续渲染调用方当前拥有的子内容。
  • 内容区域的容器内边距,按 architecture:container-padding 发布;根 dialog 仍是覆盖层边界的拥有者。
  • 在其渲染生命周期内,将 layer 注册到共享关闭栈。Escape 与平台关闭路由属于共享拥有者;两种呈现中的绘制顺序属于浏览器顶层。

不拥有 / 非目标

  • 调用方提供的表单、检查器、页脚或其他内容。DrawerHeader 是可选组合,不是必需结构。
  • 块轴方向的 sheet 面板——由 component:BottomSheet 拥有。
  • 保留布局空间或推开页面内容的持久面板。
  • 区域性(regional)或窗格作用域(pane-scoped)的放置、调用方提供的容器,或独立的模态性与遮罩轴。这些都不是当前 Drawer 的概念。
  • 跨家族的 Escape 与平台关闭排序——由 family:overlay-dismissal 拥有;Drawer 通过共享拥有者参与。
  • DrawerHeader、其标题行、关闭操作和目标——由 component:DrawerHeader 拥有。

公共概念

使用方 prop 语法及示例保留在 Drawer.doc.mjs 中。

概念 闭合值或状态 含义 按状态可用性 默认值 所有者 稳定性 无效值行为
可见性 open、closed 是否请求由调用方控制的 Drawer 呈现 所有呈现形式 调用方控制 component:Drawer 核心契约 必填受控值
逻辑边 inline start、inline end 面板进入和退出所经由的视口边缘 打开和退出时 inline end component:Drawer 核心契约 闭合类型拒绝其他值
呈现形式 模态(带遮罩)、非模态(不带遮罩) 原生宿主模式以及相关的文档语义 在原生宿主打开时选择;不支持实时变更 模态(带遮罩) component:Drawer 核心契约 一个当前布尔值选择初始模式
行内尺寸预算 像素数值或有效的 CSS 长度 桌面端行内尺寸以及揭示模式的移动端上限 桌面端及移动端页面揭示模式 400px component:Drawer 核心契约 无效 CSS 长度不受支持
移动端覆盖 页面揭示、全视口 窄视口是否保留可见的页面条带 视口处于移动端边界或以下时 56px 页面揭示 component:Drawer 实验性(DEC-4) 闭合布尔类型
关闭用途 info、form、required 允许哪些隐式关闭请求:info 允许 Escape、平台关闭和遮罩点击;form 允许 Escape 和平台关闭;required 不允许任何关闭方式 所有呈现形式;遮罩点击仅适用于模态 info component:Drawer 核心契约,与 Dialog 匹配 闭合类型拒绝其他值
头部关闭操作 rendered、absent DrawerHeader 是否渲染其关闭按钮 组合了 DrawerHeader 的所有位置 默认不渲染,除非传入 onOpenChange component:DrawerHeader 核心契约 省略回调时不渲染按钮
内容内边距 间距步进、主题 drawer 内边距或默认值 滚动内容区的容器内边距,按 architecture:container-padding 发布给后代元素 所有呈现形式 --spacing-4,与 Dialog 一致 component:Drawer 核心契约,与 Dialog 匹配 闭合数值类型拒绝其他值
同级顺序 更早打开、更晚打开、退出中、已关闭 共享堆栈中的 Escape 资格以及浏览器顶层绘制顺序 任一呈现形式中的同级 Drawer 更晚打开者位于最上层 component:Drawer 核心契约 嵌套组合不在已记录契约范围内

行为与布局契约

ID 不变量 依据
FR1 Drawer 必须保持为相对于视口、占满整个块级尺寸的覆盖层,位于逻辑内联起始端或内联结束端边缘,并且不得保留布局空间,也不得使其下方的页面重新流动。 当前源代码、文档、story 与测试
FR2 打开的 Drawer 所选的逻辑边缘必须在其退出期间保持锁定,即使调用方在关闭过程中更改了实时的边缘属性。 当前退出侧测试与实现
FR3 桌面端内联尺寸预算必须接受像素数字或 CSS 长度,并保持受视口约束。在 640px 及以下时,页面揭示模式必须保留 56px,并使用 width 作为上限;全移动模式必须用 100dvw 覆盖 width。 当前文档、样式与宽度测试
FR4 通过 Drawer 自身行为实现的可见性必须遵循 isOpen,从水合后的渲染开始(FR17)。由共享栈路由的未取消 Escape,以及未取消的模态背景激活请求,在 purpose 允许时(FR15)请求 false,且按压不会关闭 Drawer 上方任何已打开的层(FR6);DrawerHeader 的关闭操作通过其被赋予的回调请求 false;Drawer 阻止其处理的原生 cancel 事件直接关闭对话框。在受控退出期间,Drawer 在渲染调用方当前的 children 时,保持其宿主与内容区域处于挂载状态。 当前属性契约与生命周期测试
FR5 打开时,hasScrim={true} 必须选择原生 showModal(),并带 aria-modal、焦点陷阱、页面滚动锁定以及可见背景层;在锁定状态下,下拉刷新与页面回弹停止,因为模态下的滚动锁定会保持页面(spec:AST-094 FR19),如同位于 UIKit 模态呈现之后;hasScrim={false} 必须选择手动 Popover API 宿主,使页面保持在其后可交互。打开时更改 hasScrim 不是支持的原生模式转换。 当前源代码、文档与初始模式测试
FR6 在模态背景上开始并结束的未取消按压(指针按下、指针抬起、点击的 target === currentTarget,且实时的 hasScrim 为 true;family:overlay-dismissal FR10)必须在 purpose 为 info 时请求关闭,除非该按压对 Drawer 上方已打开的层进行轻触关闭,而该层会消耗该事件(family:overlay-dismissal FR11);当 purpose 为 form 或 required 时则不得请求关闭;按压从任一侧越过 Drawer 边缘都不得请求关闭。当实时的 hasScrim 为 false 时,后代点击与对话框根节点点击不得请求关闭,且非模态呈现不得安装不可见的外部指针关闭平面。 当前点击测试;useBackdropPress.test.tsx
FR7 Drawer MUST NOT 自行渲染关闭控件。可见的关闭操作由调用方组合,通常是带有 onOpenChange 的 DrawerHeader(component:DrawerHeader FR3),它通过该回调请求 false,而无需取得打开状态的所有权。 DEC-1;关闭控件套件
FR8 打开时 MUST 呈现原生宿主,捕获打开前聚焦的元素,并尝试聚焦第一个渲染的 [data-autofocus] 后代(如有)。受控关闭完成并释放原生宿主后,Drawer MUST 尝试将焦点恢复到捕获的元素。非模态宿主的合成 close 事件 MUST 在该恢复尝试之后派发——与任务队列中的原生 dialog.close() 事件一致——以便消费方关闭监听器对最终焦点拥有最后决定权。当打开的 Drawer 卸载时,如果焦点可能丢失(留在页面 body 或已离开文档的节点上),它 MUST 将焦点返回到捕获的元素;仅开发环境的模拟卸载不视为移除。 当前存在性 hook 与焦点测试
FR9 关闭时 MUST 在退出动画仍然可见期间保留面板宿主、内容区域、边缘和原生呈现,并继续渲染调用方当前的 children。变换过渡具有权威性,计算出的持续时间后备可防止丢失事件使宿主滞留,而且原生释放与 React 隐藏同步落地,因此不会有任何帧在顶层之外绘制。 当前生命周期测试和浏览器关闭可见性保护
FR10 同级 Drawer MUST 作为同级进行组合。最后打开的当前同级通过共享堆栈拥有第一次 Escape 请求的所有权;正在关闭的同级在其可见退出期间保留该所有权,而重新打开会注册一个新的活动周期,因此一次请求绝不会关闭两个表面。两种呈现中的绘制顺序均遵循浏览器顶层的时间顺序。 当前文档、共享堆栈和测试
FR11 DrawerProps 扩展 BaseProps<HTMLDialogElement> 并单独声明 ref。根元素过滤 open,合并 xstyle、className 和 style,转发其余未认领的 props,组合消费方的 onClick,在共享的文档级 Escape 所有者之前转发消费方的 onKeyDown,并拥有 aria-label、aria-modal,以及对于模态 required 抽屉的 role="alertdialog"。实现缺口:消费方的 onCancel 会被丢弃(当前状态影响)。消费方 onKeyDown 若阻止默认行为,则会取消本次按键的共享堆栈 Escape 关闭。 当前源码和聚焦键盘测试
FR12 绘制的根对话框会发出文档化的 drawer 目标和 side 选择器轴,并应用容器内边距重置。DrawerHeader 的目标由 component:DrawerHeader FR5 所有。目前不会为内容或遮罩发出单独的 Drawer 目标;未来的目标限定仍归 architecture:component-theming-surface 所有。 当前源码、文档和结构目标元数据
FR13 Drawer MUST 在其完整渲染生命周期内加入共享关闭栈,为后代图层提供逻辑深度,将平台关闭操作路由到相同的顶层/IME 决策,并保留消费者对 preventDefault() 的所有权。 共享家族契约和聚焦测试
FR14 非模态 Drawer MUST 使用手动 Popover API 宿主,使跨表面顺序来自浏览器顶层而非页面级 z-index 带。降级回退仅在低于 Popover API 支持下限时才可使用 dialog.show()。 当前源码、浏览器守卫与 spec:AST-027
FR15 purpose 取值与默认值与 Dialog 的 prop 相同。info(默认)允许 Escape、平台关闭和模态遮罩点击请求关闭;form 允许 Escape 和平台关闭请求关闭并忽略遮罩点击;required 不允许任何请求关闭,以 block 身份注册到共享栈,使请求不会到达更低层,并将模态 drawer 暴露为 role="alertdialog"。在没有遮罩时,form 和 info 行为相同。 DEC-1;purpose 套件;family:overlay-dismissal Escape 行为
FR16 Content 区域按 drawer 的容器内边距填充调用方内容,默认与 Dialog 一样为 --spacing-4,并像容器发布者一样将所应用的内边距发布给后代;architecture:container-padding 目前不承认 Drawer 是其中之一(当前状态影响)。其块末边缘应用容器内边距加上 Home 指示器安全区域,而仅发布内边距本身,因此出血子元素只减去内边距,安全区域仍保留在其下方。根 dialog 保持容器内边距重置(FR12)。 architecture:container-padding;容器内边距套件
FR17 在服务端打开的 Drawer 在 hydration 之前保持关闭渲染(无 open 样式、无 aria-modal,即关闭状态 Drawer 的标记),并在 hydration 之后的首次渲染中打开,这是第一个能进入其原生宿主的渲染;它绝不声称自己不具备的模态性(spec:AST-020 FR1,WCAG 2.2 SC 4.1.2)。服务端渲染与 hydration 渲染产生相同的标记(spec:AST-013 FR9),且 hydration 后的打开是稳定的,没有任何进入动画;之后的打开与关闭照常带动画(spec:AST-013 FR13)。 spec:AST-020 FR1
FR18 当模态 Drawer(hasScrim)打开时,它将其 <dialog> 作为被动全局出口,因此应用全局表面(如 toast)在其中渲染、绘制于其上方,并保持可操作且可通过键盘触达;当它开始关闭时,停止提供该出口,于是这些表面返回原位,不会随退出动画被带走。移动它们会保留 toast 的进入效果、计时器和焦点交接(spec:AST-003 FR18, FR19)。非模态 Drawer 不提供任何出口(architecture:layer-runtime)。 spec:AST-003 FR18
FR19 当非模态 Drawer(hasScrim={false})通过 showPopover() 进入顶层时,之前已显示的顶层 toast 视口会离开顶层,然后原位重新进入顶层,并将焦点保持在其内部,因此 toast 绘制在 drawer 之上;drawer 不提供任何出口,其关闭不会移动或重新进入任何内容(architecture:layer-runtime)。 architecture:layer-runtime
FR20 Drawer 的 scrim 是主题的 --color-overlay 调暗效果,且在所有指针设备上均不模糊;在强制颜色模式下,drawer 保持可见边缘。 所有者决定,2026-10-25:遮罩层保持由主题控制,并且在所有指针设备上均不模糊。

允许的变体

  • AV1 — 调用方内容。 任何可渲染的 inspector/detail 内容都可以占据滚动内容区域,而不会成为 Drawer 所属的解剖结构。Drawer 渲染当前 children;调用方决定底层数据在退出期间是否保持可用。
  • AV2 — 内联尺寸。 消费者可以在有效的 CSS 和视口约束内选择桌面端预算。在移动端页面揭示模式下,它仍然是上限,而全移动端模式改用 100dvw。
  • AV3 — 呈现方式。 原生打开时的值决定选择模态对话框还是非模态 popover 宿主。打开状态下更改 hasScrim 不受支持。
  • AV4 — 关闭控制。 调用方选择是否渲染关闭操作,通常是带 onOpenChange 的 DrawerHeader,或者使用他们自己的控件。
  • AV6 — 关闭目的。 调用方选择 info、form 或 required。
  • AV5 — 动效时长。 主题可以更改 transform 过渡的持续时间;关闭时机遵循计算后的 CSS 和减弱动效偏好。

代表性状态

状态 必需的不变式 允许的变体
关闭 无原生呈现或可见面板 调用方内容可在 React 中保持挂载
模态检查器 通过 showModal() 以 hasScrim 为 true 打开,具有 scrim、模态语义、焦点陷阱和 body 锁定 边缘、宽度、调用方内容、自动聚焦目标、头部关闭操作和目的
非模态主从检查器 通过手动 popover 宿主以 hasScrim 为 false 打开;没有 scrim、aria-modal 或 body 锁定;背后的页面保持可交互 边缘、宽度、调用方内容、头部关闭操作和目的
必需的模态 drawer Escape、平台关闭和 scrim 点击均不会关闭;以 alertdialog 暴露;下层不会收到 Escape 调用方提供的退出方式
窄视口与页面揭示 面板不超过其 width 上限,并保留页面的 56px 低于上限的请求宽度
窄屏全覆盖视口 面板使用 100dvw,覆盖请求的 width 调用方内容
两个同级 Drawer 后打开并保持打开的 Drawer 通过浏览器顶层绘制在上方,并通过共享堆栈拥有第一个 Escape 请求 边缘、宽度、调用方内容,以及以兄弟节点组成的任一呈现方式
退出中的 Drawer 退出动画可见期间,面板宿主、内容区域、逻辑边缘、原生呈现方式和堆栈注册仍然保留;当前子节点继续渲染 调用方可控制的子节点数据和动画时长

转换与优先级顺序

  • ORD0 — 内容内边距。 首先使用 padding prop,然后是主题在 drawer 上的 padding 属性,再是 --spacing-4,与 Dialog 中一致。在所有模式下,块末尾的安全区域 inset 在该解析之后添加。
  • ORD1 — 打开。 解析当前逻辑边缘和宽度,保留已渲染的面板,捕获当前聚焦的元素,使用当前的 hasScrim 选择原生宿主,然后遵循渲染出的自动聚焦目标。
  • ORD2 — 关闭。 在受控关闭期间,Drawer 在退出动画期间保持面板和调用方提供的内容可见。过渡完成或按计算时长运行的兜底计时器会一起释放原生宿主并隐藏 React 输出,因此呈现结束时不会出现中间可见帧;随后 Drawer 会尝试将焦点恢复到之前聚焦的元素(如果可用)。非模态宿主的合成 close 事件仅在该恢复尝试之后派发,因此重新定位焦点的消费方关闭监听器会观察到与任务队列中的原生事件相同的收尾顺序。
  • ORD3 — 兄弟顺序。 兄弟顺序来自共享的关闭堆栈和浏览器顶层:在两种呈现方式中,最后打开的可见兄弟位于最前,并首先处理 Escape。后代浮层仍由它们各自的组件和家族契约管理,而非 Drawer 嵌套。

性能与资源

  • PR1 — 仅退出期资源。 过渡监听器和兜底计时器仅在关闭等待可见 transform 退出时存在,并在完成、中断或卸载时移除。
  • PR2 — 呈现清理。 原生呈现方式和任何启用的 body 滚动锁定仅在其活动状态期间存在,并在受控关闭、卸载或隐藏 Activity 清理时释放。
  • PR3 — 相对视口的尺寸。 Drawer 根据 width、实验性的 experimental.isFullWidthOnMobile 选项(DEC-4)和视口计算尺寸;调用方无需提供区域性的测量目标。

无障碍契约

  • AR1 — 名称。 label 是转发到 aria-label 的必需字符串;调用方内容不用作隐式名称。当前代码不会拒绝空值或仅含空白字符的值。
  • AR2 — 模态真实性。 打开时,hasScrim={true} 使用原生模态对话框状态和 aria-modal;hasScrim={false} 使用非模态 popover 宿主并省略 aria-modal。模态 required drawer 使用 role="alertdialog"。在打开状态下更改 hasScrim 不是受支持的过渡。
  • AR3 — 键盘关闭。 Escape 请求仅通过共享堆栈关闭最顶层的已注册层,且仅在 purpose 允许时;required drawer 会消费该请求。阻止默认行为的消费方 onKeyDown 会取消该关闭,且无关按键不会关闭。
  • AR4 — 焦点生命周期。 焦点通过文档记录的自动聚焦/原生路径进入可见的 Drawer 内容,并且在受控关闭完成后,Drawer 会尝试将焦点恢复到 Drawer 打开时处于活动状态的元素。
  • AR5 — 关闭控件。 Drawer 本身不提供关闭控件;DrawerHeader 关闭操作的名称和行为由 component:DrawerHeader 负责。
  • AR6 — 方向与动效。 逻辑内边距的放置和滑动方向的镜像遵循最近的生效 dir 属性所表示的 DOM 方向性,包括显式的局部覆盖或继承的方向。按照 design:bidirectionality 的要求,方向与其祖先不同的区域应在 DOM dir 中描述该方向;仅靠 CSS direction 声明不是受支持的替代方式。在减少动效设置下,进入和退出在粗指针上为不超过 200 ms 的仅透明度淡入淡出(design:reduced-motion DR2),否则立即完成(DR3),最终状态不变,但减少动效造成的差异(当前状态影响)除外。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
面板 绘制全高的侧面表面,并负责边缘、宽度、边框、阴影和动效。 当前源代码和公开文档 突出 FR1–FR3, FR9, FR12
内容区域 提供全高滚动和容器内边距,用于承载调用方所有的检查器内容。 当前源代码和公开文档 主要 FR4, FR16, AV1
头部 DrawerHeader 提供标题行,并在传入 onOpenChange 时提供关闭操作。 component:DrawerHeader 辅助 FR7, AR5
模态遮罩层 在初始模态打开时,传达基于遮罩的呈现方式,并在面板后方的根节点点击时提供激活行为。 当前源代码和公开文档 辅助 FR5, FR6, FR20, AR2
页面显露 在窄视口下保留遮罩上下文,除非请求全屏覆盖。 当前公开文档 辅助 FR3

根 Panel 承载当前 drawer 目标并反映 side;DrawerHeader 的目标由 component:DrawerHeader 拥有。内容区域或模态遮罩层无法触达独立的 Drawer 目标,未来的目标限定此处不作决定。目前尚未记录解剖结构-主题映射;该映射块在迁移期间是可选的,因此映射被推迟。

组件族与系统关系

  • family:overlay-dismissal 负责跨组件的 Escape 和平台关闭顺序。Drawer 在其渲染生命周期内通过共享所有者参与,并为后代图层提供逻辑深度。
  • architecture:layer-runtime 负责区分原生模态托管、非模态对话框呈现、顶层行为以及共享图层管道。与 Dialog 一样,Drawer 的内容根节点应用共享的私有文本基线和图层内容边界:表面作用域的祖先成员关系在 drawer 处终止,而普通应用上下文继续流入其内容。
  • architecture:public-component-api 负责稳定的 API 准入与兼容性。FR11 记录当前的 DOM/ref/事件可达性,但不就此做出稳定的兼容性决定。
  • architecture:react-component-runtime 负责 effect/资源清理、原生宿主同步以及节点/生命周期安全。本记录涵盖 Drawer 自身的可见关闭与焦点交接结果。
  • architecture:component-theming-surface 负责目标限定与未来的解剖结构映射;本记录仅涵盖现有的 drawer 目标。
  • architecture:container-padding 负责共享的容器内边距协议。它尚未将 Drawer 的内容区域接纳为容器发布者(FR16)。
  • spec:AST-027/DEC-3 要求等效的浮动交互使用适用的原生顶层宿主。模态 showModal() 和非模态的手动 Popover 托管满足这条跨表面路径;文档记载的降级回退方案仍低于 Popover API 的支持下限。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR7 Drawer.test.tsx 的渲染、初始模式、点击、尺寸、side 和控制套件 关闭/打开、两侧边缘、初始模态/非模态模式、移动端宽度 布局重排;初始模式获得错误的语义;未取消的根节点点击或移动端全屏尺寸变得不确定。 audit:Drawer/behavior
FR11 Drawer 源代码及聚焦键盘组合/取消测试 过滤后的 open、合并的样式/ref、转发的未认领 props、自有的 ARIA/cancel、组合点击、转发的 keydown 未经审查就更改当前的转发行为,或共享栈中的 Escape 忽略了文档记载的消费者取消。 audit:Drawer/public-api
FR8, AR1–AR5 Drawer.test.tsx 的标签转发、自动聚焦、关闭和焦点返回套件,以及浏览器守卫的最终焦点检查 初始模态/非模态模式、自动聚焦目标、已连接的先前聚焦元素、关闭监听器重定向焦点 焦点在呈现前移动、受控关闭完成后未能恢复焦点、合成关闭覆盖消费者监听器的焦点目标,或标签转发/关闭命名失效。 audit:Drawer/accessibility
FR8(卸载) Drawer.test.tsx 中的 "Drawer unmounting while open" 测试套件;DrawerUnmountFocus.a11y.chromium.spec.ts(点击与 Enter 键) 非模态和模态抽屉仅在打开时渲染,并由其自身控件移除;随其视图一起移除;焦点先移至外部;StrictMode 重新挂载 打开的抽屉卸载后焦点留在页面主体上,或焦点从用户移到的位置被拉回,或移动焦点的 StrictMode 重新挂载失败。 audit:Drawer/accessibility
FR9、PR1–PR2 关闭时序测试、浏览器关闭可见性守卫,以及 presence-hook 源码检查 受控关闭、transform 结束、无关的 transition、事件丢失兜底 原生呈现在可见退出之前结束,宿主被搁置,清理路径保留资源,或中间帧在原生呈现之外绘制。 audit:Drawer/motion
FR10、FR13、AR3 Drawer 共享堆栈测试套件,以及 useLayerDismissal 及其家族测试 同级抽屉、关闭顶部抽屉、重新打开、卸载、嵌套后代 一次 Escape 关闭两个表面,正在关闭的宿主丢失所有权,或重新打开的同级抽屉保留过时的顺序。 audit:Drawer/layers
FR14 Drawer 源码,加上 spec:AST-027 影响清单和原生宿主浏览器守卫 模态宿主、manual-popover 宿主、降级回退 非模态呈现回退到页面级层级,或丢失原生宿主的顺序。 audit:Drawer/layers
FR15 Drawer.test.tsx 用途测试套件 info、form、required;模态和非模态;位于 required 抽屉后面的同级抽屉 form 抽屉在点击遮罩(scrim)时关闭,required 抽屉关闭或让 Escape 到达其后面的抽屉,或它的 role 语义发生偏移。 audit:Drawer/behavior
FR12 源码、Drawer.doc.mjs,以及当前目标发现 start/end 根 Panel 与继承的容器上下文 当前根目标/轴或内边距重置发生变化,或记录声称存在不可达的子目标,或决定了未来的准入。 audit:Drawer/theming
FR16 Drawer.test.tsx 容器内边距测试套件;defineTheme.test.ts 抽屉映射;浏览器证据 默认、padding 属性、主题 padding、单独的带内边距 Section 子元素、Layout 组合 公布的 inset 与应用的内边距不一致,默认抽屉改变几何形状,或块末端安全区域丢失或被重复扣除。 audit:Drawer/theming
AR6 DrawerDirection.test.tsx DOM 方向及关闭/进入一致性测试套件,以及 exact-head Storybook RTL 证据 start/end;自身应用、继承及嵌套的相反 dir;关闭与打开时的 transform 任何有效的 DOM 方向或局部覆盖都会使面板从不同于其逻辑放置的边缘移动,或者关闭与打开时的 transform 不一致。 audit:Drawer/accessibility
FR17 Drawer.ssr.test.tsx 服务端打开;水合;关闭状态 Drawer 的标记 若打开状态的服务端渲染带有 aria-modal、打开样式或不同于关闭状态的标记,或出现水合错误、水合后没有 showModal()、水合后立即打开时有入场动画,或之后打开时没有入场动画,则测试失败。 audit:Drawer/accessibility
FR18 ToastViewport.modalHost.test.tsx 中的 "ToastViewport above a Drawer" 套件;DrawerToastOutlet.a11y.chromium.spec.ts(在桌面和手机宽度下进行命中测试、点击与 Tab 键操作) 模态 Drawer 打开在页面 toast 之上;从 Drawer 内部弹出 toast;Drawer 关闭;没有遮罩的 Drawer 若 Toast viewport 被留在打开的模态 Drawer 之外、toast 随关闭的 Drawer 一起被带走、toast 行被重新挂载,或非模态 Drawer 接管了 viewport,则测试失败。 audit:Drawer/accessibility
FR19 ToastViewport.modalHost.test.tsx 中的 "ToastViewport above a Drawer" 非模态用例;DrawerToastOutlet.a11y.chromium.spec.ts 非模态用例 toast 在无遮罩 Drawer 打开并盖住它的边角之前显示;随后 Drawer 关闭 若 toast 被无遮罩 Drawer 覆盖、viewport 被移入 Drawer,或关闭时发生重新进入,则测试失败。 audit:Drawer/accessibility
FR20 modalBackdrop.test.tsx;ModalBackdrop.a11y.browser.spec.ts(Chromium 和 WebKit) 手机宽度下的手指;桌面宽度下的鼠标;任一指针下的强制颜色 若在任一宽度下遮罩上出现 backdrop-filter,或在强制颜色下没有可见边缘,则测试失败。 audit:Drawer/theming

以下内容来自源码阅读,尚无聚焦测试:

  • FR1:不预留布局空间,也不让页面重排。
  • FR5:模态 Drawer 的页面滚动锁定。
  • FR9:计算持续时间的兜底机制。
  • FR13:后代层的逻辑深度,以及平台关闭路由。
  • FR14:低于 Popover API 支持下限时回退到 dialog.show()。
  • PR1–PR2:监听器、计时器、呈现和滚动锁定的清理。

决策日志

  • DEC-1 — 关闭控件与关闭策略与 Dialog 一致(所有者决定,2026-10-01)。Drawer 不渲染内置关闭按钮,也没有 hasCloseButton;它采用 Dialog 的 purpose 取值和默认值;DrawerHeader 具有 DialogHeader 的 API,仅在传入 onOpenChange 时渲染关闭操作。使用 Drawer 自有的 header(而非 DialogHeader),可以保留 Drawer 的焦点进入方式(原生呈现后设置 data-autofocus)和 label 命名,并避免 dialog-header 主题目标。已拒绝:仅对 required 隐藏的内置按钮;复用 DialogHeader。

  • DEC-2 — Drawer 与 Dialog 一样是一个容器(所有者决定,2026-10-08)。可滚动的内容区域是遵循 Dialog 契约的容器发布者:padding 属性采用 Dialog 的间距步进刻度;drawer 上的主题 padding 展开为 --astryx-drawer-padding* 容器 token;默认值 --spacing-4 由边缘与 Layout inset 链共享。DrawerHeader 位于 Layout 的 header 插槽中,Layout 会将该 inset 重新分配到其各个区域,因此 header 不会被重复 inset。块结束(block-end)边缘在所有模式下都会在 inset 之上额外加上主屏指示器安全区。已拒绝:对面板根节点(浮层边界)设置 padding;默认完全铺满(与 Dialog 不一致)。

  • DEC-3 — Drawer 是一个 Core 组件(所有者决定,2026-10-08)。Drawer、DrawerHeader 及其属性类型随 @astryxdesign/core/Drawer 和 Core 根入口一起提供,其文档站点示例也是 Core 块。@astryxdesign/lab 不导出它们。

  • DEC-4 — 移动端全视口覆盖为实验性功能(所有者决定,2026-10-15)。isFullWidthOnMobile 位于可选的 experimental 属性对象中,在声明中标记为 @experimental,在编写文档中标记为 stability: 'experimental',因此它可能在补丁版本中变更或被移除(spec:AST-017/FR21)。省略 experimental 会保留 56px 的页面露出。已拒绝:设置一个顶层的稳定 isFullWidthOnMobile 属性。

未决问题

  • DrawerHeader 是否应该像 DialogHeader 为 Dialog 所做的那样,通过 aria-labelledby 提供默认焦点目标并为 Drawer 命名?目前 label 是必需的,焦点进入使用 data-autofocus。
  • 显式 padding prop 是否应继续添加 block-end 安全区(DEC-2),还是采用 Dialog 的全屏规则,即显式值完全取代安全区回退?
  • DrawerHeader 的 endContentEdgeCompensation 轴值如何映射到 endContentEdge 的处理值,这一问题记录在 component:DrawerHeader 的未决问题中。

区域放置、独立的 modality/scrim 轴以及块轴方向的 sheet 均不在当前组件边界内。任何针对它们的未来提案都需要新的公共 API 和设计授权。

内容边界

本文件不重复使用方 prop 表格或示例、共享的关闭栈(dismissal-stack)内部机制、过渡算法、当前审计分数、实施步骤或共享的家族/系统规则。它链接到这些内容的所属方。

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