1. 现象与症状 (Symptoms)

在桌面端三栏网格布局（CSS Grid: 左侧栏 Rail、中央工作区 Stage、右侧栏 Rail）改造移动端响应式（小于 1024px 视口，如 375px ~ 420px 手机端）过程中：

  • 需求是将左右侧栏改为移动端浮层抽屉 (Drawer / Sheet)，展开时显示半透明遮罩 (Backdrop)，点击遮罩空白区域自动收回抽屉；
  • 在 HTML 结构中直接于网格容器 .shell 内部首位插入遮罩元素 <div class="rail-backdrop" id="rail-backdrop"></div>；

  • 异常表现：

    1. 页面中央工作区 .stage 在移动端计算宽度异常变为 0px 或被强行挤压出屏幕可视区域；
    2. 桌面端与移动端切换时，网格轨道错位，主界面内容无法响应触控或点击；
    3. 在 Playwright 自动化测试中抛出异常：element is outside of the viewport 或 <div class="rail-backdrop"> intercepts pointer events。

2. 根因剖析 (Root Cause)

2.1 CSS 网格项隐式流定位 (Grid Item Auto-Placement)

当父容器声明为 display: grid; grid-template-columns: 0 1fr 0; 时：

  • 网格容器内部的直接子元素（无论是否使用 position: fixed 或绝对定位）在常规流计算中仍会按 DOM 顺序参与网格单元格的分配；
  • 将 #rail-backdrop 作为第一个子节点插入 .shell 后，遮罩元素占据了第 1 列（宽度 0px），而原本应分配在第 1 列的 .rail.left、原本应在第 2 列自适应 1fr 的 .stage 被依次顺移到了第 3 列（宽度 0px），导致中央舞台的主体完全无法正常撑开。

2.2 层叠上下文与固定定位污染 (Stacking Context & Fixed Contamination)

  • 将全局模态遮罩（覆盖 100vw * 100vh）放入包含 transform、perspective 或局部排版上下文的网格容器内部，会受到父容器的裁剪或坐标系约束，破坏全屏遮罩的语义；
  • 遮罩处于活动状态时，若事件捕获规则或层级未与主工作区解耦，会导致遮罩即使设置了 opacity: 0 仍截断底层按钮的鼠标/触控指针事件 (pointer-events)。

3. 解决机制与实现规范 (Resolution & Implementation)

3.1 遮罩元素提升为容器兄弟节点 (DOM Sibling Hoisting)

将全屏抽屉遮罩从网格布局容器内部剥离，提升为与网格容器 .shell 平级的兄弟节点，彻底隔离网格流计算：

<div class="shell" data-left-open="false" data-right-open="false">
  <aside class="rail left" id="left-rail"></aside>
  <main class="stage" id="stage-host"></main>
  <aside class="rail right" id="right-rail"></aside>
</div>
<!-- 遮罩与 shell 同级，避免占据 grid 轨道 -->
<div class="rail-backdrop" id="rail-backdrop" data-open="false"></div>

3.2 移动端断点解绑 Grid，退化为 Block 容器

在 @media (max-width: 1024px) 断点下，当抽屉采用 position: fixed 绝对脱标浮层呈现时，.shell 无需维持三栏 CSS Grid，将其退化为纯块级流：

@media (max-width: 1024px) {
  .shell,
  .shell[data-left-open="true"],
  .shell[data-right-open="true"] {
    display: block !important;
    width: 100% !important;
    height: 100% !important;
    position: relative !important;
    overflow: hidden !important;
  }

  .stage {
    width: 100% !important;
    height: 100% !important;
    min-width: 0 !important;
  }
}

3.3 遮罩状态与指针事件解耦 (Pointer Events Toggle)

遮罩只在激活时拦截点击与触控，未激活状态下必须禁用指针事件：

.rail-backdrop {
  position: fixed;
  inset: 0;
  background: rgba(15, 23, 42, 0.45);
  backdrop-filter: blur(4px);
  -webkit-backdrop-filter: blur(4px);
  z-index: 90;
  opacity: 0;
  pointer-events: none; /* 未激活状态穿透 */
  transition: opacity 0.28s cubic-bezier(0.16, 1, 0.3, 1);
}

.rail-backdrop[data-open="true"] {
  opacity: 1;
  pointer-events: auto; /* 激活状态拦截，点击空白收起抽屉 */
}

3.4 互斥抽屉与空白点击收回逻辑 (Mutual Exclusion & Dismiss)

function updateShellState() {
  shellEl.setAttribute('data-left-open', String(isLeftOpen));
  shellEl.setAttribute('data-right-open', String(isRightOpen));
  if (backdropEl) {
    const isMobile = window.innerWidth <= 1024;
    backdropEl.setAttribute('data-open', String((isLeftOpen || isRightOpen) && isMobile));
  }
}

// 点击空白遮罩处，统一收起左右抽屉
backdropEl.addEventListener('click', () => {
  closeAllRails();
});

4. 自动化验证：Playwright 多设备视口测试 (Playwright Verification)

使用 Playwright 对手机窄屏到宽屏区间（375px ~ 420px）进行系统性响应式断言，包含：

  1. 顶栏高度固定、无水平溢出；
  2. 按钮与分段控制器可见且位置不越界；
  3. 点击展开侧栏抽屉，验证遮罩 opacity 为 1 且覆盖视口；
  4. 模拟点击空白遮罩处，断言抽屉属性 data-*-open 恢复为 false 且遮罩恢复透明穿透。
// app/test-mobile-responsive.mjs 核心断言片断
const VIEWPORTS = [
  { name: 'iPhone-SE-375', width: 375, height: 667 },
  { name: 'iPhone-14-390', width: 390, height: 844 },
  { name: 'Pixel-7-412', width: 412, height: 915 },
  { name: 'Mobile-Max-420', width: 420, height: 915 },
];

for (const vp of VIEWPORTS) {
  await page.setViewportSize({ width: vp.width, height: vp.height });
  // 展开抽屉 -> 点击空白遮罩 (vp.width - 20, 333) -> 验证抽屉收起与遮罩 pointer-events 穿透
}

5. 经验与最佳实践 (Takeaways)

  1. 避免在网格容器内注入非轨道布局元素：全屏蒙层、Toast、全局 Modal 一律挂载于主应用网格容器外部或 body 根节点；
  2. 移动端响应式布局降级：多栏网格在移动端变为抽屉时，父级容器应由 display: grid 降级为 display: block，避免 0 宽度轨道带来的定位奇点；
  3. 严格的容器查询与单行文本截断：小屏下工作区顶栏采用 @container 查询与 white-space: nowrap; text-overflow: ellipsis;，确保按钮物理交互区域始终优先保留。

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Frontend