React中如何使用Portal渲染到组件外部

React 中如何使用 Portal 渲染到组件外部

一句话总结：createPortal 让组件渲染到父组件 DOM 层级之外的任意位置——弹窗、Tooltip、全局通知从此摆脱 overflow 裁剪和 z-index 层级地狱。

目录

• Portal 是什么
• 5 个高频使用场景
• 万能兜底方案
• 预防 Checklist
• 一句话总结

Portal 是什么

正常情况下，React 组件渲染的 DOM 会嵌套在父组件的 DOM 里。但有些场景（弹窗、下拉菜单）需要渲染到 body 下，否则会被父级的 overflow: hidden 裁剪或陷入 z-index 层级问题。

createPortal(children, container) 把 JSX 渲染到指定的 DOM 节点，但组件树中它仍然是你的子组件——context、事件冒泡都照常工作。

import { createPortal } from 'react-dom';

function Modal({ children }) {
return createPortal(
<div className="modal">{children}</div>,
document.body // 渲染目标：body 节点
);
}

关键特性：

这意味着：

• ✅ Portal 内可以正常使用父组件的 Context
• ✅ 事件会沿着 React 组件树冒泡（不是 DOM 树）
• ✅ 摆脱父级 overflow / z-index 限制

5 个高频使用场景

场景一：弹窗被父容器 overflow: hidden 裁剪

Modal 放在有滚动的容器里，弹出层被截断。

❌ 错误写法：直接在组件里渲染 Modal

function Page() {
const [showModal, setShowModal] = useState(false);

return (
<div style={{ height: 300, overflow: 'hidden' }}> {/* 父容器有 overflow */}
<p>很长的内容…</p>

{showModal && (
<div className="modal-overlay">
<div className="modal-content">
<p>我是弹窗</p>
{/* ❌ 被 overflow: hidden 裁剪，只能看到一部分 */}
</div>
</div>
)}
</div>
);
}

✅ 正确写法：用 createPortal 渲染到 body

import { createPortal } from 'react-dom';

function Modal({ children, onClose }) {
return createPortal(
<div className="modal-overlay" onClick={onClose}>
<div className="modal-content" onClick={e => e.stopPropagation()}>
{children}
</div>
</div>,
document.body // ✅ 直接挂到 body，不受任何父级限制
);
}

function Page() {
const [showModal, setShowModal] = useState(false);

return (
<div style={{ height: 300, overflow: 'hidden' }}>
<p>很长的内容…</p>

{showModal && (
<Modal onClose={() => setShowModal(false)}>
<p>我是弹窗，完整显示！</p>
</Modal>
)}
</div>
);
}

场景二：Tooltip 被父级 transform 影响

父容器有 transform 属性时，position: fixed 的定位基准会变成这个父级，Tooltip 位置错乱。

❌ 错误写法：Tooltip 直接 fixed 定位

function Card() {
return (
<div style={{ transform: 'translateZ(0)' }}> {/* 优化属性，但破坏 fixed */}
<div className="card-content">
<button>删除</button>
<div className="tooltip" style={{ position: 'fixed', top: 100, left: 100 }}>
确定要删除吗？
{/* ❌ fixed 基准变成了父级 transform 容器，位置不对 */}
</div>
</div>
</div>
);
}

✅ 正确写法：Tooltip 用 Portal 渲染到 body

import { createPortal } from 'react-dom';

function Tooltip({ x, y, children }) {
return createPortal(
<div
className="tooltip"
style={{
position: 'fixed',
top: y,
left: x,
zIndex: 9999
}}
>
{children}
</div>,
document.body // ✅ body 下没有 transform 祖先，fixed 正常工作
);
}

function Card() {
const [pos, setPos] = useState(null);

return (
<div style={{ transform: 'translateZ(0)' }}>
<button
onMouseEnter={e => {
const rect = e.target.getBoundingClientRect();
setPos({ x: rect.left, y: rect.bottom + 8 });
}}
onMouseLeave={() => setPos(null)}
>
删除
</button>

{pos && (
<Tooltip x={pos.x} y={pos.y}>
确定要删除吗？
</Tooltip>
)}
</div>
);
}

场景三：Portal 里的 Context 依然来自父组件

Portal 改变了 DOM 位置，但 React 组件树不变——Context 照常传递。

❌ 误解：以为 Portal 内拿不到 Context 就层层传 props

// ThemeContext 在 App 提供
function App() {
return (
<ThemeContext.Provider value="dark">
<Page />
</ThemeContext.Provider>
);
}

