TypeScript-React 项目实战：深入理解 React Portals 机制

廉林俏Industrious

于 2025-05-30 09:08:04 发布

阅读量216

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00502/article/details/148325107

TypeScript-React 项目实战：深入理解 React Portals 机制

react 项目地址: https://gitcode.com/gh_mirrors/reactt/react-typescript-cheatsheet

什么是 React Portals

React Portals 是 React 提供的一种特殊机制，允许开发者将子节点渲染到存在于父组件 DOM 层次结构之外的 DOM 节点中。这在处理模态框（Modal）、工具提示（Tooltip）或通知等需要"跳出"当前组件层级的情况下特别有用。

为什么需要 Portals

在 React 应用中，组件的渲染通常遵循父子组件的 DOM 结构。但有时我们需要将某些 UI 元素渲染到 DOM 树的其他位置，同时保持它们在 React 组件树中的逻辑位置。Portals 完美解决了这个问题，它提供了：

视觉上的"跳出"能力
保持事件冒泡机制
维持 React 组件树的上下文关系

基础实现：类组件方式

让我们先看一个使用类组件实现的 Portal 示例：

const modalRoot = document.getElementById("modal-root") as HTMLElement;

export class Modal extends React.Component<{ children?: React.ReactNode }> {
  el: HTMLElement = document.createElement("div");

  componentDidMount() {
    modalRoot.appendChild(this.el);
  }

  componentWillUnmount() {
    modalRoot.removeChild(this.el);
  }

  render() {
    return ReactDOM.createPortal(this.props.children, this.el);
  }
}

代码解析

modalRoot：这是我们在 HTML 中预先定义的一个容器元素，通常放在 <body> 的末尾
el：Modal 组件内部创建的 div 元素，将作为 Portal 的挂载点
生命周期方法：在组件挂载/卸载时管理 DOM 元素的添加/移除
createPortal：React 提供的 API，将 children 渲染到指定的 DOM 节点

现代实现：函数组件与 Hooks

随着 React Hooks 的普及，我们可以用更简洁的方式实现相同的功能：

import { useEffect, useRef, ReactNode } from "react";
import { createPortal } from "react-dom";

const modalRoot = document.querySelector("#modal-root") as HTMLElement;

type ModalProps = {
  children: ReactNode;
};

function Modal({ children }: ModalProps) {
  const elRef = useRef<HTMLDivElement | null>(null);
  if (!elRef.current) elRef.current = document.createElement("div");

  useEffect(() => {
    const el = elRef.current!;
    modalRoot.appendChild(el);
    return () => {
      modalRoot.removeChild(el);
    };
  }, []);

  return createPortal(children, elRef.current);
}

代码改进点

useRef：替代类组件中的实例属性，确保 DOM 元素只创建一次
useEffect：处理副作用逻辑，返回的清理函数相当于 componentWillUnmount
类型定义：明确 ModalProps 的类型，提高代码可维护性
非空断言：使用 ! 操作符告诉 TypeScript 我们知道 elRef.current 不会为 null

实际应用示例

下面是一个完整的 Modal 组件使用示例：

import { useState } from "react";

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

  return (
    <div>
      <div id="modal-root"></div>
      {showModal && (
        <Modal>
          <div
            style={{
              display: "grid",
              placeItems: "center",
              height: "100vh",
              width: "100vh",
              background: "rgba(0,0,0,0.1)",
              zIndex: 99,
            }}
          >
            I'm a modal!{" "}
            <button
              style={{ background: "papyawhip" }}
              onClick={() => setShowModal(false)}
            >
              close
            </button>
          </div>
        </Modal>
      )}
      <button onClick={() => setShowModal(true)}>show Modal</button>
    </div>
  );
}