تسلط بر پورتال‌های ری‌اکت: رندر کامپوننت‌ها فراتر از سلسله‌مراتب DOM

در چشم‌انداز گسترده توسعه وب مدرن، ری‌اکت به توسعه‌دهندگان بی‌شماری در سراسر جهان این قدرت را داده است تا رابط‌های کاربری پویا و بسیار تعاملی بسازند. معماری مبتنی بر کامپوننت آن، ساختارهای پیچیده UI را ساده می‌کند و قابلیت استفاده مجدد و نگهداری را ارتقا می‌دهد. با این حال، حتی با طراحی زیبای ری‌اکت، توسعه‌دهندگان گاهی با سناریوهایی روبرو می‌شوند که رویکرد استاندارد رندر کامپوننت – جایی که کامپوننت‌ها خروجی خود را به عنوان فرزندان در عنصر DOM والد خود رندر می‌کنند – محدودیت‌های قابل توجهی را ایجاد می‌کند.

یک دیالوگ مودال را در نظر بگیرید که باید بالاتر از تمام محتوای دیگر ظاهر شود، یک بنر نوتیفیکیشن که به صورت سراسری شناور است، یا یک منوی زمینه که باید از مرزهای یک کانتینر والد با سرریز (overflow) فرار کند. در این شرایط، رویکرد متداول رندر کامپوننت‌ها مستقیماً در سلسله‌مراتب DOM والدشان می‌تواند به چالش‌هایی در استایل‌دهی (مانند تداخلات z-index)، مشکلات چیدمان و پیچیدگی‌های انتشار رویداد منجر شود. این دقیقاً جایی است که پورتال‌های ری‌اکت (React Portals) به عنوان یک ابزار قدرتمند و ضروری در زرادخانه یک توسعه‌دهنده ری‌اکت وارد عمل می‌شوند.

این راهنمای جامع به عمق الگوی پورتال ری‌اکت می‌پردازد و مفاهیم بنیادی، کاربردهای عملی، ملاحظات پیشرفته و بهترین شیوه‌های آن را بررسی می‌کند. چه یک توسعه‌دهنده باتجربه ری‌اکت باشید یا تازه سفر خود را آغاز کرده باشید، درک پورتال‌ها امکانات جدیدی را برای ساختن تجربیات کاربری واقعاً قوی و قابل دسترس در سطح جهانی برای شما باز خواهد کرد.

درک چالش اصلی: محدودیت‌های سلسله‌مراتب DOM

کامپوننت‌های ری‌اکت، به طور پیش‌فرض، خروجی خود را در گره DOM کامپوننت والد خود رندر می‌کنند. این یک نگاشت مستقیم بین درخت کامپوننت ری‌اکت و درخت DOM مرورگر ایجاد می‌کند. در حالی که این رابطه شهودی و به طور کلی مفید است، زمانی که نمایش بصری یک کامپوننت نیاز به رهایی از محدودیت‌های والد خود داشته باشد، می‌تواند به یک مانع تبدیل شود.

سناریوهای رایج و نقاط دردناک آن‌ها:

