تسلط بر مدیریت رویداد در پورتال‌های ری‌اکت: تفویض رویداد در میان درخت‌های DOM برای اپلیکیشن‌های جهانی

در دنیای گسترده و به‌هم‌پیوسته توسعه وب، ساخت رابط‌های کاربری بصری و واکنش‌گرا که پاسخگوی مخاطبان جهانی باشد، از اهمیت بالایی برخوردار است. ری‌اکت، با معماری مبتنی بر کامپوننت خود، ابزارهای قدرتمندی برای دستیابی به این هدف فراهم می‌کند. در میان این ابزارها، پورتال‌های ری‌اکت (React Portals) به عنوان یک مکانیزم بسیار مؤثر برای رندر کردن فرزندان در یک گره DOM که خارج از سلسله‌مراتب کامپوننت والد قرار دارد، برجسته هستند. این قابلیت برای ایجاد عناصر UI مانند مودال‌ها، راهنماها (tooltips)، منوهای کشویی و اعلان‌هایی که نیاز دارند از محدودیت‌های استایل‌دهی یا زمینه انباشتگی `z-index` والد خود رها شوند، بسیار ارزشمند است.

در حالی که پورتال‌ها انعطاف‌پذیری فوق‌العاده‌ای ارائه می‌دهند، چالش منحصربه‌فردی را نیز به همراه دارند: مدیریت رویداد، به‌ویژه هنگام سروکار داشتن با تعاملاتی که بخش‌های مختلف درخت مدل شیء سند (DOM) را در بر می‌گیرند. هنگامی که کاربر با عنصری که از طریق یک پورتال رندر شده تعامل می‌کند، سفر رویداد در DOM ممکن است با ساختار منطقی درخت کامپوننت ری‌اکت همخوانی نداشته باشد. این مسئله در صورت عدم مدیریت صحیح می‌تواند منجر به رفتار غیرمنتظره شود. راه‌حل، که ما آن را به تفصیل بررسی خواهیم کرد، در یک مفهوم بنیادی توسعه وب نهفته است: تفویض رویداد (Event Delegation).

این راهنمای جامع، مدیریت رویداد با پورتال‌های ری‌اکت را رمزگشایی خواهد کرد. ما به پیچیدگی‌های سیستم رویداد ترکیبی (synthetic event) ری‌اکت خواهیم پرداخت، مکانیک حباب‌زدن (bubbling) و کپچر کردن (capture) رویداد را درک خواهیم کرد، و مهم‌تر از همه، نشان خواهیم داد که چگونه تفویض رویداد قدرتمندی را برای تضمین تجربیات کاربری یکپارچه و قابل پیش‌بینی برای اپلیکیشن‌های شما، صرف‌نظر از دسترسی جهانی یا پیچیدگی UI آن‌ها، پیاده‌سازی کنیم.

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

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

چرا پورتال‌های ری‌اکت برای رابط/تجربه کاربری جهانی ضروری هستند

یک دیالوگ مودال را در نظر بگیرید که باید بر روی تمام محتوای دیگر ظاهر شود، صرف‌نظر از خصوصیات `z-index` یا `overflow` کامپوننت والد آن. اگر این مودال به عنوان یک فرزند معمولی رندر می‌شد، ممکن بود توسط یک والد با `overflow: hidden` بریده شود یا به دلیل تداخل‌های `z-index` برای قرار گرفتن بالاتر از عناصر هم‌سطح خود دچار مشکل شود. پورتال‌ها این مشکل را با اجازه دادن به مودال برای مدیریت منطقی توسط کامپوننت والد ری‌اکت خود، اما رندر فیزیکی مستقیم در یک گره DOM مشخص، که اغلب فرزندی از document.body است، حل می‌کنند.

