React Portal'ları: Modal ve Tooltip için createPortal

Bir portal, bir bileşenin bir kısmını DOM'da farklı bir yere, genellikle document.body'ye render eder; bileşen ise React ağacında aynı yerde kalır. react-dom'dan createPortal(children, domNode) ile bir tane oluşturursun. Portal'lar, modalların, tooltip'lerin ve açılır menülerin overflow: hidden'lı ya da kendi katmanlama bağlamı olan bir ebeveynden kaçma yoludur.

Aşağıdaki kutu dışına taşan her şeyi kırpar. İki ipucunu da aç.

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>
    );
}

Normal ipucu kesik çizgili kenarlıkta kesilir. Portal ipucu tam olarak görünür, çünkü DOM düğümü kutunun değil <body>'nin bir çocuğudur. Kutudan overflow: 'hidden''ı sil; normal ipucu artık kırpılmaz.

Sözdizimi

import { createPortal } from 'react-dom';

createPortal(children, domNode, key?)

• children herhangi bir JSX'tir: bir öğe, bir fragment, bir bileşen.
• domNode, document.body ya da document.getElementById('modal-root') gibi mevcut bir DOM öğesidir. Portal render olduğunda var olmalıdır.
• key isteğe bağlıdır; bir portal listesi render ettiğinde kullanılır.

createPortal, JSX'ine diğer her öğe gibi koyduğun bir şey döndürür. Ebeveynin kendi DOM konumunda hiçbir şey render etmez.

document.body içinde bir modal

Modal klasik örnektir. transform'lu bir kartın içinde, position: fixed bir katman pencereye değil o karta göre konumlanır ve kartın overflow: hidden'ı da onu kırpar. document.body içine render edildiğinde tüm görünümü kaplar.

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>
    );
}

Modalı aç, sonra kapatmak için Escape'e bas ya da karanlık katmana tıkla. Açıldığında odak Close düğmesine geçer. Şimdi katmanı createPortal olmadan döndür (çağrıyı ve document.body argümanını kaldır): katman kartın boyutuna küçülür, çünkü transform kartı sabit öğeler için kapsayıcı blok yapar.

Olaylar React ağacı boyunca kabarcıklanır

Bir portal, bileşenin nerede yaşadığını değil, DOM düğümünün nerede yaşadığını değiştirir. React olayları React ağacı boyunca yukarı kabarcıklanır, bu yüzden bir portal içindeki tıklama, DOM'da düğme <body>'nin bir çocuğu olsa bile onu render eden bileşenin onClick'ine ulaşır.

Yerel dinleyiciler farklıdır. addEventListener ile eklenen bir dinleyici DOM ağacını izler ve tıklamayı asla görmez.

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"a tıkla: hem React işleyicisi hem yerel dinleyici kayıt yazar. "In a portal"a tıkla: yalnızca React işleyicisi kayıt yazar. Portal düğmesi ekranda kesik çizgili sarmalayıcının dışında durur, ama React onu yine de bir çocuk olarak ele alır.

Genellikle istediğin budur: bir menünün ebeveynindeki onClick portal öğelerindeki tıklamaları görür ve bileşenin üstündeki context provider'ları portal içinde de geçerlidir. "Dışarı tıklayınca kapat" mantığında seni şaşırtabilir. Bir menüyü kapatan bir sarmalayıcıdaki onClick, menünün portal'ı içindeki tıklamalar için de tetiklenir; bu yüzden menünün içinde yayılımı durdur (e.stopPropagation(), olaylar sayfasında anlatılıyor) ya da yerel bir document dinleyicisi kullanıp hedefin portal'ın DOM düğümünün içinde olup olmadığını kontrol et.

Kendi kapsayıcına portal'lar

document.body en basit hedeftir. Bazı uygulamalar tüm katmanların tek bir yeri ve tek bir katman sırasını paylaşması için index.html'e özel bir kapsayıcı ekler:

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

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

Sunucu tarafı render ile (Next.js ve diğer framework'ler) document sunucuda yoktur. Portal'ı yalnızca bileşen mount olduktan sonra render et; örneğin bir efektin true yaptığı bir mounted state'inin arkasında.

Portal'ın tetikleyicisinin yanında konumlanması gerektiğinde önce tetikleyiciyi ölç. İlk örnek onu tıklama işleyicisinde ölçer; titrememesi gereken bir tooltip için tarayıcı boyamadan önce çalışan useLayoutEffect içinde ölç.

Erişilebilir modallar

İşaretlemeyi document.body'ye taşımak tek başına klavye ve ekran okuyucu kullanıcıları için hiçbir şey yapmaz. Bir modalın ayrıca şunlara ihtiyacı vardır:

• role="dialog" ve aria-modal="true", başlığını gösteren aria-labelledby ile.
• Açıldığında odağın diyaloğa taşınması (örnek Close'a odaklanır) ve kapandığında onu açan düğmeye geri dönmesi.
• Kapatmak için Escape.
• Açıkken odağın içeride tutulması, böylece Tab arkadaki sayfaya geçmez. Modal açıkken uygulama köküne inert özelliğini ayarlamak oradaki odağı ve tıklamaları engeller.

Yerel <dialog> öğesi bunun çoğunu senin için halleder. dialogRef.current.showModal() ile açıldığında tarayıcının üst katmanında, her z-index'in üstünde çizilir, sayfanın geri kalanını inert yapar ve Escape ile kapanır. Portal'a ihtiyaç duymaz, bu yüzden basit onay diyalogları için iyi bir varsayılandır; portal'lar ise tooltip'ler, menüler ve özel katmanlar için araç olmaya devam eder.

Neden tek başına z-index yetmez

Geliştiriciler, büyük bir z-index bir menüyü sayfanın geri kalanının üstüne koymakta başarısız olduktan sonra çoğu zaman bir portal'a başvurur. Nedeni katmanlama bağlamlarıdır (stacking context). position ve bir z-index'i olan, opacity'si 1'in altında olan, bir transform, bir filter ya da isolation: isolate içeren bir öğe yeni bir katmanlama bağlamı başlatır ve çocuklarının z-index değerleri yalnızca onun içinde birbiriyle yarışır. z-index: 1 olan bir kartın içindeki z-index: 9999'lu bir çocuk, z-index: 2 olan kardeş bir kartın yine altında durur.

Bir portal öğeyi bu tür her atadan çıkarır. <body>'nin bir çocuğu olarak z-index'i sayfanın en üst düzey öğeleriyle karşılaştırılır, bu yüzden katmanlar için 1000 gibi mütevazı bir değer yeterlidir.

Yaygın hatalar

Henüz var olmayan bir düğüme portal yapmak. Öğe eksikse document.getElementById('modal-root') null döndürür ve createPortal "Target container is not a DOM element" hatası fırlatır. HTML'i kontrol et ya da document.body'ye portal yap.

Hedef düğümü render sırasında oluşturmak. Bileşen gövdesine document.createElement('div') yazmak her render'da yeni bir düğüm oluşturur. Onu bir efektte bir kez oluştur ya da sabit bir kapsayıcı kullan.

Tetikleyicisini takip etmeyen açılır pencereler. getBoundingClientRect()'ten konumlandırılan bir tooltip, sayfa kaydırıldığında ya da yeniden boyutlandırıldığında tetikleyicisini takip etmez. scroll ve resize'da yeniden hesapla (ve bu dinleyicileri efektin temizlemesinde kaldır) ya da sayfa kaydırıldığında tooltip'i kapat.