interior 的 Modal、Drawer 与 Command Palette 如何处理焦点陷阱、滚动锁定与碰撞翻转:完整指南
interior 的 Modal、Drawer 与 Command Palette 如何处理焦点陷阱、滚动锁定与碰撞翻转:完整指南
interior 是一个面向 React 的开源微交互组件库(micro-interactions for react),专为"点击后那半秒钟"而设计。本文带你读懂它 Overlay 类组件——Modal、Drawer、Command Palette 与 Popover——是如何把焦点陷阱(focus trap)、滚动锁定(scroll lock)和碰撞翻转(collision flip)这三个最容易写崩的细节做对的,帮你避开自己手写浮层时最常见的坑。
为什么浮层组件最容易"翻车"
每个 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 实现了完整的焦点管理,分三层:
- 打开即聚焦:优先聚焦
initialFocusRef指定的元素(危险操作弹窗里应指向"取消"按钮),否则聚焦面板内第一个可聚焦元素 - Tab 循环:在最后一个元素按 Tab 跳回第一个,
Shift+Tab反向循环;若面板内没有可聚焦元素,则焦点锁定在面板本身 - 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 是完整的碰撞求解器:
- 测量四边空间:
room = { top, bottom, left, right }各边实际剩余空间 - 翻转规则(popover.tsx):请求的方向放不下、且对面空间更大时,翻到对面(
FLIP表:top↔bottom、left↔right) - 横向夹取:翻转后仍可能出界的,用
clamp夹进碰撞边界(默认视口,也可传boundary收窄到滚动容器) - 箭头追触发器:面板被夹回去之后,箭头位置重新对着触发元素中心求解,
transform-origin也写到箭头位置——面板永远从它自己的触发器里"长出来",而不是从中心弹出 - 高度自适应:可用空间直接作为内容的
maxHeight,超出就在面板内部滚动,绝不会向无限高度动画
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%。拷走一个文件,你获得的不是弹窗,而是一套可以直接抄进自己项目的浮层工程范式。