• فرار از محدودیت‌های کانتینر: پورتال‌ها به کامپوننت‌ها اجازه می‌دهند تا از محدودیت‌های بصری و استایل‌دهی کانتینر والد خود «فرار» کنند. این امر به‌ویژه برای لایه‌های رویی، منوهای کشویی، راهنماها و دیالوگ‌هایی که نیاز به موقعیت‌یابی نسبت به ویوپورت یا در بالاترین سطح زمینه انباشتگی دارند، مفید است.
• حفظ کانتکست و استیت ری‌اکت: با وجود رندر شدن در یک مکان متفاوت در DOM، یک کامپوننت رندر شده از طریق پورتال موقعیت خود را در درخت ری‌اکت حفظ می‌کند. این بدان معناست که همچنان می‌تواند به کانتکست دسترسی داشته باشد، پراپ‌ها را دریافت کند و در همان مدیریت استیت شرکت کند که گویی یک فرزند معمولی است، که جریان داده را ساده می‌کند.
• دسترسی‌پذیری بهبود یافته: پورتال‌ها می‌توانند در ایجاد UIهای قابل دسترس مؤثر باشند. به عنوان مثال، یک مودال می‌تواند مستقیماً در document.body رندر شود، که مدیریت به دام انداختن فوکوس (focus trapping) را آسان‌تر کرده و تضمین می‌کند که صفحه‌خوان‌ها محتوا را به درستی به عنوان یک دیالوگ سطح بالا تفسیر می‌کنند.
• سازگاری جهانی: برای اپلیکیشن‌هایی که به مخاطبان جهانی خدمت می‌کنند، رفتار UI سازگار حیاتی است. پورتال‌ها به توسعه‌دهندگان امکان می‌دهند الگوهای استاندارد UI (مانند رفتار سازگار مودال) را در بخش‌های مختلف یک اپلیکیشن پیاده‌سازی کنند بدون اینکه با مشکلات CSS آبشاری یا تداخلات سلسله‌مراتب DOM دست و پنجه نرم کنند.

یک تنظیمات معمول شامل ایجاد یک گره DOM اختصاصی در فایل index.html شما (مثلاً <div id="modal-root"></div>) و سپس استفاده از `ReactDOM.createPortal` برای رندر محتوا در آن است. به عنوان مثال:

// public/index.html
<body>
  <div id="root"></div>
  <div id="portal-root"></div>
</body>

// MyModal.js
import React from 'react';
import ReactDOM from 'react-dom';

const portalRoot = document.getElementById('portal-root');

const MyModal = ({ children, isOpen, onClose }) => {
  if (!isOpen) return null;

  return ReactDOM.createPortal(
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content" onClick={e => e.stopPropagation()}>
        {children}
        <button onClick={onClose}>Close</button>
      </div>
    </div>,
    portalRoot
  );
};

export default MyModal;

معضل مدیریت رویداد: زمانی که درخت‌های DOM و ری‌اکت از هم جدا می‌شوند

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

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

ویژگی خاص پورتال: یک انحراف در DOM

اینجاست که چالش پورتال‌ها نهفته است: در حالی که یک عنصر رندر شده از طریق پورتال از نظر منطقی فرزند والد ری‌اکت خود است، مکان فیزیکی آن در درخت DOM می‌تواند کاملاً متفاوت باشد. اگر اپلیکیشن اصلی شما در <div id="root"></div> مونت شده باشد و محتوای پورتال شما در <div id="portal-root"></div> (یک هم‌سطح از `root`) رندر شود، یک رویداد کلیک که از داخل پورتال نشأت می‌گیرد، مسیر DOM بومی *خودش* را به سمت بالا حباب می‌زند و در نهایت به `document.body` و سپس `document` می‌رسد. این رویداد به طور طبیعی از طریق `div#root` به سمت بالا حباب نخواهد زد تا به شنوندگان رویدادی که به اجداد والد *منطقی* پورتال در داخل `div#root` متصل شده‌اند، برسد.

این واگرایی به این معنی است که الگوهای سنتی مدیریت رویداد، که در آن ممکن است یک کنترل‌کننده کلیک روی یک عنصر والد قرار دهید و انتظار داشته باشید رویدادهای تمام فرزندانش را دریافت کند، می‌توانند در صورتی که آن فرزندان در یک پورتال رندر شده باشند، شکست بخورند یا به طور غیرمنتظره‌ای رفتار کنند. به عنوان مثال، اگر شما یک `div` در کامپوننت اصلی `App` خود با یک شنونده `onClick` داشته باشید و یک دکمه را در داخل یک پورتال که از نظر منطقی فرزند آن `div` است رندر کنید، کلیک کردن روی دکمه، کنترل‌کننده `onClick` `div` را از طریق حباب‌زدن DOM بومی فعال *نخواهد کرد*.

اما، و این یک تمایز حیاتی است: سیستم رویداد ترکیبی ری‌اکت این شکاف را پر می‌کند. هنگامی که یک رویداد بومی از یک پورتال نشأت می‌گیرد، مکانیسم داخلی ری‌اکت تضمین می‌کند که رویداد ترکیبی همچنان در درخت کامپوننت ری‌اکت به والد منطقی خود حباب می‌زند. این بدان معناست که اگر شما یک کنترل‌کننده `onClick` روی یک کامپوننت ری‌اکت داشته باشید که به طور منطقی حاوی یک پورتال است، یک کلیک در داخل پورتال *آن کنترل‌کننده را فعال خواهد کرد*. این یک جنبه بنیادی از سیستم رویداد ری‌اکت است که تفویض رویداد با پورتال‌ها را نه تنها ممکن، بلکه رویکرد توصیه‌شده می‌سازد.

