البوابات في React: createPortal للنوافذ المنبثقة والتلميحات

تعرض البوابة (portal) جزءًا من مكوّن في مكان مختلف من DOM، عادة document.body، بينما يبقى في المكان نفسه من شجرة React. تنشئ واحدة بـ createPortal(children, domNode) من react-dom. والبوابات هي طريقة إفلات النوافذ المنبثقة والتلميحات والقوائم المنسدلة من أب له overflow: hidden أو سياق تراكب خاص به.

يقصّ الصندوق أدناه كل ما يبرز منه. افتح التلميحين.

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

const tipStyle = { position: 'absolute', width: 150, padding: 8, background: '#222', color: '#fff', borderRadius: 6, fontSize: 13 };

export default function App() {
    const [inlineOpen, setInlineOpen] = useState(false);
    const [portalPos, setPortalPos] = useState(null);

    function togglePortal(e) {
        if (portalPos) return setPortalPos(null);
        const r = e.currentTarget.getBoundingClientRect();
        setPortalPos({ top: r.bottom + window.scrollY + 6, left: r.left + window.scrollX });
    }

    return (
        <div>
            <div style={{ position: 'relative', overflow: 'hidden', height: 60, maxWidth: 340, padding: 8, border: '2px dashed #999', display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}>
                <button onClick={() => setInlineOpen(!inlineOpen)}>Normal tip</button>
                <button onClick={togglePortal}>Portal tip</button>
                {inlineOpen && (
                    <div style={{ ...tipStyle, top: 44, left: 8 }}>
                        I render inside the box, so its overflow: hidden cuts me off.
                    </div>
                )}
            </div>
            {portalPos &&
                createPortal(
                    <div style={{ ...tipStyle, ...portalPos }}>
                        I render into document.body, so nothing clips me.
                    </div>,
                    document.body,
                )}
            <div style={{ height: 90 }} />
        </div>
    );
}

يُقطع التلميح العادي عند الحد المتقطع. أما تلميح البوابة فيظهر كاملًا، لأن عقدة DOM الخاصة به ابن لـ <body>، لا للصندوق. احذف overflow: 'hidden' من الصندوق فلا يعود التلميح العادي مقصوصًا.

الصيغة

import { createPortal } from 'react-dom';

createPortal(children, domNode, key?)

• children أي JSX: عنصر، أو جزء، أو مكوّن.
• domNode عنصر DOM موجود، مثل document.body أو document.getElementById('modal-root'). ويجب أن يكون موجودًا عندما تُعرض البوابة.
• key اختياري، لحين تعرض قائمة من البوابات.

تُرجع createPortal شيئًا تضعه في JSX مثل أي عنصر. ولا تعرض شيئًا في موضع DOM الخاص بالأب.

نافذة منبثقة في document.body

النافذة المنبثقة هي الحالة الكلاسيكية. داخل بطاقة لها transform، يتحدد موضع الغطاء position: fixed نسبة إلى تلك البطاقة بدلًا من النافذة، ثم يقصّه overflow: hidden الخاص بالبطاقة. أما عند عرضه داخل document.body فيغطي منفذ العرض كله.

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

function Modal({ title, onClose, children }) {
    const closeRef = useRef(null);

    useEffect(() => {
        closeRef.current.focus();
        function onKey(e) {
            if (e.key === 'Escape') onClose();
        }
        document.addEventListener('keydown', onKey);
        return () => document.removeEventListener('keydown', onKey);
    }, [onClose]);

    return createPortal(
        <div onClick={onClose} style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.4)', display: 'grid', placeItems: 'center' }}>
            <div role="dialog" aria-modal="true" aria-labelledby="modal-title" onClick={(e) => e.stopPropagation()} style={{ background: '#fff', padding: 16, borderRadius: 8, width: 240 }}>
                <h3 id="modal-title" style={{ marginTop: 0 }}>{title}</h3>
                {children}
                <button ref={closeRef} onClick={onClose}>Close</button>
            </div>
        </div>,
        document.body,
    );
}

export default function App() {
    const [open, setOpen] = useState(false);

    return (
        <div style={{ transform: 'scale(1)', overflow: 'hidden', border: '1px solid #ccc', padding: 12 }}>
            <p>A card with transform and overflow: hidden.</p>
            <button onClick={() => setOpen(true)}>Open modal</button>
            {open && (
                <Modal title="Delete draft?" onClose={() => setOpen(false)}>
                    <p>The overlay covers the whole frame, not just the card.</p>
                </Modal>
            )}
        </div>
    );
}

افتح النافذة المنبثقة، ثم اضغط Escape أو انقر الغطاء الداكن لإغلاقها. ينتقل التركيز إلى زر Close عندما تنفتح. أرجع الآن الغطاء دون createPortal (احذف الاستدعاء ووسيطه document.body): يتقلص الغطاء إلى حجم البطاقة، لأن transform يجعل البطاقة الكتلة الحاوية للعناصر الثابتة.

الأحداث تنتشر عبر شجرة React

تغيّر البوابة مكان عيش عقدة DOM، لا مكان عيش المكوّن. تنتشر أحداث React صعودًا عبر شجرة React، فتصل النقرة داخل بوابة إلى onClick الخاص بالمكوّن الذي عرضها، رغم أن الزر في DOM ابن لـ <body>.

أما المستمعات الأصلية فمختلفة. المستمع المضاف بـ addEventListener يتبع شجرة DOM ولا يرى النقرة أبدًا.

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

