React的Portals怎么用？弹窗为什么必须挂到body？

一、弹窗为什么往往要挂到 body？三大 CSS 物理陷阱

初学 React 时，许多人习惯直接在需要弹窗的按钮旁边写一个 <div className="modal-backdrop">，并给它设置 position: fixed; inset: 0; z-index: 9999;。在最基础的简单页面里，这样写可能看似正常，但一旦页面结构复杂化，原地渲染的弹窗就会立即遭遇浏览器 CSS 渲染规范带来的三道物理枷锁：

1. overflow: hidden / overflow: auto 的物理裁剪

当弹窗声明在一个具有 overflow: hidden 或 overflow: auto 样式的卡片、列表项或侧边栏内部时，浏览器在绘制时会以该祖先容器的边界为界限，硬生生切掉所有超出尺寸的子元素。哪怕弹窗声明了 position: fixed，在许多嵌套或局部滚动的布局中，原本应该覆盖整屏的黑色半透明遮罩会被剪得只剩卡片大小，弹窗内容也被截断，无法正常交互。

2. CSS 变换（transform）劫持包含块（Containing Block）

这是前端布局中最隐蔽且极易踩坑的规则。很多开发者以为 position: fixed 永远是相对于浏览器视口（Viewport）进行定位的，但在 W3C CSS 规范中明确规定：如果任何祖先元素设置了非 none 的 transform、perspective 或 filter 属性，该祖先元素将替代视口，强制成为固定定位元素的包含块（Containing Block）。

现代前端界面广泛使用过渡动画或卡片微动效果（例如给列表项添加 transform: scale(0.98) 或平移过渡）。一旦宿主父元素拥有了哪怕 1 像素的变换，原本应当全屏固定的遮罩层（top: 0; left: 0; width: 100vw; height: 100vh;）就会立刻缩回到父元素的右上角或局部边框内，直接破坏全屏交互。

3. 层叠上下文（Stacking Context）的“拼爹”限制

CSS 的 z-index 并不是全页面唯一的扁平标尺，而是受限于层叠上下文。如果弹窗所在父容器创建了一个独立的层叠上下文，并且其自身的 z-index 仅为 1；而页面右侧有一个同级的固定悬浮栏，其 z-index 为 10。此时，即使你在弹窗上写下 z-index: 999999，弹窗也只能在这个 z-index: 1 的父级内部称霸，在全局依然会被侧边栏死死压在下方。

二、辨析：“弹窗必须挂到 body”是绝对真理吗？

社区中经常有一句口头禅：“弹窗必须挂载到 document.body”。这种说法看似斩钉截铁，但理解它需要分清合理之处与需要修正的边界。

合理之处在于：在常规 Web 页面中，document.body 位于 DOM 树的最外层，本身不具备局部的 transform、未受限制的 overflow 裁剪，是承载全屏覆盖遮罩最稳固、最干净的物理底座。直接挂载到 body 下能够以最小的沟通成本彻底规避上述三大样式陷阱。

需要修正的地方在于：“必须挂到 body”并不是唯一正确的选择，也不是绝对标准。在规范的现代前端工程中，直接无序地向 document.body 乱塞 div 反而是一种欠缺架构约束的做法。

• 推荐做法：独立挂载容器——在 HTML 骨架中预先在 <body> 下安排一个独立的同级容器，例如 <div id="modal-root"></div>。这能将弹层节点与应用主根节点 <div id="root"> 清晰隔开，避免弹窗散落在 body 的子元素末尾。
• 多层弹窗与堆叠管理——通过独立的弹窗容器，可以统一监听全局焦点捕获、配合屏幕阅读器管理 aria-hidden，以及统一处理多层弹窗排队时的层叠深度（Stacking Order）。
• 局部限定的弹层——如果业务需要的是在某个特定富文本编辑器、全屏画板或独立微应用沙箱内部的局部抽屉，挂载目标就应当是该沙箱的根节点，而不是外层宿主的 body。核心原则不是“必须是 body 标签”，而是“必须脱离产生样式限制的局部祖先，挂载到对应渲染范围最顶层的纯净容器”。

三、React Portals 的具体用法：标准 4 步实现

在 React 中，使用传送门非常简单。核心 API 是从 react-dom 导出的 createPortal：

createPortal(children, domNode, key?)

其中 children 是任意可渲染的 React 节点（如 JSX 元素、字符串等），domNode 是一个已经存在于当前页面中的真实 DOM 节点。下面我们按照工业级组件的标准，分 4 个步骤实现一个安全健壮的 Modal 组件。

步骤 1：准备挂载点 DOM 容器

最推荐的方式是在公共模板（如 public/index.html）中预留挂载节点；如果无法修改模板，也可以在组件代码中检测并动态生成容器：

// 在 public/index.html 中预先定义
<body>
  <div id="root"></div>
  <div id="modal-root"></div>
</body>

步骤 2：防范 SSR（服务端渲染）水合异常