راه‌حل: تفویض رویداد به تفصیل

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

مزایای کلیدی تفویض رویداد

• بهینه‌سازی عملکرد: به جای تعداد زیادی شنونده رویداد، شما فقط یکی دارید. این امر مصرف حافظه و زمان راه‌اندازی را کاهش می‌دهد، که به‌ویژه برای UIهای پیچیده با بسیاری از عناصر تعاملی یا برای اپلیکیشن‌های مستقر در سطح جهانی که بهره‌وری منابع در آن‌ها حیاتی است، مفید است.
• مدیریت محتوای پویا: عناصری که پس از رندر اولیه به DOM اضافه می‌شوند (مثلاً از طریق درخواست‌های AJAX یا تعاملات کاربر) به طور خودکار از شنوندگان تفویض‌شده بهره‌مند می‌شوند بدون اینکه نیاز به اتصال شنوندگان جدید داشته باشند. این برای محتوای پورتال که به صورت پویا رندر می‌شود کاملاً مناسب است.
• کد تمیزتر: متمرکز کردن منطق رویداد باعث می‌شود کدبیس شما سازمان‌یافته‌تر و نگهداری آن آسان‌تر شود.
• استحکام در ساختارهای مختلف DOM: همانطور که بحث کردیم، سیستم رویداد ترکیبی ری‌اکت تضمین می‌کند که رویدادهایی که از محتوای یک پورتال نشأت می‌گیرند *همچنان* در درخت کامپوننت ری‌اکت به اجداد منطقی خود حباب می‌زنند. این سنگ بنایی است که تفویض رویداد را به یک استراتژی مؤثر برای پورتال‌ها تبدیل می‌کند، حتی اگر مکان فیزیکی DOM آن‌ها متفاوت باشد.

توضیح حباب‌زدن و کپچر کردن رویداد

برای درک کامل تفویض رویداد، درک دو فاز انتشار رویداد در DOM حیاتی است:

1. فاز کپچرینگ (پایین آمدن): رویداد از ریشه `document` شروع می‌شود و در درخت DOM به سمت پایین حرکت می‌کند و از هر عنصر جد بازدید می‌کند تا به عنصر هدف برسد. شنوندگانی که با `useCapture = true` ثبت شده‌اند (یا در ری‌اکت، با افزودن پسوند `Capture`، مثلاً `onClickCapture`) در این فاز فعال می‌شوند.
2. فاز حباب‌زدن (بالا رفتن): پس از رسیدن به عنصر هدف، رویداد سپس در درخت DOM به سمت بالا بازمی‌گردد، از عنصر هدف به ریشه `document`، و از هر عنصر جد بازدید می‌کند. بیشتر شنوندگان رویداد، از جمله تمام `onClick`، `onChange` و غیره استاندارد ری‌اکت، در این فاز فعال می‌شوند.

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

پیاده‌سازی تفویض رویداد با پورتال‌های ری‌اکت

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

سناریو: یک مودال که با کلیک در خارج بسته می‌شود

ما می‌خواهیم یک کامپوننت مودال را با استفاده از یک پورتال ری‌اکت پیاده‌سازی کنیم. مودال باید زمانی که روی یک دکمه کلیک می‌شود ظاهر شود و باید زمانی بسته شود که:

• کاربر روی لایه نیمه‌شفاف (پس‌زمینه) اطراف محتوای مودال کلیک می‌کند.
• کاربر کلید `Escape` را فشار می‌دهد.
• کاربر روی یک دکمه صریح «بستن» در داخل مودال کلیک می‌کند.

پیاده‌سازی گام به گام

گام ۱: آماده‌سازی HTML و کامپوننت پورتال

اطمینان حاصل کنید که فایل `index.html` شما یک ریشه اختصاصی برای پورتال‌ها دارد. برای این مثال، از `id="portal-root"` استفاده می‌کنیم.

// public/index.html (snippet)
<body>
  <div id="root"></div>
  <div id="portal-root"></div> <!-- هدف پورتال ما -->
</body>

سپس، یک کامپوننت ساده `Portal` ایجاد کنید تا منطق `ReactDOM.createPortal` را کپسوله کند. این کار کامپوننت مودال ما را تمیزتر می‌کند.

// components/Portal.js
import { useEffect, useState } from 'react';
import { createPortal } from 'react-dom';

interface PortalProps {
  children: React.ReactNode;
  wrapperId?: string;
}

// اگر دیوی برای شناسه wrapperId وجود نداشته باشد، یکی برای پورتال ایجاد می‌کنیم
function createWrapperAndAppendToBody(wrapperId: string) {
  const wrapperElement = document.createElement('div');
  wrapperElement.setAttribute('id', wrapperId);
  document.body.appendChild(wrapperElement);
  return wrapperElement;
}

