Portale w React: createPortal dla modali i tooltipów

Portal renderuje część komponentu w innym miejscu DOM, zwykle w document.body, a komponent pozostaje w tym samym miejscu drzewa Reacta. Tworzysz go przez createPortal(children, domNode) z react-dom. Dzięki portalom modale, tooltipy i menu rozwijane wydostają się z rodzica, który ma overflow: hidden albo własny kontekst stosu.

Ramka poniżej przycina wszystko, co z niej wystaje. Otwórz obie podpowiedzi.

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

Zwykła podpowiedź jest ucięta na przerywanej ramce. Podpowiedź z portalu pojawia się w całości, bo jej węzeł DOM jest dzieckiem <body>, a nie ramki. Usuń overflow: 'hidden' z ramki, a zwykła podpowiedź przestanie być przycinana.

Składnia

import { createPortal } from 'react-dom';

createPortal(children, domNode, key?)

• children to dowolny JSX: element, fragment, komponent.
• domNode to istniejący element DOM, na przykład document.body albo document.getElementById('modal-root'). Musi istnieć, gdy portal się renderuje.
• key jest opcjonalny, na wypadek gdy renderujesz listę portali.

createPortal zwraca coś, co umieszczasz w JSX jak każdy element. W pozycji DOM samego rodzica nie renderuje niczego.

Modal w document.body

Modal to klasyczny przypadek. Wewnątrz karty z transform nakładka z position: fixed jest pozycjonowana względem tej karty zamiast okna, a overflow: hidden karty ją przycina. Wyrenderowana do document.body zakrywa cały obszar widoku.

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

Otwórz modal, a potem naciśnij Escape albo kliknij ciemną nakładkę, żeby go zamknąć. Po otwarciu fokus przechodzi na przycisk Close. Teraz zwróć nakładkę bez createPortal (usuń wywołanie i jego argument document.body): nakładka kurczy się do rozmiaru karty, bo transform sprawia, że karta staje się blokiem zawierającym dla elementów fixed.

Zdarzenia propagują się przez drzewo Reacta

Portal zmienia miejsce, w którym żyje węzeł DOM, a nie miejsce, w którym żyje komponent. Zdarzenia Reacta propagują się w górę drzewa Reacta, więc kliknięcie wewnątrz portalu dociera do onClick komponentu, który go wyrenderował, choć w DOM przycisk jest dzieckiem <body>.

Natywne nasłuchiwania działają inaczej. Nasłuchiwanie dodane przez addEventListener podąża za drzewem DOM i nigdy nie widzi tego kliknięcia.

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

Kliknij "Inside the wrapper": wypisują się i handler Reacta, i natywne nasłuchiwanie. Kliknij "In a portal": wypisuje się tylko handler Reacta. Przycisk z portalu leży na ekranie poza przerywaną ramką, a jednak React wciąż traktuje go jako dziecko.

Zwykle właśnie tego chcesz: onClick na rodzicu menu widzi kliknięcia w elementy jego portalu, a providery kontekstu nad komponentem działają też wewnątrz portalu. Może cię to jednak zaskoczyć przy logice „kliknij poza, żeby zamknąć". onClick na opakowaniu, które zamyka menu, uruchamia się też dla kliknięć wewnątrz portalu menu, więc zatrzymaj propagację wewnątrz menu (e.stopPropagation(), omówione na stronie o zdarzeniach) albo użyj natywnego nasłuchiwania na document i sprawdź, czy cel jest wewnątrz węzła DOM portalu.

Portale do własnego kontenera

document.body to najprostszy cel. Niektóre aplikacje dodają do index.html osobny kontener, żeby wszystkie nakładki miały jedno miejsce i jedną kolejność stosu:

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

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

Przy renderowaniu na serwerze (Next.js i inne frameworki) document nie istnieje na serwerze. Renderuj portal dopiero po zamontowaniu komponentu, na przykład za stanem mounted, który efekt ustawia na true.

Gdy portal trzeba ustawić obok elementu, który go otwiera, najpierw zmierz ten element. Pierwszy przykład mierzy go w handlerze kliknięcia; dla tooltipa, który nie może migotać, mierz w useLayoutEffect, który uruchamia się przed odmalowaniem ekranu przez przeglądarkę.

Dostępne modale

Samo przeniesienie znaczników do document.body nic nie daje użytkownikom klawiatury i czytników ekranu. Modal potrzebuje też:

• role="dialog" i aria-modal="true", z aria-labelledby wskazującym na jego tytuł.
• Przeniesienia fokusu do okna dialogowego przy otwarciu (przykład ustawia fokus na Close) i z powrotem na przycisk, który je otworzył, przy zamknięciu.
• Zamykania klawiszem Escape.
• Utrzymania fokusu w środku, dopóki jest otwarty, żeby Tab nie przechodził na stronę w tle. Ustawienie atrybutu inert na roocie aplikacji, gdy modal jest otwarty, blokuje tam fokus i kliknięcia.

Natywny element <dialog> obsługuje większość tego za ciebie. Otwarty przez dialogRef.current.showModal() jest rysowany w górnej warstwie przeglądarki ponad każdym z-index, sprawia, że reszta strony staje się inert, i zamyka się klawiszem Escape. Nie potrzebuje portalu, więc to dobry domyślny wybór dla prostych okien potwierdzenia; portale pozostają narzędziem do tooltipów, menu i własnych nakładek.

Dlaczego sam z-index nie wystarcza

Programiści często sięgają po portal, gdy duży z-index nie umieszcza menu nad resztą strony. Powodem są konteksty stosu (stacking contexts). Element z position i z-index, opacity poniżej 1, transform, filter albo isolation: isolate tworzy nowy kontekst stosu, a wartości z-index jego dzieci konkurują tylko ze sobą w jego środku. Dziecko z z-index: 9999 wewnątrz karty z z-index: 1 nadal leży pod sąsiednią kartą z z-index: 2.

Portal wyjmuje element spod każdego takiego przodka. Jako dziecko <body> jego z-index jest porównywany z elementami najwyższego poziomu strony, więc dla nakładek wystarcza skromna wartość, taka jak 1000.

Częste błędy

Portal do węzła, który jeszcze nie istnieje. document.getElementById('modal-root') zwraca null, jeśli elementu brakuje, a createPortal rzuca "Target container is not a DOM element". Sprawdź HTML albo kieruj portal do document.body.

Tworzenie węzła docelowego podczas renderowania. Napisanie document.createElement('div') w ciele komponentu tworzy nowy węzeł przy każdym renderowaniu. Utwórz go raz w efekcie albo użyj stałego kontenera.

Wyskakujące okienka, które nie podążają za elementem otwierającym. Tooltip pozycjonowany na podstawie getBoundingClientRect() nie podąża za swoim elementem, gdy strona się przewija albo zmienia rozmiar. Przeliczaj pozycję przy scroll i resize (i usuwaj te nasłuchiwania w funkcji czyszczącej efektu) albo zamykaj tooltip, gdy strona się przewija.