• مودال‌ها، دیالوگ‌ها و لایت‌باکس‌ها: این عناصر معمولاً باید روی کل اپلیکیشن قرار بگیرند، صرف نظر از اینکه در کجای درخت کامپوننت تعریف شده‌اند. اگر یک مودال در عمق زیادی تودرتو باشد، `z-index` CSS آن ممکن است توسط اجدادش محدود شود و اطمینان از اینکه همیشه در بالا ظاهر می‌شود را دشوار کند. علاوه بر این، `overflow: hidden` در یک عنصر والد می‌تواند بخش‌هایی از مودال را ببرد.
• تولتیپ‌ها و پاپ‌اورها: مانند مودال‌ها، تولتیپ‌ها یا پاپ‌اورها اغلب نیاز دارند که خود را نسبت به یک عنصر موقعیت‌دهی کنند اما خارج از مرزهای احتمالاً محدود والد آن ظاهر شوند. یک `overflow: hidden` روی یک والد می‌تواند یک تولتیپ را کوتاه کند.
• نوتیفیکیشن‌ها و پیام‌های Toast: این پیام‌های سراسری اغلب در بالا یا پایین ویوپورت ظاهر می‌شوند و نیاز دارند که مستقل از کامپوننتی که آن‌ها را فعال کرده است، رندر شوند.
• منوهای زمینه (Context Menus): منوهای کلیک-راست یا منوهای زمینه سفارشی باید دقیقاً در جایی که کاربر کلیک می‌کند ظاهر شوند و اغلب از کانتینرهای والد محدود خارج می‌شوند تا دید کامل داشته باشند.
• ادغام با کتابخانه‌های شخص ثالث: گاهی اوقات، ممکن است نیاز داشته باشید که یک کامپوننت ری‌اکت را در یک گره DOM که توسط یک کتابخانه خارجی یا کد قدیمی مدیریت می‌شود، خارج از ریشه ری‌اکت، رندر کنید.

در هر یک از این سناریوها، تلاش برای دستیابی به نتیجه بصری مطلوب با استفاده از رندر استاندارد ری‌اکت، اغلب منجر به CSS پیچیده، مقادیر بیش از حد `z-index` یا منطق موقعیت‌یابی پیچیده‌ای می‌شود که نگهداری و مقیاس‌پذیری آن دشوار است. اینجاست که پورتال‌های ری‌اکت یک راه‌حل تمیز و اصولی ارائه می‌دهند.

پورتال ری‌اکت دقیقاً چیست؟

یک پورتال ری‌اکت یک روش درجه یک برای رندر کردن فرزندان در یک گره DOM فراهم می‌کند که خارج از سلسله‌مراتب DOM کامپوننت والد وجود دارد. با وجود رندر شدن در یک عنصر DOM فیزیکی متفاوت، محتوای پورتال همچنان طوری رفتار می‌کند که گویی یک فرزند مستقیم در درخت کامپوننت ری‌اکت است. این بدان معناست که همان کانتکست ری‌اکت (مثلاً مقادیر Context API) را حفظ می‌کند و در سیستم حباب رویداد (event bubbling) ری‌اکت شرکت می‌کند.

هسته پورتال‌های ری‌اکت در متد `ReactDOM.createPortal()` نهفته است. امضای آن ساده است:

ReactDOM.createPortal(child, container)

• child: هر فرزند قابل رندر ری‌اکت، مانند یک عنصر، رشته یا فرگمنت.
• container: یک عنصر DOM که از قبل در سند وجود دارد. این گره DOM هدف است که `child` در آن رندر خواهد شد.

هنگامی که از `ReactDOM.createPortal()` استفاده می‌کنید، ری‌اکت یک زیردرخت DOM مجازی جدید تحت گره DOM `container` مشخص شده ایجاد می‌کند. با این حال، این زیردرخت جدید هنوز به طور منطقی به کامپوننتی که پورتال را ایجاد کرده است متصل است. این «اتصال منطقی» کلید درک این است که چرا حباب رویداد و کانتکست همانطور که انتظار می‌رود کار می‌کنند.

راه‌اندازی اولین پورتال ری‌اکت: یک مثال ساده از مودال

بیایید یک مورد استفاده رایج را بررسی کنیم: ایجاد یک دیالوگ مودال. برای پیاده‌سازی یک پورتال، ابتدا به یک عنصر DOM هدف در `index.html` خود (یا هر جایی که فایل HTML ریشه اپلیکیشن شما قرار دارد) نیاز دارید که محتوای پورتال در آن رندر شود.

مرحله ۱: آماده‌سازی گره DOM هدف

فایل `public/index.html` خود (یا معادل آن) را باز کرده و یک عنصر `div` جدید اضافه کنید. رسم بر این است که این عنصر درست قبل از تگ پایانی `body`، خارج از ریشه اصلی اپلیکیشن ری‌اکت شما اضافه شود.