function Portal({ children, wrapperId = 'portal-wrapper' }: PortalProps) {
  const [wrapperElement, setWrapperElement] = useState<HTMLElement | null>(null);

  useEffect(() => {
    let element = document.getElementById(wrapperId) as HTMLElement;
    let created = false;

    if (!element) {
      created = true;
      element = createWrapperAndAppendToBody(wrapperId);
    }
    setWrapperElement(element);

    return () => {
      // اگر ما عنصر را ایجاد کرده‌ایم، آن را پاکسازی می‌کنیم
      if (created && element.parentNode) {
        element.parentNode.removeChild(element);
      }
    };
  }, [wrapperId]);

  // در اولین رندر، wrapperElement تهی خواهد بود. این مشکلی ندارد چون ما چیزی رندر نخواهیم کرد.
  if (!wrapperElement) return null;

  return createPortal(children, wrapperElement);
}

export default Portal;

توجه: برای سادگی، `portal-root` در مثال‌های قبلی در `index.html` به صورت هاردکد شده بود. این کامپوننت `Portal.js` یک رویکرد پویاتر ارائه می‌دهد و در صورت عدم وجود یک دیو پوشاننده، آن را ایجاد می‌کند. روشی را انتخاب کنید که به بهترین شکل با نیازهای پروژه شما مطابقت دارد. ما برای کامپوننت `Modal` به منظور مستقیم بودن، با استفاده از `portal-root` مشخص شده در `index.html` ادامه خواهیم داد، اما `Portal.js` بالا یک جایگزین قوی است.

گام ۲: ایجاد کامپوننت مودال

کامپوننت `Modal` ما محتوای خود را به عنوان `children` و یک کال‌بک `onClose` دریافت خواهد کرد.

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

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}

const modalRoot = document.getElementById('portal-root') as HTMLElement;

const Modal = ({ isOpen, onClose, children }: ModalProps) => {
  const modalContentRef = useRef<HTMLDivElement>(null);

  if (!isOpen) return null;

  // مدیریت فشردن کلید Escape
  useEffect(() => {
    const handleEscape = (event: KeyboardEvent) => {
      if (event.key === 'Escape') {
        onClose();
      }
    };
    document.addEventListener('keydown', handleEscape);
    return () => {
      document.removeEventListener('keydown', handleEscape);
    };
  }, [onClose]);

  // کلید تفویض رویداد: یک کنترل‌کننده کلیک واحد روی پس‌زمینه.
  // این همچنین به طور ضمنی به دکمه بستن داخل مودال تفویض می‌شود.
  const handleBackdropClick = (event: React.MouseEvent<HTMLDivElement>) => {
    // بررسی کنید که آیا هدف کلیک خود پس‌زمینه است، نه محتوای داخل مودال.
    // استفاده از `modalContentRef.current.contains(event.target)` در اینجا حیاتی است.
    // event.target عنصری است که کلیک از آن نشأت گرفته است.
    // event.currentTarget عنصری است که شنونده رویداد به آن متصل شده است (modal-overlay).
    if (modalContentRef.current && !modalContentRef.current.contains(event.target as Node)) {
      onClose();
    }
  };

  return ReactDOM.createPortal(
    <div className="modal-overlay" onClick={handleBackdropClick}>
      <div className="modal-content" ref={modalContentRef}>
        {children}
        <button onClick={onClose} aria-label="Close modal">X</button>
      </div>
    </div>,
    modalRoot
  );
};

export default Modal;

گام ۳: ادغام در کامپوننت اصلی اپلیکیشن

کامپوننت اصلی `App` ما وضعیت باز/بسته بودن مودال را مدیریت کرده و `Modal` را رندر خواهد کرد.

// App.js
import React, { useState } from 'react';
import Modal from './components/Modal';
import './App.css'; // برای استایل‌دهی اولیه

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

  const openModal = () => setIsModalOpen(true);
  const closeModal = () => setIsModalOpen(false);

  return (
    <div className="App">
      <h1>React Portal Event Delegation Example</h1>
      <p>Demonstrating event handling across different DOM trees.</p>

      <button onClick={openModal}>Open Modal</button>

      <Modal isOpen={isModalOpen} onClose={closeModal}>
        <h2>Welcome to the Modal!</h2>
        <p>This content is rendered in a React Portal, outside the main application's DOM hierarchy.</p>
        <button onClick={closeModal}>Close from inside</button>
      </Modal>

      <p>Some other content behind the modal.</p>
      <p>Another paragraph to show the background.</p>
    </div>
  );
}

export default App;

گام ۴: استایل‌دهی اولیه (App.css)

برای به تصویر کشیدن مودال و پس‌زمینه آن.