export default function App() {
    const wrapperRef = useRef(null);

    useEffect(() => {
        const node = wrapperRef.current;
        const onNativeClick = () => console.log('native listener on the wrapper div');
        node.addEventListener('click', onNativeClick);
        return () => node.removeEventListener('click', onNativeClick);
    }, []);

    return (
        <div
            ref={wrapperRef}
            onClick={(e) => console.log('React onClick on the wrapper, target:', e.target.textContent)}
            style={{ padding: 12, border: '2px dashed #999' }}
        >
            <button>Inside the wrapper</button>
            {createPortal(<button style={{ margin: 16 }}>In a portal</button>, document.body)}
        </div>
    );
}

انقر "Inside the wrapper": يسجّل معالج React والمستمع الأصلي كلاهما. وانقر "In a portal": لا يسجّل إلا معالج React. يقع زر البوابة خارج الغلاف المتقطع على الشاشة، ومع ذلك ما زالت React تعامله كابن.

هذا عادة ما تريده: يرى onClick على أب القائمة النقرات على عناصر بوابتها، ومزوّدو السياق فوق المكوّن ينطبقون داخل البوابة أيضًا. لكنه قد يفاجئك مع منطق «انقر خارجها للإغلاق». فالـ onClick على غلاف يغلق قائمة يُطلق أيضًا للنقرات داخل بوابة القائمة، فأوقف الانتشار داخل القائمة (e.stopPropagation()، الذي تتناوله صفحة الأحداث)، أو استخدم مستمعًا أصليًا على document وتحقق مما إذا كان الهدف داخل عقدة DOM الخاصة بالبوابة.

بوابات داخل حاويتك الخاصة

document.body أبسط هدف. وتضيف بعض التطبيقات حاوية مخصصة إلى index.html لتتشارك كل الأغطية مكانًا واحدًا وترتيب تراكب واحدًا:

<body>
    <div id="root"></div>
    <div id="modal-root"></div>
</body>

createPortal(<Modal />, document.getElementById('modal-root'));

مع العرض على الخادم (Next.js وأطر العمل الأخرى)، لا يوجد document على الخادم. اعرض البوابة فقط بعد أن يُركَّب المكوّن، مثلًا خلف حالة mounted يضبطها تأثير على true.

وعندما يجب أن يتحدد موضع البوابة بجانب مشغّلها، قِس المشغّل أولًا. يقيسه المثال الأول في معالج النقر؛ أما للتلميح الذي يجب ألا يومض، فقِس في useLayoutEffect، الذي يعمل قبل أن يرسم المتصفح.

نوافذ منبثقة سهلة الوصول

نقل الترميز إلى document.body لا يفعل شيئًا بذاته لمستخدمي لوحة المفاتيح وقارئات الشاشة. تحتاج النافذة المنبثقة أيضًا إلى:

• role="dialog" وaria-modal="true"، مع aria-labelledby يشير إلى عنوانها.
• نقل التركيز إلى داخل الحوار عندما ينفتح (يركّز المثال على Close)، وإعادته إلى الزر الذي فتحه عندما ينغلق.
• الإغلاق بـ Escape.
• إبقاء التركيز داخله ما دام مفتوحًا، حتى لا يتجول Tab في الصفحة خلفه. ضبط السمة inert على جذر التطبيق أثناء فتح النافذة يمنع التركيز والنقرات هناك.

يتولى العنصر الأصلي <dialog> معظم هذا نيابة عنك. عند فتحه بـ dialogRef.current.showModal() يُرسم في الطبقة العليا للمتصفح فوق كل z-index، ويجعل باقي الصفحة خاملًا، وينغلق بـ Escape. لا يحتاج إلى بوابة، فهو خيار افتراضي جيد لحوارات التأكيد البسيطة؛ وتبقى البوابات الأداة المناسبة للتلميحات والقوائم والأغطية المخصصة.

لماذا لا يكفي z-index وحده

كثيرًا ما يلجأ المطورون إلى بوابة بعد أن يفشل z-index كبير في وضع قائمة فوق باقي الصفحة. والسبب سياقات التراكب. العنصر الذي له position وz-index، أو opacity أقل من 1، أو transform، أو filter، أو isolation: isolate يبدأ سياق تراكب جديدًا، ولا تتنافس قيم z-index لأبنائه إلا فيما بينها داخله. فالابن الذي له z-index: 9999 داخل بطاقة لها z-index: 1 ما زال يقع أسفل بطاقة شقيقة لها z-index: 2.

تنقل البوابة العنصر خارج كل سلف كهذا. وبصفته ابنًا لـ <body>، تُقارن قيمة z-index الخاصة به بعناصر المستوى الأعلى في الصفحة، فتكفي قيمة متواضعة مثل 1000 للأغطية.

أخطاء شائعة

إنشاء بوابة داخل عقدة لم توجد بعد. يُرجع document.getElementById('modal-root') القيمة null إذا كان العنصر مفقودًا، فترمي createPortal الخطأ "Target container is not a DOM element". تحقق من HTML، أو أنشئ البوابة داخل document.body.

إنشاء العقدة الهدف أثناء العرض. كتابة document.createElement('div') في جسم المكوّن تصنع عقدة جديدة في كل عرض. أنشئها مرة واحدة في تأثير، أو استخدم حاوية ثابتة.

نوافذ منبثقة لا تتبع مشغّلها. التلميح الذي يتحدد موضعه من getBoundingClientRect() لا يتبع مشغّله عندما تُمرَّر الصفحة أو يتغير حجمها. أعد الحساب عند scroll وresize (وأزل هذين المستمعين في دالة تنظيف التأثير)، أو أغلق التلميح عندما تُمرَّر الصفحة.