<body>
  <!-- ریشه اصلی اپلیکیشن ری‌اکت شما -->
  <div id="root"></div>

  <!-- اینجا جایی است که محتوای پورتال ما رندر خواهد شد -->
  <div id="modal-root"></div>
</body>

مرحله ۲: ایجاد کامپوننت پورتال

حالا، بیایید یک کامپوننت مودال ساده بسازیم که از یک پورتال استفاده می‌کند.

// Modal.js
import React, { useEffect, useRef } from 'react';
import ReactDOM from 'react-dom';

const modalRoot = document.getElementById('modal-root');

const Modal = ({ children, isOpen, onClose }) => {
  const el = useRef(document.createElement('div'));

  useEffect(() => {
    // اضافه کردن div به ریشه مودال هنگام mount شدن کامپوننت
    modalRoot.appendChild(el.current);

    // پاک‌سازی: حذف div هنگام unmount شدن کامپوننت
    return () => {
      modalRoot.removeChild(el.current);
    };
  }, []); // آرایه وابستگی خالی به این معناست که این کد یک بار در mount و یک بار در unmount اجرا می‌شود

  if (!isOpen) {
    return null; // اگر مودال باز نیست، چیزی رندر نکن
  }

  return ReactDOM.createPortal(
    <div style={{
      position: 'fixed',
      top: 0,
      left: 0,
      right: 0,
      bottom: 0,
      backgroundColor: 'rgba(0, 0, 0, 0.5)',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      zIndex: 1000 // اطمینان از قرار گرفتن در بالا
    }}>
      <div style={{
        backgroundColor: 'white',
        padding: '20px',
        borderRadius: '8px',
        boxShadow: '0 4px 8px rgba(0, 0, 0, 0.2)',
        maxWidth: '500px',
        width: '90%'
      }}>
        {children}
        <button onClick={onClose} style={{ marginTop: '15px' }}>بستن مودال</button>
      </div>
    </div>,
    el.current // رندر محتوای مودال در div ایجاد شده ما، که داخل modalRoot است
  );
};

export default Modal;

در این مثال، ما برای هر نمونه مودال یک عنصر `div` جدید (`el.current`) ایجاد کرده و آن را به `modal-root` اضافه می‌کنیم. این به ما امکان می‌دهد در صورت نیاز چندین مودال را مدیریت کنیم بدون اینکه در چرخه حیات یا محتوای یکدیگر تداخل ایجاد کنند. محتوای واقعی مودال (پوشش و جعبه سفید) سپس با استفاده از `ReactDOM.createPortal` در این `el.current` رندر می‌شود.

مرحله ۳: استفاده از کامپوننت مودال

// App.js
import React, { useState } from 'react';
import Modal from './Modal'; // با فرض اینکه Modal.js در همان دایرکتوری است

function App() {
  const [isModalOpen, setIsModalOpen] = useState(false);

  const handleOpenModal = () => setIsModalOpen(true);
  const handleCloseModal = () => setIsModalOpen(false);

  return (
    <div style={{ padding: '20px' }}>
      <h1>مثال پورتال ری‌اکت</h1>
      <p>این محتوا بخشی از درخت اصلی اپلیکیشن است.</p>
      <button onClick={handleOpenModal}>باز کردن مودال سراسری</button>

      <Modal isOpen={isModalOpen} onClose={handleCloseModal}>
        <h3>درود از پورتال!</h3>
        <p>این محتوای مودال خارج از div با شناسه 'root' رندر شده است، اما همچنان توسط ری‌اکت مدیریت می‌شود.</p>
      </Modal>
    </div>
  );
}

export default App;

با وجود اینکه کامپوننت `Modal` در داخل کامپوننت `App` رندر می‌شود (که خود در داخل div با شناسه `root` قرار دارد)، خروجی DOM واقعی آن در داخل div با شناسه `modal-root` ظاهر می‌شود. این تضمین می‌کند که مودال بدون مشکلات `z-index` یا `overflow` روی همه چیز قرار می‌گیرد، در حالی که همچنان از مدیریت state و چرخه حیات کامپوننت ری‌اکت بهره‌مند است.