/* App.css */
.modal-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.6);
  display: flex;
  justify-content: center;
  align-items: center;
  z-index: 1000;
}

.modal-content {
  background: white;
  padding: 30px;
  border-radius: 8px;
  min-width: 300px;
  max-width: 80%;
  box-shadow: 0 5px 15px rgba(0, 0, 0, 0.3);
  position: relative; /* Needed for internal button positioning if any */
}

.modal-content button {
  margin-top: 15px;
  padding: 8px 15px;
  background-color: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 1rem;
}

.modal-content button:hover {
  background-color: #0056b3;
}

.modal-content > button:last-child { /* استایل برای دکمه بستن 'X' */
    position: absolute;
    top: 10px;
    right: 10px;
    background: none;
    color: #333;
    font-size: 1.2rem;
    padding: 0;
    margin: 0;
    border: none;
}

.App {
  font-family: Arial, sans-serif;
  padding: 20px;
  text-align: center;
}

.App button {
  padding: 10px 20px;
  font-size: 1.1rem;
  background-color: #28a745;
  color: white;
  border: none;
  border-radius: 5px;
  cursor: pointer;
}

.App button:hover {
  background-color: #218838;
}

توضیح منطق تفویض

در کامپوننت `Modal` ما، `onClick={handleBackdropClick}` به دیو `.modal-overlay` متصل شده است که به عنوان شنونده تفویض‌شده ما عمل می‌کند. هنگامی که هر کلیکی در داخل این لایه رویی رخ می‌دهد (که شامل `modal-content` و دکمه بستن `X` در داخل آن و همچنین دکمه «بستن از داخل» است)، تابع `handleBackdropClick` اجرا می‌شود.

در داخل `handleBackdropClick`:

• `event.target` به عنصر DOM خاصی اشاره دارد که *واقعاً کلیک شده است* (مثلاً `<h2>`، `<p>`، یا یک `<button>` در داخل `modal-content`، یا خود `modal-overlay`).
• `event.currentTarget` به عنصری اشاره دارد که شنونده رویداد به آن متصل شده است، که در این مورد دیو `.modal-overlay` است.
• شرط `!modalContentRef.current.contains(event.target as Node)` قلب تفویض ما است. این شرط بررسی می‌کند که آیا عنصر کلیک شده (`event.target`) از نوادگان دیو `modal-content` *نیست*. اگر `event.target` خود `.modal-overlay` باشد، یا هر عنصر دیگری که فرزند مستقیم لایه رویی است اما بخشی از `modal-content` نیست، آنگاه `contains` مقدار `false` برمی‌گرداند و مودال بسته می‌شود.
• به طور حیاتی، سیستم رویداد ترکیبی ری‌اکت تضمین می‌کند که حتی اگر `event.target` عنصری باشد که به صورت فیزیکی در `portal-root` رندر شده است، کنترل‌کننده `onClick` روی والد منطقی (`.modal-overlay` در کامپوننت Modal) همچنان فعال خواهد شد و `event.target` به درستی عنصر عمیقاً تودرتو را شناسایی خواهد کرد.

برای دکمه‌های بستن داخلی، صرفاً فراخوانی `onClose()` به طور مستقیم روی کنترل‌کننده‌های `onClick` آنها کار می‌کند زیرا این کنترل‌کننده‌ها *قبل از* اینکه رویداد به شنونده تفویض‌شده `modal-overlay` حباب بزند، اجرا می‌شوند یا به صراحت مدیریت می‌شوند. حتی اگر حباب می‌زدند، بررسی `contains()` ما از بسته شدن مودال در صورتی که کلیک از داخل محتوا نشأت گرفته باشد، جلوگیری می‌کرد.

`useEffect` برای شنونده کلید `Escape` مستقیماً به `document` متصل شده است، که یک الگوی رایج و مؤثر برای میانبرهای صفحه کلید جهانی است، زیرا تضمین می‌کند که شنونده صرف‌نظر از فوکوس کامپوننت فعال است و رویدادها را از هر جای DOM، از جمله آنهایی که از داخل پورتال‌ها نشأت می‌گیرند، دریافت خواهد کرد.

پرداختن به سناریوهای رایج تفویض رویداد

جلوگیری از انتشار ناخواسته رویداد: `event.stopPropagation()`

گاهی اوقات، حتی با وجود تفویض، ممکن است عناصر خاصی در ناحیه تفویض‌شده خود داشته باشید که بخواهید به صراحت از حباب زدن بیشتر یک رویداد به سمت بالا جلوگیری کنید. به عنوان مثال، اگر شما یک عنصر تعاملی تودرتو در داخل محتوای مودال خود داشتید که وقتی کلیک می‌شود، نباید منطق `onClose` را فعال کند (حتی اگر بررسی `contains` قبلاً آن را مدیریت می‌کرد)، می‌توانید از `event.stopPropagation()` استفاده کنید.