在 Next.js、Remix 或任何同构 SSR 环境中，服务端执行代码时是不存在 document 或 window 对象的。如果直接在组件体内部访问 document.getElementById，会导致服务端直接抛出 ReferenceError: document is not defined。

正确的做法是引入一个 mounted 状态，在 useEffect 触发（即确认进入浏览器客户端运行环境）后再行渲染。未挂载前安全返回 null。

步骤 3：编写完整的 Modal 组件

下面是一份结构完整、带有遮罩点击关闭、ESC 按键监听与页面滚动锁定的生产级代码示例：

import React, { useEffect, useState } from 'react';
import { createPortal } from 'react-dom';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title?: string;
  children: React.ReactNode;
}

export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children }) => {
  const [mounted, setMounted] = useState(false);

  // 1. 确保仅在客户端环境执行
  useEffect(() => {
    setMounted(true);
    return () => setMounted(false);
  }, []);

  // 2. 处理按键监听与 body 滚动锁定
  useEffect(() => {
    if (!isOpen) return;

    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Escape') {
        onClose();
      }
    };

    // 锁定 body 滚动，防止弹窗打开时背景仍可滚动
    const originalOverflow = document.body.style.overflow;
    document.body.style.overflow = 'hidden';
    window.addEventListener('keydown', handleKeyDown);

    return () => {
      document.body.style.overflow = originalOverflow;
      window.removeEventListener('keydown', handleKeyDown);
    };
  }, [isOpen, onClose]);

  if (!mounted || !isOpen) return null;

  const modalRoot = document.getElementById('modal-root') || document.body;

  // 3. 调用 createPortal 传送渲染
  return createPortal(
    <div
      className="modal-backdrop"
      style={{
        position: 'fixed',
        inset: 0,
        backgroundColor: 'rgba(70, 75, 72, 0.45)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        zIndex: 1000,
      }}
      onClick={onClose}
    >
      <div
        className="modal-dialog"
        style={{
          background: '#F7F4ED',
          border: '1px solid #D9D4C7',
          borderRadius: 8,
          padding: 24,
          minWidth: 360,
          maxWidth: 520,
          boxShadow: '0 8px 24px rgba(0, 0, 0, 0.12)',
        }}
        role="dialog"
        aria-modal="true"
        onClick={(e) => e.stopPropagation()} // 关键：防止点击弹框内部触发遮罩的关闭
      >
        {title && <h3 style={{ marginTop: 0, color: '#464B48' }}>{title}</h3>}
        <div className="modal-body">{children}</div>
      </div>
    </div>,
    modalRoot
  );
};

四、容易忽略的关键机制：DOM 分离，但 React 事件冒泡仍然保留！

这是使用 React Portals 时最常见但也最反直觉的一点。许多工程师会想当然地认为：既然弹窗的 DOM 已经挂载到了 document.body，那么在弹窗里点击按钮，事件只会沿着 dialog → modal-root → body 进行冒泡，肯定不会影响到原先声明它的父组件。

这种理解是错误的。在 React 中，合成事件（SyntheticEvent）的派发并不依赖物理 DOM 树的父子关系，而是严格依照 React 虚拟组件树的层级结构向上传递。

设想这样一个典型业务场景：我们有一个点击可展开详情的列表卡片 <div className="card" onClick={handleCardClick}>。在卡片内部，我们嵌入了上述通过 Portal 渲染到 body 的 <Modal>。

当用户在屏幕中央的 Modal 弹窗里点击“确认”按钮时，浏览器底层的原生 DOM 事件确实只冒泡到了 body。但是，React 的事件委托系统接收到事件后，会沿着虚拟 DOM 树从 <button> 一路向上寻找父组件节点，从而直接触发卡片上的 handleCardClick 回调函数！

五、全景对比与技术选型总结

在实际项目架构中，并非所有浮层都需要使用 Portals。理解何时使用、何时保持普通就地渲染，是保证代码简洁度与健壮性的关键。

综合来看，两者的选择逻辑非常清晰：

1. 必须使用 Portals 的场景：全屏对话框（Modal）、侧边抽屉（Drawer）、全局顶部通知（Toast/Alert）、右键菜单（Context Menu）。这些元素的共同特征是视觉上需要突破局部容器，占据全局视口层级。
2. 保持常规原地渲染的场景：跟随文档流展开的折叠面板（Accordion）、局部表单校验提示条、纯卡片内部的动态增减小部件。这些组件在尺寸和定位上与父元素强绑定，原地渲染无论是状态调试还是样式管理都更为自然。
3. 介于两者之间的悬浮组件：例如下拉菜单（Dropdown）或气泡提示（Tooltip）。如果是简单的局部下拉，原地绝对定位搭配 z-index 即可；但如果该下拉菜单所在的表格或卡片设置了 overflow: hidden，则依然需要配合 Portals 挂载到 body，并借助 getBoundingClientRect() 计算坐标，以实现既不被裁剪又精确定位的效果。