function Modal({ theme }) {
// ❌ 不需要通过 props 传 theme！
return createPortal(
<div className={`modal ${theme}`}>…</div>,
document.body
);
}

✅ 正确理解：Portal 内直接 useContext

import { useContext } from 'react';
import { createPortal } from 'react-dom';

function Modal() {
// ✅ DOM 在 body 下，但组件树还在 App 内，Context 正常工作
const theme = useContext(ThemeContext);

return createPortal(
<div className={`modal theme-${theme}`}>…</div>,
document.body
);
}

场景四：Portal 中的事件冒泡遵循 React 树

在 Portal 内点击，事件会冒泡到 React 父组件——这是特性不是 bug。

❌ 翻车写法：不知道事件会冒泡，导致意外触发

function ListItem() {
const handleClick = () => {
console.log('列表项被点击');
closeMenu();
};

return (
<div onClick={handleClick}>
<span>列表项</span>

{createPortal(
<button>Portal 内的按钮</button>,
document.body
)}
{/* 点击 Portal 内按钮 → handleClick 被触发！ */}
{/* ❌ 用户只是想点按钮，结果整个列表项的点击逻辑也执行了 */}
</div>
);
}

✅ 正确写法：理解冒泡特性并阻止

function ListItem() {
const handleClick = () => {
closeMenu();
};

return (
<div onClick={handleClick}>
<span>列表项</span>

{createPortal(
<button onClick={e => e.stopPropagation()}> {/* ✅ 阻止冒泡 */}
Portal 内的按钮
</button>,
document.body
)}
</div>
);
}

场景五：SSR 环境 document 未定义报错

createPortal 的第二个参数是 DOM 节点，服务端渲染时 document 不存在，直接用会报错。

❌ 错误写法：模块加载时就访问 document

import { createPortal } from 'react-dom';

// ❌ SSR 报错：document is not defined
function Modal({ children }) {
return createPortal(
<div className="modal">{children}</div>,
document.body // 服务端渲染时崩溃
);
}

✅ 正确写法：客户端渲染后再挂 Portal

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

function Modal({ children }) {
const [mounted, setMounted] = useState(false);

useEffect(() => {
setMounted(true); // ✅ 只在客户端执行
}, []);

if (!mounted) return null; // SSR 时返回 null

return createPortal(
<div className="modal">{children}</div>,
document.body
);
}

万能兜底方案

通用 Modal 组件模板——一个文件解决所有弹窗需求：

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

function useModal() {
const [isOpen, setIsOpen] = useState(false);

const open = useCallback(() => setIsOpen(true), []);
const close = useCallback(() => setIsOpen(false), []);

return { isOpen, open, close };
}

function Modal({ isOpen, onClose, title, children, footer }) {
// ESC 关闭
useEffect(() => {
if (!isOpen) return;

const handleEsc = (e) => {
if (e.key === 'Escape') onClose();
};
document.addEventListener('keydown', handleEsc);

// 锁定背景滚动
document.body.style.overflow = 'hidden';

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

if (!isOpen) return null;

return createPortal(
<div
className="modal-overlay"
onClick={onClose}
style={{
position: 'fixed',
inset: 0,
background: 'rgba(0,0,0,0.5)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
zIndex: 1000
}}
>
<div
className="modal-content"
onClick={e => e.stopPropagation()}
style={{
background: '#fff',
borderRadius: 8,
padding: 24,
minWidth: 400,
maxHeight: '80vh',
overflow: 'auto'
}}
>
{title && <h3>{title}</h3>}
<div>{children}</div>
{footer && <div className="modal-footer">{footer}</div>}
</div>
</div>,
document.body
);
}

// 使用
function App() {
const { isOpen, open, close } = useModal();

return (
<div style={{ height: 300, overflow: 'hidden' }}>
<button onClick={open}>打开弹窗</button>

<Modal isOpen={isOpen} onClose={close} title="确认操作">
<p>确定要执行这个操作吗？</p>
</Modal>
</div>
);
}

快速参考表：

预防 Checklist

一句话总结

createPortal = “DOM 搬家，组件树不动”——弹窗、Tooltip、全局通知渲染到 body 摆脱裁剪和层级地狱，Context 和事件冒泡照常工作。记住 SSR 要做兼容，事件冒泡要主动管理。

最后问候亲爱的朋友们，并邀请你们阅读我的全新著作

📚 《React进阶实战指南》