React createPortal：解决层叠上下文导致的 fixed 定位问题 • 月与羽

在前端开发中，开发者时常会遇到 position: fixed 元素未能如期相对于视口（Viewport）定位的挑战。一个典型场景是，当一个本应全屏显示的模态框（Modal）或侧边栏（Sidebar）组件被置于一个应用了特定 CSS 属性（如 transform）的父容器内时，其定位会意外地被限制在该父容器的范围内。此现象并非浏览器缺陷，而是由 CSS 的层叠上下文（Stacking Context）机制所致。本文旨在深入剖析该问题的成因，并阐述如何利用 React 的 createPortal API 作为标准解决方案。

一、问题根源：层叠上下文对 `position: fixed` 的影响

要准确理解此问题，必须掌握以下两个核心 CSS 概念：

**position: fixed** 的定位行为：该属性值旨在使元素的定位基准为浏览器视口。这意味着，无论页面滚动状态如何，该元素都将保持在屏幕的固定位置，这是实现全屏遮罩层（Overlay）和模态框的基础。
层叠上下文（Stacking Context）：层叠上下文是 CSS 中的一个三维概念模型，用于管理元素在 Z 轴上的堆叠顺序。页面的根元素（<html>）会创建一个根层叠上下文。然而，某些特定的 CSS 属性会强制元素生成一个新的层叠上下文。当一个元素形成新的层叠上下文后，它将成为其所有后代元素（包括 position: fixed 的后代）的包含块（Containing Block）。这直接导致了 fixed 元素的定位基准从视口转变为创建了层叠上下文的那个祖先元素。 触发新层叠上下文的常见 CSS 属性包括：

transform 属性值不为 none。
opacity 属性值小于 1。
filter 属性值不为 none。
其他属性如 perspective, clip-path, backdrop-filter 等。因此，当一个包含 position: fixed 模态框的组件（例如 MobileNavigation）被嵌套在一个应用了 transform 样式的父组件（例如 <header>) 中时，header 元素便创建了一个新的层叠上下文。其结果是，模态框的 fixed 定位不再相对于视口，而是被约束在 header 的边界之内，从而产生了布局被裁剪和限制的现象。

二、解决方案：`createPortal` 的机制与应用

createPortal 是 React DOM 提供的一个标准 API，其核心功能是允许开发者将一个组件的子节点渲染到父组件 DOM 层次结构之外的指定 DOM 节点中。从概念上讲，createPortal 在组件的逻辑树和物理 DOM 树之间建立了一座桥梁。虽然被传送的子节点在 DOM 结构上被移动到了一个新的位置（如 document.body），但在 React 组件树中，它依然是原始父组件的子嗣，维持着原有的数据流和事件传递关系。其 API 定义如下：

import { createPortal } from 'react-dom';
createPortal(child, container);

child: 任何可被 React 渲染的子节点，通常是一段 JSX。
container: 一个有效的 DOM 元素，child 将被挂载到此元素下。

三、实践：重构组件以规避层叠上下文限制

以下示例展示了如何应用 createPortal 来修复前述问题。

修改前的 DOM 结构（问题状态）

在浏览器开发者工具中，position: fixed 的元素被嵌套在创建了层叠上下文的 <header> 内部。

<body>
  <div id="__next">
    <header style="transform: translateX(0);">  <!-- `transform` 创建了新的层叠上下文 -->
      <nav>
        <button>Toggle Menu</button>
        <!-- `position: fixed` 元素被渲染于此，其定位受限于 <header> -->
        <div style="position: fixed; inset: 0;"></div>
      </nav>
    </header>
  </div>
</body>

修改后的实现（应用 `createPortal`）

通过引入 createPortal，我们将模态框的 JSX 结构传送至 document.body。

'use client';
import { useState } from 'react';
import { createPortal } from 'react-dom'; // 1. 导入 API
export default function MobileNavigation() {
  const [isMenuOpen, setIsMenuOpen] = useState(false);
  return (
    <>
      {/* 触发器按钮保留在原始位置 */}
      <button onClick={() => setIsMenuOpen(true)}>Menu</button>
      {/* 2. 条件性地渲染 Portal */}
      {isMenuOpen && createPortal(
        <>
          {/* 遮罩层与菜单面板的 JSX */}
          <div style={{ position: 'fixed', inset: 0, zIndex: 1000 }} />
          <div style={{ position: 'fixed', top: 0, left: 0, zIndex: 1001 }} >
            {/* Menu Content */}
          </div>
        </>,
        document.body // 3. 指定传送目标为 document.body
      )}
    </>
  );
}

修改后的 DOM 结构（问题解决）

经过重构，模态框相关的 DOM 节点被直接附加到 <body> 元素上，从而脱离了 <header> 的层叠上下文，使其 position: fixed 能够正确地相对于视口进行定位。

<body>
  <div id="__next">
    <header style="transform: translateX(0);">
      <nav>
        <button>Toggle Menu</button>
        <!-- 模态框的 DOM 节点已不在此处 -->
      </nav>
    </header>
  </div>
  <!-- 节点被传送至 body，现在可以实现预期的全屏覆盖 -->
  <div style="position: fixed; inset: 0; zIndex: 1000;"></div>
  <div style="position: fixed; top: 0; left: 0; zIndex: 1001;"></div>
</body>

四、`createPortal` 的核心优势

与手动操作 DOM（如 appendChild）相比，createPortal 提供了显著的优势，因为它无缝集成了 React 的声明式范式和事件系统。

维持组件逻辑树：尽管 DOM 位置发生改变，Portal 中的组件在 React 组件树中的位置保持不变。这意味着它可以正常地通过 props 和 context 从其逻辑父组件接收数据。
事件冒泡：Portal 内部触发的事件会沿着 React 组件树向上冒泡，直至其逻辑上的祖先组件。这确保了组件间的交互逻辑和状态管理能够按照预期工作，而这是原生 DOM 操作难以优雅实现的。