کاربردهای کلیدی و کاربردهای پیشرفته پورتال‌های ری‌اکت

در حالی که مودال‌ها یک مثال برجسته هستند، کاربرد پورتال‌های ری‌اکت بسیار فراتر از پاپ‌آپ‌های ساده است. بیایید سناریوهای پیشرفته‌تری را بررسی کنیم که در آن‌ها پورتال‌ها راه‌حل‌های زیبایی ارائه می‌دهند.

۱. سیستم‌های مودال و دیالوگ قوی

همانطور که دیدیم، پورتال‌ها پیاده‌سازی مودال را ساده می‌کنند. مزایای کلیدی عبارتند از:

• Z-Index تضمین شده: با رندر شدن در سطح `body` (یا یک کانتینر سطح بالای اختصاصی)، مودال‌ها همیشه می‌توانند به بالاترین `z-index` دست یابند بدون اینکه با زمینه‌های CSS تودرتو درگیر شوند. این تضمین می‌کند که آن‌ها همیشه روی تمام محتوای دیگر ظاهر می‌شوند، صرف نظر از کامپوننتی که آن‌ها را فعال کرده است.
• فرار از Overflow: والدها با `overflow: hidden` یا `overflow: auto` دیگر محتوای مودال را قطع نخواهند کرد. این برای مودال‌های بزرگ یا آن‌هایی که محتوای پویا دارند، حیاتی است.
• دسترسی‌پذیری (A11y): پورتال‌ها برای ساختن مودال‌های قابل دسترس اساسی هستند. با وجود اینکه ساختار DOM جدا است، اتصال منطقی درخت ری‌اکت امکان مدیریت صحیح فوکوس (به دام انداختن فوکوس در داخل مودال) و اعمال صحیح ویژگی‌های ARIA (مانند `aria-modal`) را فراهم می‌کند. کتابخانه‌هایی مانند `react-focus-lock` یا `@reach/dialog` به طور گسترده از پورتال‌ها برای این منظور استفاده می‌کنند.

۲. تولتیپ‌ها، پاپ‌اورها و دراپ‌داون‌های پویا

مشابه مودال‌ها، این عناصر اغلب نیاز دارند که در مجاورت یک عنصر فعال‌کننده ظاهر شوند اما از چیدمان‌های والد محدود خود نیز خارج شوند.

• موقعیت‌یابی دقیق: شما می‌توانید موقعیت عنصر فعال‌کننده را نسبت به ویوپورت محاسبه کرده و سپس تولتیپ را با استفاده از جاوا اسکریپت به صورت مطلق موقعیت‌دهی کنید. رندر کردن آن از طریق یک پورتال تضمین می‌کند که توسط خاصیت `overflow` در هیچ والد میانی قطع نخواهد شد.
• جلوگیری از جابجایی چیدمان (Layout Shifts): اگر یک تولتیپ به صورت درون‌خطی رندر می‌شد، وجود آن می‌توانست باعث جابجایی چیدمان در والد خود شود. پورتال‌ها رندر آن را جدا می‌کنند و از reflowهای ناخواسته جلوگیری می‌کنند.

۳. نوتیفیکیشن‌های سراسری و پیام‌های Toast

اپلیکیشن‌ها اغلب به سیستمی برای نمایش پیام‌های غیر مسدودکننده و موقتی نیاز دارند (مثلاً «آیتم به سبد خرید اضافه شد!»، «اتصال شبکه قطع شد»).

• مدیریت متمرکز: یک کامپوننت «ToastProvider» می‌تواند یک صف از پیام‌های toast را مدیریت کند. این provider می‌تواند از یک پورتال برای رندر کردن تمام پیام‌ها در یک `div` اختصاصی در بالا یا پایین `body` استفاده کند، و تضمین کند که آن‌ها همیشه قابل مشاهده و با استایل یکسان هستند، صرف نظر از اینکه پیام از کجای اپلیکیشن فعال شده است.
• ثبات: تضمین می‌کند که تمام نوتیفیکیشن‌ها در یک اپلیکیشن پیچیده به طور یکنواخت به نظر برسند و رفتار کنند.

