React createPortal API 完整指南 - Refine 开发

一. createPortal API 简介

createPortal 是 React DOM 的一部分，允许开发者将 React 组件的子元素渲染到 DOM 中的其他位置。尽管 portal 的渲染位置不同，但其行为与普通 React 子组件一致。这一特性使得创建工具提示、通知框、模态框和弹窗等 UI 变得更加简单高效。

二. 什么是 createPortal API？

通常情况下，React 组件与其子组件存在父子关系，所有子组件渲染后都嵌套在父组件内。然而，通过 createPortal，React 组件可以将部分或全部子组件渲染到 DOM 中非父节点的位置。

1. createPortal 函数签名

ReactDOM.createPortal(children, domNode, [key])

a. 参数说明

• children：React 组件、JSX、React Fragment、字符串、数字或这些类型的数组
• domNode：目标 DOM 节点，可通过 document.getElementById 或其他 DOM 查询方式获取
• key（可选）：用于标识 portal 的唯一字符串或数字

createPortal 返回一个 React 节点，可以在组件返回 JSX 或嵌套在其他组件中使用。

三. createPortal 的核心特性

1. 渲染位置的灵活性

Portal 仅改变组件在 DOM 中的渲染位置，其行为与普通组件一致。例如，从 portal 触发的事件沿着 React 树冒泡，而非 DOM 树。

2. 父子关系的保留

Portal 虽然渲染在 DOM 的其他位置，但仍然是渲染它的父组件的子组件。父组件 props 或 context 改变时，portal 会重新渲染。

四. 使用 createPortal 的优势

1. 灵活的渲染位置

Portal 可以将元素渲染到父组件之外的 DOM 节点，适用于工具提示、模态框等 UI 组件。

2. 与非 React 库的集成

Portal 允许 React 组件在非 React 的第三方库中渲染，为集成提供便利。参考示例

五. 使用 createPortal 的最佳实践

1. 简化 Portal 组件

尽量保持 portal 内部组件简单，减少维护成本。示例模态框：

import ReactDOM from 'react-dom';
import React from 'react';

const Modal = ({ isOpen, children, onClose }) = > {
  if (!isOpen) return null;
  return ReactDOM.createPortal(
    < div className="modal" >
      {children}
      < button onClick={onClose} > 关闭 < /button >
    < /div > ,
    document.getElementById('modal-root')
  );
};

2. 集中状态管理

在父组件中管理影响 portal 的状态，避免在 portal 内部管理状态。

3. 样式传递

Portal 不会继承父组件的 CSS 样式，需要显式传递：

const style = { color: 'red' };
ReactDOM.createPortal( < p style={style} > Hello, Portal! < /p > , document.getElementById('modal-root'));

4. 无障碍访问

确保 portal 内容对屏幕阅读器友好，使用 ARIA 角色和属性增强可访问性。

六. createPortal 的局限性

1. 样式继承问题

Portal 不会继承父组件 CSS，可能导致样式问题，特别是在复杂布局中。

2. 复杂性增加

多个相互依赖的 portal 增加维护和调试难度，DOM 渲染位置与 React 组件层级不一致可能造成理解难度。

3. 事件冒泡路径

Portal 的事件沿 React 树冒泡，而非 DOM 树，可能导致调试困难。

七. createPortal 的常见用途

1. 模态框、工具提示和弹窗

const Modal = ({ isOpen, onClose }) = > {
  if (!isOpen) return null;
  return ReactDOM.createPortal(
    < div className="modal" >
      < p > 这是一个模态框 < /p >
      < button onClick={onClose} > 关闭 < /button >
    < /div > ,
    document.getElementById('modal-root')
  );
};

2. 与非 React 应用集成

Portal 支持将 React 组件渲染到 DOM 的任意位置，方便在静态页面或非 React 应用中使用。

八. 测试 Portals 的技巧

1. 验证渲染位置

expect(document.getElementById('modal-root').textContent).toBe('Hello, Portal!');

2. 测试交互行为

验证按钮点击是否触发正确逻辑，例如关闭模态框。

3. 可访问性测试

检查 ARIA 属性是否正确设置，确保屏幕阅读器可访问 portal 内容。

4. 资源清理

父组件卸载时，确保 portal 内容正确卸载，避免内存泄漏。

九. 总结

createPortal 是 React DOM 提供的强大工具，允许开发者将子组件渲染到 DOM 的其他位置。它在构建模态框、工具提示、弹窗和通知框等 UI 组件时非常实用。

使用时需注意样式继承、事件冒泡路径和复杂性等问题。通过遵循最佳实践和测试方法，可以充分发挥 createPortal 的优势，提供灵活高效的用户交互体验。

原文链接
Refine 官方博客