TypeScript-React 项目中的 Portals 使用指南

沈书苹Peter

于 2025-05-30 09:07:30 发布

阅读量351

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00443/article/details/148324932

TypeScript-React 项目中的 Portals 使用指南

react Cheatsheets for experienced React developers getting started with TypeScript 项目地址: https://gitcode.com/gh_mirrors/rea/react

什么是 React Portals

Portals 是 React 提供的一种特殊功能，允许开发者将子节点渲染到存在于父组件 DOM 层次结构之外的 DOM 节点中。这在创建模态框、弹出窗口、工具提示等需要脱离常规 DOM 流的组件时特别有用。

为什么需要 Portals

在 React 应用中，组件通常按照其父组件-子组件的关系渲染到 DOM 中。然而，某些情况下我们需要将子组件渲染到 DOM 树的其他位置，例如：

模态对话框需要显示在其他内容之上
工具提示需要避免被父组件的 overflow:hidden 截断
全局通知需要独立于组件层级

Portals 完美解决了这些问题，同时保持了 React 的事件冒泡机制。

基础实现：类组件方式

在 TypeScript-React 项目中，我们可以这样实现一个 Portal 组件：

const modalRoot = document.getElementById("modal-root") as HTMLElement;
// 确保你的 HTML 文件中有一个 id 为 'modal-root' 的 div

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);
  }
}

代码解析

首先我们获取目标 DOM 节点（modal-root）
在类组件中创建一个新的 div 元素作为 Portal 的容器
在组件挂载时将容器添加到 modal-root
在组件卸载时移除容器
使用 ReactDOM.createPortal 将子组件渲染到容器中

现代实现：函数组件与 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) {
  // 使用 useRef 保持容器元素的引用
  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 来保持对容器元素的引用
在组件首次渲染时创建容器元素
使用 useEffect 处理挂载和卸载逻辑
返回通过 createPortal 创建的 Portal

使用示例

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

import { useState } from "react";

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

  return (
    <div>
      {/* 这个 div 也可以放在你的静态 HTML 文件中 */}
      <div id="modal-root"></div>
      {showModal && (
        <Modal>
          <div
            style={{
              display: "grid",
              placeItems: "center",
              height: "100vh",
              width: "100vw",
              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>
  );
}