۴. منوهای زمینه سفارشی

هنگامی که یک کاربر روی یک عنصر کلیک-راست می‌کند، اغلب یک منوی زمینه ظاهر می‌شود. این منو باید دقیقاً در مکان نشانگر ماوس قرار گیرد و روی تمام محتوای دیگر قرار بگیرد. پورتال‌ها در اینجا ایده‌آل هستند:

• کامپوننت منو می‌تواند از طریق یک پورتال رندر شود و مختصات کلیک را دریافت کند.
• این منو دقیقاً در جایی که لازم است ظاهر می‌شود، بدون اینکه توسط سلسله‌مراتب والد عنصر کلیک‌شده محدود شود.

۵. ادغام با کتابخانه‌های شخص ثالث یا عناصر DOM غیر ری‌اکتی

تصور کنید یک اپلیکیشن موجود دارید که بخشی از UI آن توسط یک کتابخانه جاوا اسکریپت قدیمی یا شاید یک راه‌حل نقشه‌برداری سفارشی که از گره‌های DOM خود استفاده می‌کند، مدیریت می‌شود. اگر می‌خواهید یک کامپوننت ری‌اکت کوچک و تعاملی را در چنین گره DOM خارجی رندر کنید، `ReactDOM.createPortal` پل شماست.

• شما می‌توانید یک گره DOM هدف را در داخل ناحیه تحت کنترل شخص ثالث ایجاد کنید.
• سپس، با استفاده از یک کامپوننت ری‌اکت با یک پورتال، UI ری‌اکت خود را به آن گره DOM خاص تزریق کنید، و به قدرت اعلانی ری‌اکت اجازه دهید تا بخش‌های غیر ری‌اکتی اپلیکیشن شما را بهبود بخشد.

ملاحظات پیشرفته هنگام استفاده از پورتال‌های ری‌اکت

در حالی که پورتال‌ها مشکلات پیچیده رندر را حل می‌کنند، درک چگونگی تعامل آن‌ها با سایر ویژگی‌های ری‌اکت و DOM برای استفاده مؤثر از آن‌ها و جلوگیری از دام‌های رایج، حیاتی است.

۱. حباب رویداد (Event Bubbling): یک تمایز حیاتی

یکی از قدرتمندترین و اغلب اشتباه درک شده‌ترین جنبه‌های پورتال‌های ری‌اکت، رفتار آن‌ها در مورد حباب رویداد است. با وجود اینکه در یک گره DOM کاملاً متفاوت رندر می‌شوند، رویدادهایی که از عناصر داخل یک پورتال شلیک می‌شوند، همچنان در درخت کامپوننت ری‌اکت به سمت بالا حباب می‌کنند، گویی که هیچ پورتالی وجود ندارد. این به این دلیل است که سیستم رویداد ری‌اکت مصنوعی است و در اکثر موارد مستقل از حباب رویداد DOM بومی کار می‌کند.

• این به چه معناست: اگر یک دکمه در داخل یک پورتال داشته باشید و رویداد کلیک آن دکمه به سمت بالا حباب کند، هر کنترل‌کننده `onClick` را در کامپوننت‌های والد منطقی خود در درخت ری‌اکت فعال می‌کند، نه والد DOM آن.
• مثال: اگر کامپوننت `Modal` شما توسط `App` رندر شود، یک کلیک در داخل `Modal` به کنترل‌کننده‌های رویداد `App` (در صورت پیکربندی) حباب می‌کند. این بسیار مفید است زیرا جریان رویداد شهودی را که در ری‌اکت انتظار دارید، حفظ می‌کند.
• رویدادهای DOM بومی: اگر شنوندگان رویداد DOM بومی را مستقیماً وصل کنید (مثلاً با استفاده از `addEventListener` روی `document.body`)، آن‌ها از درخت DOM بومی پیروی خواهند کرد. با این حال، برای رویدادهای مصنوعی استاندارد ری‌اکت (`onClick`, `onChange` و غیره)، درخت منطقی ری‌اکت غالب است.