<div className="modal-content" ref={modalContentRef}>
  <h2>Modal Content</h2>
  <p>Clicking this area will not close the modal.</p>
  <button onClick={(e) => {
    e.stopPropagation(); // جلوگیری از حباب‌زدن این کلیک به پس‌زمینه
    console.log('Inner button clicked!');
  }}>Inner Action Button</button>
  <button onClick={onClose}>Close</button>
</div>

در حالی که `event.stopPropagation()` می‌تواند مفید باشد، از آن با احتیاط استفاده کنید. استفاده بیش از حد می‌تواند جریان رویداد را غیرقابل پیش‌بینی و اشکال‌زدایی را دشوار کند، به‌ویژه در اپلیکیشن‌های بزرگ و توزیع‌شده جهانی که تیم‌های مختلف ممکن است در UI مشارکت داشته باشند.

مدیریت عناصر فرزند خاص با تفویض

فراتر از بررسی ساده اینکه آیا یک کلیک در داخل یا خارج است، تفویض رویداد به شما امکان می‌دهد بین انواع مختلف کلیک‌ها در ناحیه تفویض‌شده تمایز قائل شوید. می‌توانید از ویژگی‌هایی مانند `event.target.tagName`، `event.target.id`، `event.target.className` یا صفات `event.target.dataset` برای انجام اقدامات مختلف استفاده کنید.

const handleBackdropClick = (event: React.MouseEvent<HTMLDivElement>) => {
  if (modalContentRef.current && modalContentRef.current.contains(event.target as Node)) {
    // کلیک داخل محتوای مودال بود
    const clickedElement = event.target as HTMLElement;

    if (clickedElement.tagName === 'BUTTON' && clickedElement.dataset.action === 'confirm') {
      console.log('Confirm action triggered!');
      onClose();
    } else if (clickedElement.tagName === 'A') {
      console.log('Link inside modal clicked:', clickedElement.href);
      // به طور بالقوه از رفتار پیش‌فرض جلوگیری کرده یا به صورت برنامه‌ریزی شده هدایت می‌کنیم
    }
    // سایر کنترل‌کننده‌های خاص برای عناصر داخل مودال
  } else {
    // کلیک خارج از محتوای مودال بود (روی پس‌زمینه)
    onClose();
  }
};

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

چه زمانی تفویض نکنیم

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

• رفتار بسیار خاص کامپوننت: اگر یک کامپوننت منطق رویداد بسیار تخصصی و خودکفایی داشته باشد که نیازی به تعامل با کنترل‌کننده‌های تفویض‌شده اجداد خود ندارد.
• عناصر ورودی با `onChange`: برای کامپوننت‌های کنترل‌شده مانند ورودی‌های متنی، شنوندگان `onChange` معمولاً مستقیماً روی عنصر ورودی برای به‌روزرسانی‌های فوری استیت قرار می‌گیرند. در حالی که این رویدادها نیز حباب می‌زنند، مدیریت مستقیم آنها یک عمل استاندارد است.
• رویدادهای با فرکانس بالا و حیاتی از نظر عملکرد: برای رویدادهایی مانند `mousemove` یا `scroll` که بسیار مکرر فعال می‌شوند، تفویض به یک جد دور ممکن است سربار جزئی بررسی مکرر `event.target` را به همراه داشته باشد. با این حال، برای اکثر تعاملات UI (کلیک‌ها، فشردن کلیدها)، مزایای تفویض بسیار بیشتر از این هزینه ناچیز است.

الگوهای پیشرفته و ملاحظات

برای اپلیکیشن‌های پیچیده‌تر، به‌ویژه آنهایی که به پایگاه‌های کاربری متنوع جهانی پاسخ می‌دهند، ممکن است الگوهای پیشرفته‌ای را برای مدیریت رویدادها در پورتال‌ها در نظر بگیرید.

ارسال رویداد سفارشی

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

// داخل یک کامپوننت پورتال
const handleCustomAction = () => {
  const event = new CustomEvent('my-custom-portal-event', { detail: { data: 'some info' }, bubbles: true });
  document.dispatchEvent(event);
};

// جایی در اپلیکیشن اصلی شما، مثلاً در یک هوک افکت
useEffect(() => {
  const handler = (event: Event) => {
    if (event instanceof CustomEvent) {
      console.log('Custom event received:', event.detail);
    }
  };
  document.addEventListener('my-custom-portal-event', handler);
  return () => document.removeEventListener('my-custom-portal-event', handler);
}, []);

این رویکرد کنترل دقیقی را ارائه می‌دهد اما نیازمند مدیریت دقیق انواع رویداد و محموله‌ها است.

