Frontend Academy · 课时

用于模态框和工具提示的 Portal

使用 ReactDOM.createPortal 将子元素渲染到不同的 DOM 节点中，从而让模态框和工具提示脱离 overflow:hidden 容器的限制。

用于模态框和工具提示的 Portal 是 CoddyKit 上的免费 Frontend Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。

容器逃逸问题

模态框和工具提示需要在 DOM 顶层渲染，以避开父元素的 overflow:hidden、z-index 堆叠以及由 transform 创建的上下文。解决方案是使用门户。

createPortal API

createPortal(children, container) 会将 children 渲染到 container（任意 DOM 节点）中，同时让它们在逻辑上仍是 React 组件的子元素，以保留事件和上下文。

import { createPortal } from 'react-dom';

function Modal({ children, onClose }) {
  return createPortal(
    <div className="modal-backdrop" onClick={onClose}>
      <div className="modal-content" onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>,
    document.body
  );
}

门户容器

常见目标包括：document.body、index.html 中专用的 #modal-root 元素，或按需创建并通过 ref 引用的容器。

<!-- index.html -->
<div id="root"></div>
<div id="modal-root"></div>

// component:
const modalRoot = document.getElementById('modal-root');
return createPortal(<div>...</div>, modalRoot);

为什么不直接内联渲染

如果父元素设置了 overflow: hidden，子模态框就会被裁剪。如果父元素设置了 transform: scale，模态框的固定定位就会相对于父元素。门户可以避免所有这些问题。

事件仍会冒泡

尽管内容被渲染到了 DOM 的其他位置，React 事件仍会沿组件树而不是 DOM 树冒泡。门户中的点击仍会冒泡到祖先 React 组件上的 onClick 处理函数。

通过点击遮罩层关闭

请在模态框内容上阻止事件传播，这样点击内部区域就不会关闭模态框。

function Modal({ onClose, children }) {
  return createPortal(
    <div className="backdrop" onClick={onClose}>
      <div className="content" onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>,
    document.body
  );
}

通过 Escape 键关闭

在模态框打开期间添加键盘按下监听器，并在卸载时移除它。

useEffect(() => {
  const onKey = (e) => { if (e.key === 'Escape') onClose(); };
  window.addEventListener('keydown', onKey);
  return () => window.removeEventListener('keydown', onKey);
}, [onClose]);

门户中的焦点管理

模态框打开时：将焦点移入其中，在关闭前锁定焦点，然后将焦点恢复到打开模态框的元素。请使用 focus-trap-react 之类的库，避免自行重新实现这些逻辑。

原生对话框元素

HTML 的 <dialog> 原生处理模态框定位、背景遮罩、焦点锁定和通过 Escape 关闭。对于大多数模态框，它比门户更适合作为起点。

function Modal({ open, onClose, children }) {
  const ref = useRef(null);
  useEffect(() => {
    if (open) ref.current?.showModal();
    else ref.current?.close();
  }, [open]);
  return (
    <dialog ref={ref} onClose={onClose}>
      {children}
    </dialog>
  );
}

工具提示与弹出层

工具提示会相对于锚点元素定位。门户可以让它们脱离堆叠上下文。将其与 floating-ui 结合，可实现碰撞检测、翻转和定位。

import { useFloating, autoUpdate } from '@floating-ui/react';

function Tooltip({ children, content }) {
  const { refs, floatingStyles } = useFloating({ whileElementsMounted: autoUpdate });
  const [open, setOpen] = useState(false);
  return (
    <>
      <button ref={refs.setReference} onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>
        {children}
      </button>
      {open && createPortal(
        <div ref={refs.setFloating} style={floatingStyles}>{content}</div>,
        document.body
      )}
    </>
  );
}

SSR 注意事项

服务器上不存在 document。您可以只在客户端渲染（检查 typeof window），或者使用 Next.js 的 dynamic 并设置 ssr:false。

无障碍：aria-modal

模态框容器应具有 role="dialog"、aria-modal="true" 和指向模态框标题的 aria-labelledby。或者使用原生 <dialog>。

快速检查

为什么模态框应使用 createPortal，而不是在组件树中内联渲染？

回顾：门户

createPortal(children, container) 会在其他位置渲染 DOM，同时保持 React 树中的逻辑关系。它可以解决 overflow、transform 和 z-index 的逃逸问题。事件仍会沿 React 树冒泡。请添加 Escape 关闭功能并管理焦点。原生 <dialog> 可以为模态框处理其中许多事项。工具提示可与 floating-ui 结合。不要忘记 SSR（检查 typeof window）。

常见问题解答

「用于模态框和工具提示的 Portal」课时是免费的吗？

是的 — 「用于模态框和工具提示的 Portal」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。

「用于模态框和工具提示的 Portal」这节课中我会学到什么？

使用 ReactDOM.createPortal 将子元素渲染到不同的 DOM 节点中，从而让模态框和工具提示脱离 overflow:hidden 容器的限制。你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Frontend Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「用于模态框和工具提示的 Portal」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Frontend Academy 课中编写并运行代码吗？

能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Frontend Academy