۲. Context API و پورتال‌ها

Context API مکانیزم ری‌اکت برای به اشتراک گذاشتن مقادیر (مانند تم‌ها، وضعیت احراز هویت کاربر) در سراسر درخت کامپوننت بدون prop-drilling است. خوشبختانه، Context به طور یکپارچه با پورتال‌ها کار می‌کند.

• یک کامپوننت که از طریق یک پورتال رندر می‌شود، همچنان به ارائه‌دهندگان کانتکست (context providers) که اجداد آن در درخت کامپوننت منطقی ری‌اکت هستند، دسترسی خواهد داشت.
• این بدان معناست که شما می‌توانید یک `ThemeProvider` در بالای کامپوننت `App` خود داشته باشید و یک مودال که از طریق یک پورتال رندر می‌شود، همچنان آن کانتکست تم را به ارث می‌برد، که استایل‌دهی سراسری و مدیریت state را برای محتوای پورتال ساده می‌کند.

۳. دسترسی‌پذیری (A11y) با پورتال‌ها

ساختن UIهای قابل دسترس برای مخاطبان جهانی بسیار مهم است و پورتال‌ها ملاحظات A11y خاصی را به خصوص برای مودال‌ها و دیالوگ‌ها معرفی می‌کنند.

• مدیریت فوکوس: هنگامی که یک مودال باز می‌شود، فوکوس باید در داخل مودال به دام بیفتد تا از تعامل کاربران (به ویژه کاربران کیبورد و صفحه‌خوان) با عناصر پشت آن جلوگیری شود. هنگامی که مودال بسته می‌شود، فوکوس باید به عنصری که آن را فعال کرده است بازگردد. این اغلب به مدیریت دقیق جاوا اسکریپت نیاز دارد (مثلاً استفاده از `useRef` برای مدیریت عناصر قابل فوکوس، یا یک کتابخانه اختصاصی مانند `react-focus-lock`).
• ناوبری با کیبورد: اطمینان حاصل کنید که کلید `Esc` مودال را می‌بندد و کلید `Tab` فوکوس را فقط در داخل مودال می‌چرخاند.
• ویژگی‌های ARIA: از نقش‌ها و ویژگی‌های ARIA مانند `role="dialog"`، `aria-modal="true"`، `aria-labelledby` و `aria-describedby` به درستی در محتوای پورتال خود استفاده کنید تا هدف و ساختار آن را به فناوری‌های کمکی منتقل کنید.

۴. چالش‌ها و راه‌حل‌های استایل‌دهی

در حالی که پورتال‌ها مشکلات سلسله‌مراتب DOM را حل می‌کنند، آن‌ها به طور جادویی تمام پیچیدگی‌های استایل‌دهی را حل نمی‌کنند.

• استایل‌های سراسری در مقابل استایل‌های محلی (Scoped): از آنجایی که محتوای پورتال در یک گره DOM قابل دسترس جهانی (مانند `body` یا `modal-root`) رندر می‌شود، هر قانون CSS سراسری به طور بالقوه می‌تواند بر آن تأثیر بگذارد.
• CSS-in-JS و CSS Modules: این راه‌حل‌ها می‌توانند به کپسوله‌سازی استایل‌ها و جلوگیری از نشت ناخواسته کمک کنند، و آن‌ها را به ویژه هنگام استایل‌دهی محتوای پورتال مفید می‌سازند. Styled Components، Emotion یا CSS Modules می‌توانند نام‌های کلاس منحصر به فردی تولید کنند و اطمینان حاصل کنند که استایل‌های مودال شما با سایر بخش‌های اپلیکیشن شما تداخل ندارند، حتی اگر به صورت سراسری رندر شوند.
• تم‌بندی (Theming): همانطور که با Context API ذکر شد، اطمینان حاصل کنید که راه‌حل تم‌بندی شما (خواه متغیرهای CSS، تم‌های CSS-in-JS یا تم‌بندی مبتنی بر کانتکست) به درستی به فرزندان پورتال منتقل می‌شود.