Context API برای کنترل‌کننده‌های رویداد

برای اپلیکیشن‌های بزرگ با محتوای پورتال عمیقاً تودرتو، ارسال `onClose` یا سایر کنترل‌کننده‌ها از طریق پراپ‌ها می‌تواند منجر به حفاری پراپ (prop drilling) شود. Context API ری‌اکت یک راه‌حل زیبا ارائه می‌دهد:

// context/ModalContext.js
import React, { createContext, useContext } from 'react';

interface ModalContextType {
  onClose?: () => void;
  // در صورت نیاز سایر کنترل‌کننده‌های مربوط به مودال را اضافه کنید
}

const ModalContext = createContext<ModalContextType>({});

export const useModal = () => useContext(ModalContext);

export const ModalProvider = ({ children, onClose }: ModalContextType & React.PropsWithChildren) => (
  <ModalContext.Provider value={{ onClose }}>
    {children}
  </ModalContext.Provider>
);

// components/Modal.js (به‌روز شده برای استفاده از کانتکست)
// ... (ایمپورت‌ها و modalRoot تعریف شده‌اند)

const Modal = ({ isOpen, onClose, children }: ModalProps) => {
  const modalContentRef = useRef<HTMLDivElement>(null);
  // ... (useEffect برای کلید Escape، handleBackdropClick تا حد زیادی یکسان باقی می‌ماند)

  if (!isOpen) return null;

  return ReactDOM.createPortal(
    <div className="modal-overlay" onClick={handleBackdropClick}>
      <div className="modal-content" ref={modalContentRef}>
        <ModalProvider onClose={onClose}>{children}</ModalProvider> <!-- فراهم کردن کانتکست -->
        <button onClick={onClose} aria-label="Close modal">X</button>
      </div>
    </div>,
    modalRoot
  );
};

export default Modal;

// components/DeeplyNestedComponent.js (جایی داخل فرزندان مودال)
import React from 'react';
import { useModal } from '../context/ModalContext';

const DeeplyNestedComponent = () => {
  const { onClose } = useModal();

  return (
    <div>
      <p>This component is deep inside the modal.</p>
      {onClose && <button onClick={onClose}>Close from Deep Nest</button>}
    </div>
  );
};

استفاده از Context API یک روش تمیز برای ارسال کنترل‌کننده‌ها (یا هر داده مرتبط دیگری) به پایین درخت کامپوننت به محتوای پورتال فراهم می‌کند، که رابط‌های کامپوننت را ساده کرده و قابلیت نگهداری را بهبود می‌بخشد، به‌ویژه برای تیم‌های بین‌المللی که روی سیستم‌های UI پیچیده همکاری می‌کنند.

پیامدهای عملکردی

در حالی که تفویض رویداد خود یک تقویت‌کننده عملکرد است، به پیچیدگی منطق `handleBackdropClick` یا منطق تفویض‌شده خود توجه داشته باشید. اگر در هر کلیک پیمایش‌های DOM یا محاسبات گران‌قیمتی انجام می‌دهید، این می‌تواند بر عملکرد تأثیر بگذارد. بررسی‌های خود را (مثلاً `event.target.closest()`، `element.contains()`) بهینه کنید تا تا حد امکان کارآمد باشند. برای رویدادهای با فرکانس بسیار بالا، در صورت لزوم، دیبانسینگ (debouncing) یا تراتلینگ (throttling) را در نظر بگیرید، هرچند این برای رویدادهای ساده کلیک/فشردن کلید در مودال‌ها کمتر رایج است.

ملاحظات دسترسی‌پذیری (A11y) برای مخاطبان جهانی

دسترسی‌پذیری یک afterthought نیست؛ این یک نیاز اساسی است، به‌ویژه هنگام ساخت برای یک مخاطب جهانی با نیازهای متنوع و فناوری‌های کمکی. هنگام استفاده از پورتال‌ها برای مودال‌ها یا لایه‌های رویی مشابه، مدیریت رویداد نقش حیاتی در دسترسی‌پذیری ایفا می‌کند:

