interior 的 Modal、Drawer 与 Command Palette 如何处理焦点陷阱、滚动锁定与碰撞翻转:完整指南

原创2026-10-18 17:29:511,910 阅读

interior 的 Modal、Drawer 与 Command Palette 如何处理焦点陷阱、滚动锁定与碰撞翻转:完整指南

interior 是一个面向 React 的开源微交互组件库(micro-interactions for react),专为"点击后那半秒钟"而设计。本文带你读懂它 Overlay 类组件——Modal、Drawer、Command Palette 与 Popover——是如何把焦点陷阱(focus trap)、滚动锁定(scroll lock)和碰撞翻转(collision flip)这三个最容易写崩的细节做对的,帮你避开自己手写浮层时最常见的坑。

interior 组件库演示图片:Overlay 组件打开浮层后背景页面被锁定滚动的场景示意

为什么浮层组件最容易"翻车"

每个 React 项目都会做弹窗,但很少有人把它做完。README 里的原话很直白:

Everybody builds these components. Almost nobody finishes them. The missing twenty percent is always the same three things: a jump, a restart, an animation that ignores the person watching it.

浮层的"缺失 20%"集中在三件事:

  • 焦点跑出去:Tab 键跳到了遮罩后面的页面元素,读屏软件开始朗读背景
  • 背景页面跳动:锁定滚动时滚动条消失,布局左右抖一下
  • 贴边溢出:下拉菜单、气泡贴在视口边缘时直接跑出屏幕

interior 的解法可以概括为一句话:每个组件只有一个依赖(motion),行为全部封装在 useX hook 里,样式组件只是示例。你只拷一个文件,就能拿到完整的无障碍与边界处理。

焦点陷阱:Tab 键永远出不去

Modal:Tab 循环 + 失焦拉回

components/interior/modal.tsx 中的 useModal 实现了完整的焦点管理,分三层:

  1. 打开即聚焦:优先聚焦 initialFocusRef 指定的元素(危险操作弹窗里应指向"取消"按钮),否则聚焦面板内第一个可聚焦元素
  2. Tab 循环:在最后一个元素按 Tab 跳回第一个,Shift+Tab 反向循环;若面板内没有可聚焦元素,则焦点锁定在面板本身
  3. focusin 守卫:监听全局 focusin,一旦焦点落到面板之外(比如被脚本抢走),立即用 preventScroll 拉回面板,避免页面滚到用户看不见的地方

关闭时,焦点会精确还给打开它的那个元素(modal.tsx 中记录了 previous),而不是丢给 document.body 让用户从头重新 Tab。

更狠的一招是 inert:打开时,遮罩的所有兄弟节点都会被加上 inert 属性(modal.tsx),关闭时逐一恢复原值。这意味着背景页面不仅点不到,键盘也进不去,读屏软件也不会去朗读它——屏幕阅读器只读弹窗本身。

Drawer:同样的循环,加上手势放弃面

components/interior/drawer.tsx 的 useDrawer 复用了同一套 Tab 循环逻辑,并且把非弹窗面板标记为 inert。它还有一个 Modal 没有的特性:从边缘拖出去关闭。拖动超过面板宽度的 38% 或者甩出速度超过 520px/s 就关闭(drawer.tsx),否则弹簧把面板拉回原位。

Drawer 的另一个细节值得抄:关闭时面板不卸载,只是平移走。滚动位置和表单状态都保留着,重新打开还是原样(drawer.tsx)。很多侧边栏组件一关就 unmount,用户重开后列表回到顶部、表单被清空——这就是那种"没人提 bug 但每次都在流失信任"的细节。

Command Palette:不换焦点,而是让焦点"不需要移动"

Command Palette(components/interior/command-palette.tsx)选择了另一种无障碍模型:输入框始终持有焦点,用 ARIA combobox 模式(role="combobox" + aria-activedescendant,command-palette.tsx)告诉读屏软件当前高亮的是哪一行。上下方向键、Home、End、Enter 是完整的键盘实现,不需要焦点在列表里跳转。

两个防抖细节:

  • 选中锚定在命令 id 上,不是行号。输入导致列表重排时,不可能"另一条命令滑到高亮底下"再被 Enter 误触发
  • 鼠标划过高亮行会先比对坐标(command-palette.tsx),列表在静止鼠标下面重排时不会偷走高亮

滚动锁定:参考计数 + 滚动条补偿

页面锁定滚动的经典实现是 body { overflow: hidden },但它有两个毛病:滚动条消失导致背景布局横向跳动;嵌套多个浮层时,内层一关整个页面就解锁了。

Modal 的参考计数锁

components/interior/modal.tsx 用一个模块级计数器 locks 做参考计数:

lockDocumentScroll():  locks += 1,只有第一个锁会真正设置 overflow
unlockDocumentScroll(): locks -= 1,只有归零时才恢复

所以从 Modal 里再开一个 Modal,内层关闭时外层依然锁着滚动。同时,锁定前会测量滚动条宽度(window.innerWidth - documentElement.clientWidth)并把它加到 body 的 paddingRight 上——背景页面在弹窗打开/关闭的瞬间纹丝不动。