۵. ملاحظات رندر سمت سرور (SSR)

اگر اپلیکیشن شما از رندر سمت سرور (SSR) استفاده می‌کند، باید مراقب رفتار پورتال‌ها باشید.

• `ReactDOM.createPortal` به یک عنصر DOM به عنوان آرگومان `container` خود نیاز دارد. در یک محیط SSR، رندر اولیه در سرور اتفاق می‌افتد که در آن DOM مرورگر وجود ندارد.
• این بدان معناست که پورتال‌ها معمولاً در سرور رندر نخواهند شد. آن‌ها فقط زمانی که جاوا اسکریپت در سمت کلاینت اجرا شود، «هیدراته» یا رندر می‌شوند.
• برای محتوایی که حتماً باید در رندر اولیه سرور وجود داشته باشد (مثلاً برای SEO یا عملکرد حیاتی اولین رندر)، پورتال‌ها مناسب نیستند. با این حال، برای عناصر تعاملی مانند مودال‌ها که معمولاً تا زمانی که یک عمل آن‌ها را فعال کند پنهان هستند، این به ندرت یک مشکل است. اطمینان حاصل کنید که کامپوننت‌های شما با بررسی وجود `container` پورتال در سرور (مثلاً `document.getElementById('modal-root')`)، عدم وجود آن را به خوبی مدیریت می‌کنند.

۶. تست کامپوننت‌هایی که از پورتال‌ها استفاده می‌کنند

تست کامپوننت‌هایی که از طریق پورتال‌ها رندر می‌شوند می‌تواند کمی متفاوت باشد اما توسط کتابخانه‌های تست محبوب مانند React Testing Library به خوبی پشتیبانی می‌شود.

• React Testing Library: این کتابخانه به طور پیش‌فرض از `document.body` کوئری می‌گیرد، که احتمالاً محتوای پورتال شما در آنجا قرار دارد. بنابراین، کوئری برای عناصر داخل مودال یا تولتیپ شما اغلب «به سادگی کار خواهد کرد».
• شبیه‌سازی (Mocking): در برخی سناریوهای پیچیده، یا اگر منطق پورتال شما به شدت به ساختارهای DOM خاصی وابسته است، ممکن است نیاز به شبیه‌سازی یا راه‌اندازی دقیق عنصر `container` هدف در محیط تست خود داشته باشید.

اشتباهات رایج و بهترین شیوه‌ها برای پورتال‌های ری‌اکت

برای اطمینان از اینکه استفاده شما از پورتال‌های ری‌اکت مؤثر، قابل نگهداری و با عملکرد خوب است، این بهترین شیوه‌ها را در نظر بگیرید و از اشتباهات رایج اجتناب کنید:

۱. از پورتال‌ها بیش از حد استفاده نکنید

پورتال‌ها قدرتمند هستند، اما باید با احتیاط استفاده شوند. اگر خروجی بصری یک کامپوننت را می‌توان بدون شکستن سلسله‌مراتب DOM به دست آورد (مثلاً با استفاده از موقعیت‌یابی نسبی یا مطلق در یک والد بدون سرریز)، این کار را انجام دهید. اتکای بیش از حد به پورتال‌ها گاهی اوقات می‌تواند اشکال‌زدایی ساختار DOM را در صورت عدم مدیریت دقیق، پیچیده کند.

۲. از پاک‌سازی مناسب (Unmounting) اطمینان حاصل کنید

اگر به صورت پویا یک گره DOM برای پورتال خود ایجاد می‌کنید (مانند مثال `Modal` ما با `el.current`)، اطمینان حاصل کنید که آن را هنگام unmount شدن کامپوننتی که از پورتال استفاده می‌کند، پاک‌سازی می‌کنید. تابع پاک‌سازی `useEffect` برای این کار عالی است و از نشت حافظه و شلوغ شدن DOM با عناصر یتیم جلوگیری می‌کند.