• مدیریت فوکوس: هنگامی که یک مودال باز می‌شود، فوکوس باید به صورت برنامه‌ریزی شده به اولین عنصر تعاملی در داخل مودال منتقل شود. هنگامی که مودال بسته می‌شود، فوکوس باید به عنصری که باز شدن آن را آغاز کرده بود، بازگردد. این کار اغلب با `useEffect` و `useRef` انجام می‌شود.
• تعامل با صفحه‌کلید: عملکرد بستن با کلید `Escape` (همانطور که نشان داده شد) یک الگوی دسترسی‌پذیری حیاتی است. اطمینان حاصل کنید که تمام عناصر تعاملی در داخل مودال با صفحه‌کلید قابل پیمایش هستند (کلید `Tab`).
• صفات ARIA: از نقش‌ها و صفات ARIA مناسب استفاده کنید. برای مودال‌ها، `role="dialog"` یا `role="alertdialog"`، `aria-modal="true"` و `aria-labelledby` یا `aria-describedby` ضروری هستند. این صفات به صفحه‌خوان‌ها کمک می‌کنند تا حضور مودال را اعلام کرده و هدف آن را توصیف کنند.
• به دام انداختن فوکوس (Focus Trapping): به دام انداختن فوکوس را در داخل مودال پیاده‌سازی کنید. این تضمین می‌کند که وقتی کاربر `Tab` را فشار می‌دهد، فوکوس فقط در میان عناصر *داخل* مودال چرخش می‌کند، نه عناصر در اپلیکیشن پس‌زمینه. این کار معمولاً با کنترل‌کننده‌های `keydown` اضافی روی خود مودال به دست می‌آید.

دسترسی‌پذیری قوی فقط مربوط به انطباق نیست؛ این دامنه دسترسی اپلیکیشن شما را به پایگاه کاربری جهانی گسترده‌تری، از جمله افراد دارای معلولیت، گسترش می‌دهد و تضمین می‌کند که همه می‌توانند به طور مؤثر با UI شما تعامل داشته باشند.

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

به طور خلاصه، در اینجا بهترین شیوه‌های کلیدی برای مدیریت مؤثر رویدادها با پورتال‌های ری‌اکت آورده شده است:

• تفویض رویداد را بپذیرید: همیشه ترجیح دهید یک شنونده رویداد واحد را به یک جد مشترک (مانند پس‌زمینه یک مودال) متصل کنید و از `event.target` با `element.contains()` یا `event.target.closest()` برای شناسایی عنصر کلیک شده استفاده کنید.
• رویدادهای ترکیبی ری‌اکت را درک کنید: به یاد داشته باشید که سیستم رویداد ترکیبی ری‌اکت به طور مؤثر رویدادها را از پورتال‌ها مجدداً هدف‌گذاری می‌کند تا در درخت کامپوننت منطقی ری‌اکت خود حباب بزنند، که این امر تفویض را قابل اعتماد می‌سازد.
• شنوندگان جهانی را با احتیاط مدیریت کنید: برای رویدادهای جهانی مانند فشردن کلید `Escape`، شنوندگان را مستقیماً به `document` در داخل یک هوک `useEffect` متصل کنید و از پاکسازی مناسب اطمینان حاصل کنید.
• `stopPropagation()` را به حداقل برسانید: از `event.stopPropagation()` به ندرت استفاده کنید. این می‌تواند جریان‌های رویداد پیچیده‌ای ایجاد کند. منطق تفویض خود را طوری طراحی کنید که به طور طبیعی اهداف کلیک مختلف را مدیریت کند.
• دسترسی‌پذیری را در اولویت قرار دهید: ویژگی‌های دسترسی‌پذیری جامع را از همان ابتدا پیاده‌سازی کنید، از جمله مدیریت فوکوس، پیمایش با صفحه‌کلید و صفات ARIA مناسب.
• از `useRef` برای ارجاع به DOM استفاده کنید: از `useRef` برای گرفتن ارجاع‌های مستقیم به عناصر DOM در داخل پورتال خود استفاده کنید، که برای بررسی‌های `element.contains()` حیاتی است.
• برای پراپ‌های پیچیده از Context API استفاده کنید: برای درخت‌های کامپوننت عمیق در داخل پورتال‌ها، از Context API برای ارسال کنترل‌کننده‌های رویداد یا سایر استیت‌های مشترک استفاده کنید تا حفاری پراپ کاهش یابد.
• به طور کامل تست کنید: با توجه به ماهیت بین-DOM پورتال‌ها، مدیریت رویداد را در تعاملات مختلف کاربر، محیط‌های مرورگر و فناوری‌های کمکی به طور دقیق تست کنید.

نتیجه‌گیری

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

پیاده‌سازی تفویض رویداد تضمین می‌کند که اپلیکیشن‌های جهانی شما یک تجربه کاربری سازگار و قوی را، صرف‌نظر از ساختار زیربنایی DOM، ارائه می‌دهند. این به کدی تمیزتر و قابل نگهداری‌تر منجر می‌شود و راه را برای توسعه UI مقیاس‌پذیر هموار می‌کند. این الگوها را بپذیرید، و شما به خوبی مجهز خواهید شد تا از قدرت کامل پورتال‌های ری‌اکت در پروژه بعدی خود بهره‌برداری کنید و تجربیات دیجیتال استثنایی را به کاربران در سراسر جهان ارائه دهید.