Drawer 与 Command Palette 的锁

Drawer(drawer.tsx)和 Command Palette 的浮层(command-palette.tsx)用的是同款"锁 + 补 padding"手法,只是作用在 documentElement 上。Drawer 还提供 container="parent" 选项:把面板收进最近的定位祖先、跳过页面锁——适合嵌在卡片里的局部抽屉。

另外三者都通过 createPortal 挂到 document.body,避免被带 transform 或 overflow: hidden 的祖先裁剪掉 fixed 定位。

Escape 栈:谁该响应 Esc

Modal 在 modal.tsx 里维护了一个全局 stack:每个打开的 Modal 入栈一个 token,Escape 只响应栈顶,并且 stopPropagation。从 A 弹窗里打开 B 弹窗,按 Esc 只关 B——这是嵌套浮层体验的底线。

Command Palette 在 document 捕获阶段监听 Escape(command-palette.tsx),保证即使焦点在别处也能关掉;Drawer 则在自己的 onKeyDown 里拦截。三者都做了 preventDefault,防止 Esc 事件穿透去关掉底层的另一个浮层。

碰撞翻转:Popover 与 Context Menu 的贴边求生

Modal 和 Command Palette 居中于视口,天然不存在翻转问题;真正需要"碰撞检测"的是 Popover 和 Context Menu 这类锚定在触发元素旁的浮层。

Popover:先测量,再决定开哪边

components/interior/popover.tsx 的 usePopover 是完整的碰撞求解器:

  1. 测量四边空间:room = { top, bottom, left, right } 各边实际剩余空间
  2. 翻转规则(popover.tsx):请求的方向放不下、且对面空间更大时,翻到对面(FLIP 表:top↔bottom、left↔right)
  3. 横向夹取:翻转后仍可能出界的,用 clamp 夹进碰撞边界(默认视口,也可传 boundary 收窄到滚动容器)
  4. 箭头追触发器:面板被夹回去之后,箭头位置重新对着触发元素中心求解,transform-origin 也写到箭头位置——面板永远从它自己的触发器里"长出来",而不是从中心弹出
  5. 高度自适应:可用空间直接作为内容的 maxHeight,超出就在面板内部滚动,绝不会向无限高度动画

interior Overlay 组件文档演示:Popover 贴边时自动碰撞翻转的示意

Context Menu:在指针旁边生长

components/interior/context-menu.tsx 的翻转更简洁:

left = x + 面板宽 + 边距 <= 视口宽 ? x : x - 面板宽   // 放得下就贴右,放不下翻左边
top  = y + 面板高 + 边距 <= 视口高 ? y : y - 面板高   // 垂直同理

再夹取一个 8px 安全边距,菜单项永远不会掉进滚动条底下。transformOrigin 被写成点击点在面板内的像素偏移,菜单从指针精确位置放大,而不是"从没人点过的角落飞进来"。

速查:三个组件的行为对照

能力 Modal Drawer Command Palette Popover / Context Menu
焦点管理 Tab 循环 + focusin 拉回 + 关闭还焦 同左 焦点固定输入框,aria-activedescendant 焦点进面板,Esc/失焦还回触发器
背景隔离 兄弟节点 inert + aria-modal 同左 Portal 遮罩 blur/外部点击关闭
滚动锁 参考计数 + 滚动条补偿 同左(parent 模式可跳过) 同左 不锁滚动(不打断阅读流)
贴边处理 居中,maxWidth/maxHeight 内部滚动 宽度夹取 calc(100% - 40px) 居中固定宽度 520px 四边测量 + 翻转 + clamp
Escape 栈顶优先 直接关闭 捕获阶段监听 还焦给触发器

怎么用起来

没有 npm 包——每个组件就是一个自包含文件,直接拷走即可:

git clone https://gitcode.com/gh_mirrors/inte/interior

然后:

  • 拷贝 components/interior/modal.tsx(或 drawer.tsx、command-palette.tsx、popover.tsx)到你项目里
  • 只用 headless hook:useModal / useDrawer / useCommandPalette / usePopover,自己画 UI
  • 或直接用带样式的示例组件 <Modal> / <Drawer> / <CommandPalette> / <Popover>

唯一运行时依赖是 motion 目录,例如 modal-demo.tsx、drawer-demo.tsx、command-palette-demo.tsx。

小结

interior 的 Overlay 组件把浮层最容易翻车的三件事都变成了"默认正确":

  • 焦点陷阱不只是 Tab 循环,还有 inert 隔离、失焦拉回、关闭后还焦
  • 滚动锁定用参考计数支持嵌套,用滚动条宽度补偿消除布局跳动
  • 碰撞翻转先测量后决策:Popover 翻边 + clamp + 箭头追踪,Context Menu 在指针旁生长并留出安全边距

这些正是"没人提 issue 但用户天天踩"的缺失 20%。拷走一个文件,你获得的不是弹窗,而是一套可以直接抄进自己项目的浮层工程范式。

登录后查看全文
interior