useEffect(() => {
  // ... اضافه کردن el.current
  return () => {
    // ... حذف el.current;
  };
}, []);

اگر همیشه در یک گره DOM ثابت و از پیش موجود (مانند یک `modal-root` واحد) رندر می‌کنید، پاک‌سازی خود *گره* لازم نیست، اما اطمینان از اینکه *محتوای پورتال* به درستی هنگام unmount شدن کامپوننت والد unmount می‌شود، همچنان به طور خودکار توسط ری‌اکت انجام می‌شود.

۳. ملاحظات عملکرد

برای اکثر موارد استفاده (مودال‌ها، تولتیپ‌ها)، پورتال‌ها تأثیر عملکردی ناچیزی دارند. با این حال، اگر در حال رندر کردن یک کامپوننت بسیار بزرگ یا با به‌روزرسانی مکرر از طریق یک پورتال هستید، بهینه‌سازی‌های عملکردی معمول ری‌اکت (مانند `React.memo`، `useCallback`، `useMemo`) را مانند هر کامپوننت پیچیده دیگری در نظر بگیرید.

۴. همیشه دسترسی‌پذیری را در اولویت قرار دهید

همانطور که تأکید شد، دسترسی‌پذیری حیاتی است. اطمینان حاصل کنید که محتوای رندر شده با پورتال شما از دستورالعمل‌های ARIA پیروی می‌کند و تجربه روانی را برای همه کاربران، به ویژه آن‌هایی که به ناوبری با کیبورد یا صفحه‌خوان‌ها متکی هستند، فراهم می‌کند.

• به دام انداختن فوکوس مودال: یک کتابخانه پیاده‌سازی یا استفاده کنید که فوکوس کیبورد را در داخل مودال باز شده به دام می‌اندازد.
• ویژگی‌های توصیفی ARIA: از `aria-labelledby` و `aria-describedby` برای پیوند دادن محتوای مودال به عنوان و توضیحات آن استفاده کنید.
• بستن با کیبورد: اجازه بستن با کلید `Esc` را بدهید.
• بازیابی فوکوس: هنگامی که مودال بسته می‌شود، فوکوس را به عنصری که آن را باز کرده است بازگردانید.

۵. از HTML معنایی در داخل پورتال‌ها استفاده کنید

در حالی که پورتال به شما امکان می‌دهد محتوا را از نظر بصری در هر جایی رندر کنید، به یاد داشته باشید که از عناصر HTML معنایی در داخل فرزندان پورتال خود استفاده کنید. به عنوان مثال، یک دیالوگ باید از عنصر `

// مثالی از یک PortalWrapper ساده
import React, { useEffect, useState } from 'react';
import ReactDOM from 'react-dom';

const createWrapperAndAppendToBody = (wrapperId) => {
  const wrapperElement = document.createElement('div');
  wrapperElement.setAttribute('id', wrapperId);
  document.body.appendChild(wrapperElement);
  return wrapperElement;
};

const PortalWrapper = ({ children, wrapperId = 'portal-wrapper' }) => {
  const [wrapperElement, setWrapperElement] = useState(null);

  useEffect(() => {
    let element = document.getElementById(wrapperId);
    let systemCreated = false;
    // اگر عنصری با شناسه wrapperId وجود نداشته باشد، آن را ایجاد کرده و به body اضافه کنید
    if (!element) {
      systemCreated = true;
      element = createWrapperAndAppendToBody(wrapperId);
    }
    setWrapperElement(element);

    return () => {
      // عنصری که به صورت برنامه‌ریزی شده ایجاد شده را حذف کنید
      if (systemCreated && element.parentNode) {
        element.parentNode.removeChild(element);
      }
    };
  }, [wrapperId]);

  if (!wrapperElement) return null;

  return ReactDOM.createPortal(children, wrapperElement);
};

export default PortalWrapper;