编辑“︁Next.js Portal组件”︁

{{Note|本文适用于Next.js 13+版本，部分语法可能需要React 18+环境支持}}

= Next.js Portal组件 =

'''Portal组件'''是React提供的一项高级功能，允许开发者将子节点渲染到父组件DOM层次结构之外的DOM节点中。在Next.js中，这一特性常用于解决模态框(Modal)、通知(Toast)、工具提示(Tooltip)等需要突破容器层叠上下文限制的场景。

== 核心概念 ==

Portal的工作原理可以用以下公式表示：
<math>
\text{Portal}(children, container) \rightarrow \text{DOM渲染}
</math>
其中：
* <code>children</code> 是要渲染的React元素
* <code>container</code> 是目标DOM节点

=== 为什么需要Portal ===
传统React组件渲染存在以下限制：
* 子组件受父组件CSS属性影响（如overflow: hidden）
* z-index堆叠上下文问题
* 全屏元素可能被父容器裁剪

Portal通过将内容渲染到DOM树的任意位置解决这些问题，同时保持React组件树的上下文。

== 基本用法 ==

Next.js中使用Portal需要先创建目标容器，然后通过<code>createPortal</code>实现：

<syntaxhighlight lang="javascript">
// components/Modal.js
'use client'; // Next.js 13+客户端组件标记

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

export default function Modal({ children, isOpen }) {
  const portalRef = useRef(null);

  useEffect(() => {
    // 动态创建portal容器
    portalRef.current = document.createElement('div');
    portalRef.current.id = 'modal-portal';
    document.body.appendChild(portalRef.current);

    return () => {
      // 组件卸载时清理
      if (portalRef.current) {
        document.body.removeChild(portalRef.current);
      }
    };
  }, []);

  if (!isOpen || !portalRef.current) return null;

  return createPortal(
    <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center">
      <div className="bg-white p-6 rounded-lg max-w-md">
        {children}
      </div>
    </div>,
    portalRef.current
  );
}
</syntaxhighlight>

=== 使用示例 ===
<syntaxhighlight lang="javascript">
// app/page.js
import { useState } from 'react';
import Modal from '../components/Modal';

export default function Home() {
  const [showModal, setShowModal] = useState(false);

  return (
    <main>
      <button 
        onClick={() => setShowModal(true)}
        className="px-4 py-2 bg-blue-500 text-white rounded"
      >
        打开模态框
      </button>
      
      <Modal isOpen={showModal}>
        <h2>重要通知</h2>
        <p>这是通过Portal渲染的内容！</p>
        <button 
          onClick={() => setShowModal(false)}
          className="mt-4 px-3 py-1 bg-gray-200 rounded"
        >
          关闭
        </button>
      </Modal>
    </main>
  );
}
</syntaxhighlight>

== 高级应用 ==

=== 动态容器管理 ===
对于需要频繁创建/销毁Portal的场景，可以使用全局容器管理器：

<syntaxhighlight lang="javascript">
// lib/portal-manager.js
const portalContainers = new Map();

export function getPortalContainer(id) {
  if (!portalContainers.has(id)) {
    const container = document.createElement('div');
    container.id = `portal-${id}`;
    document.body.appendChild(container);
    portalContainers.set(id, container);
  }
  return portalContainers.get(id);
}
</syntaxhighlight>

=== SSR兼容方案 ===
Next.js服务端渲染时需特殊处理：

<syntaxhighlight lang="javascript">
// components/SafePortal.js
'use client';

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

export default function SafePortal({ children, id }) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;
  
  return createPortal(
    children,
    document.getElementById(id) || document.body
  );
}
</syntaxhighlight>

== 实际应用案例 ==

=== 案例1：全局通知系统 ===
<mermaid>
graph TD
  A[触发通知] --> B[通过Portal渲染]
  B --> C[body下的.notification-container]
  C --> D[自动消失动画]
</mermaid>

=== 案例2：工具提示(Tooltip) ===
解决父容器<code>overflow: hidden</code>导致工具提示被裁剪的问题。

== 性能优化 ==

* 复用Portal容器减少DOM操作
* 使用React.memo避免不必要的重新渲染
* 延迟加载Portal内容（如配合Intersection Observer）

<syntaxhighlight lang="javascript">
// 优化后的Portal组件
const MemoizedPortal = React.memo(({ children, id }) => {
  return createPortal(children, document.getElementById(id));
});
</syntaxhighlight>

== 常见问题 ==

=== Q1: Portal事件冒泡 ===
Portal中的事件会按照React组件树冒泡，而非DOM树。例如点击Portal内的按钮，仍会触发外层React组件的onClick。

=== Q2: 样式隔离 ===
Portal内容不受父组件样式作用域影响，但全局样式仍会应用。推荐使用CSS Modules或CSS-in-JS解决方案。

=== Q3: 与Next.js Layout的关系 ===
Portal可以突破Layout的DOM结构限制，但仍在同一React上下文。

== 最佳实践 ==

1. 为Portal容器添加明确的z-index管理
2. 实现无障碍访问（ARIA属性）
3. 提供关闭/销毁机制
4. 考虑移动端视口适应

{{Warning|避免过度使用Portal，仅在确实需要突破DOM层级限制时使用}}

== 扩展阅读 ==

* React官方Portal文档
* Next.js客户端组件规范
* Web无障碍倡议(WAI-ARIA)模态框实践

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js高级组件]]