Kurs JavaScript i React · Moduł 10: Ekosystem i przyszłość React

React 19 - Nowy sposób przekazywania ref (bez forwardRef)

5 min czytania ·
W tej lekcji6

Panel nawigacyjny chce ustawić fokus na polu współrzędnych ukrytym w komponencie potomnym. ref daje właśnie taki bezpośredni dostęp do elementu DOM, ale przypięty do własnego komponentu przez lata nie docierał do środka: React traktował go specjalnie i nie przekazywał w propsach. Trzeba było owijać komponent w forwardRef, jak w dodatkowy przekaźnik sygnału. W React 19 ta długo oczekiwana zmiana wreszcie nadeszła, podobnie jak nowe systemy komunikacji na statkach eliminują skomplikowane przekaźniki.

Stary sposób z forwardRef (React 18 i wcześniej)

W poprzednich wersjach Reacta, żeby przekazać ref do komponentu potomnego, trzeba było użyć forwardRef. Funkcja komponentu dostawała ref jako drugi argument, obok propsów:

import { forwardRef, useRef } from 'react';

// Stary sposób - wymaga forwardRef
const SpaceshipButton = forwardRef((props, ref) => {
  return (
    <button ref={ref} className="spaceship-btn" {...props}>
      {props.children}
    </button>
  );
});

// Użycie
function MissionControl() {
  const buttonRef = useRef(null);

  const focusButton = () => {
    buttonRef.current?.focus();
  };

  return (
    <div>
      <SpaceshipButton ref={buttonRef}>
        Uruchom silniki
      </SpaceshipButton>
      <button onClick={focusButton}>Fokus na przycisk</button>
    </div>
  );
}

MissionControl tworzy buttonRef przez useRef i po kliknięciu wywołuje focus() na prawdziwym przycisku. Działa, ale komponent ma nietypową sygnaturę (props, ref) i dodatkowe opakowanie, o którym trzeba pamiętać przy każdym takim komponencie.

Nowy sposób w React 19 - ref jako prop

W React 19 ref jest zwykłym propem komponentu funkcyjnego. Wyciągasz go z propsów jak każdą inną wartość:

import { useRef } from 'react';

// Nowy sposób w React 19 - ref to po prostu prop!
function SpaceshipButton({ ref, children, ...props }) {
  return (
    <button ref={ref} className="spaceship-btn" {...props}>
      {children}
    </button>
  );
}

// Użycie - dokładnie tak samo!
function MissionControl() {
  const buttonRef = useRef(null);

  const focusButton = () => {
    buttonRef.current?.focus();
  };

  return (
    <div>
      <SpaceshipButton ref={buttonRef}>
        Uruchom silniki
      </SpaceshipButton>
      <button onClick={focusButton}>Fokus na przycisk</button>
    </div>
  );
}

Zmieniła się tylko definicja: znika forwardRef, a ref trafia do destrukturyzacji obok children. Użycie w MissionControl jest dokładnie takie samo. Zasada dotyczy komponentów funkcyjnych, bo w klasowych ref nadal wskazuje instancję i nie trafia do propsów.

Praktyczne przykłady

1. Input z auto-focus

Formularz współrzędnych pokazuje, jak ref ułatwia nawigację klawiaturą. Każdy CoordinateInput przekazuje ref prosto do elementu input:

// React 19 - prosty komponent inputa
function CoordinateInput({ ref, label, ...props }) {
  return (
    <div className="coordinate-field">
      <label>{label}</label>
      <input ref={ref} {...props} />
    </div>
  );
}

function NavigationPanel() {
  const latitudeRef = useRef(null);
  const longitudeRef = useRef(null);

  useEffect(() => {
    // Auto-focus na pierwszy input
    latitudeRef.current?.focus();
  }, []);

  const handleLatitudeEnter = (e) => {
    if (e.key === 'Enter') {
      longitudeRef.current?.focus();
    }
  };

  return (
    <form className="nav-panel">
      <h2>Wprowadź współrzędne docelowe</h2>

      <CoordinateInput
        ref={latitudeRef}
        label="Szerokość galaktyczna"
        onKeyDown={handleLatitudeEnter}
      />

      <CoordinateInput
        ref={longitudeRef}
        label="Długość galaktyczna"
      />

      <button type="submit">Ustaw kurs</button>
    </form>
  );
}

Po zamontowaniu efekt ustawia fokus na polu szerokości, a Enter przenosi go do długości. CoordinateInput pozostaje zwykłą funkcją bez opakowania, a pozostałe propsy, jak onKeyDown, trafiają do inputa przez ...props.

useImperativeHandle - nadal użyteczny

Czasem nie chcesz oddawać rodzicowi całego elementu DOM, tylko wybrane polecenia. useImperativeHandle nadal działa, ale teraz bez forwardRef: podajesz mu ref odebrany z propsów:

import { useImperativeHandle, useRef } from 'react';

function VideoPlayer({ ref, src }) {
  const videoRef = useRef(null);

  // Eksponuj tylko wybrane metody
  useImperativeHandle(ref, () => ({
    play: () => videoRef.current?.play(),
    pause: () => videoRef.current?.pause(),
    seek: (time) => {
      if (videoRef.current) {
        videoRef.current.currentTime = time;
      }
    },
    getCurrentTime: () => videoRef.current?.currentTime || 0,
  }), []);

  return (
    <video ref={videoRef} src={src} className="space-video">
      Twoja przeglądarka nie obsługuje wideo.
    </video>
  );
}

function MediaController() {
  const playerRef = useRef(null);

  return (
    <div>
      <VideoPlayer ref={playerRef} src="/space-documentary.mp4" />

      <div className="controls">
        <button onClick={() => playerRef.current?.play()}>
          Odtwórz
        </button>
        <button onClick={() => playerRef.current?.pause()}>
          Pauza
        </button>
        <button onClick={() => playerRef.current?.seek(0)}>
          Od początku
        </button>
      </div>
    </div>
  );
}

Rodzic widzi tylko play, pause, seek i getCurrentTime, a nie cały element video. To bezpieczniejsze API, bo nikt z zewnątrz nie zmieni przypadkiem atrybutów odtwarzacza.

Migracja z forwardRef

Jeśli masz kod z forwardRef, migracja jest prosta: przenosisz ref z drugiego argumentu do propsów:

// Przed (React 18)
const OldComponent = forwardRef(function OldComponent(props, ref) {
  return <div ref={ref}>{props.children}</div>;
});

// Po (React 19)
function NewComponent({ ref, children }) {
  return <div ref={ref}>{children}</div>;
}

// Użycie pozostaje identyczne!
function Panel() {
  const oldRef = useRef(null);
  const newRef = useRef(null);

  return (
    <>
      <OldComponent ref={oldRef}>Stary</OldComponent>
      <NewComponent ref={newRef}>Nowy</NewComponent>
    </>
  );
}

Miejsca użycia się nie zmieniają, więc możesz migrować komponent po komponencie. Nie musisz się też spieszyć: forwardRef w React 19 nadal działa i nie jest jeszcze oznaczony jako przestarzały (deprecated), dokumentacja zapowiada to dopiero w przyszłej wersji.

Podsumowanie

React 19 wprowadza znaczące uproszczenie w przekazywaniu referencji:

  1. ref jest zwykłym propem - w komponentach funkcyjnych nie wymaga specjalnego traktowania
  2. forwardRef nie jest już potrzebny - nadal działa, a dokumentacja zapowiada, że w przyszłej wersji zostanie oznaczony jako przestarzały (deprecated)
  3. useImperativeHandle działa bez forwardRef - przekaż ref jako prop
  4. Callback refs działają jak dawniej - a od React 19 mogą też zwrócić funkcję sprzątającą, którą React wywoła przy odłączeniu elementu
  5. TypeScript - ref opisujesz w typie propsów jak każdy inny prop, np. React.Ref<HTMLInputElement>

W nowym kodzie polecam Ci od razu pisać komponenty z ref w propsach, a stary kod migrować przy okazji innych zmian. Przyda się to w każdej bibliotece komponentów, bo przyciski i pola muszą udostępniać ref do fokusu i pomiarów. To uproszczenie sprawia, że komponenty są bardziej przewidywalne i łatwiejsze do zrozumienia.

Pamiętaj: w React 19 ref to zwykły kanał łączności między modułami - podłączasz go jak każdy inny prop, bez dodatkowego przekaźnika. W przykładzie poniżej stary przycisk z forwardRef i nowe komponenty z ref w propsach działają obok siebie, a okno dialogowe udostępnia rodzicowi metody przez useImperativeHandle.

Kod do tej lekcji: App.jsx
import { forwardRef, useImperativeHandle, useRef, useState } from 'react';

// React 19: ref jest zwykłym propem komponentu funkcyjnego.
// forwardRef nadal działa, ale nie jest już potrzebny.

// Stary sposób (React 18) - wciąż działa w React 19
const OldSpaceButton = forwardRef(function OldSpaceButton(props, ref) {
  return <button ref={ref} style={{ ...styles.button, background: '#778da9' }} {...props} />;
});

// Nowy sposób w React 19 - ref wyciągasz z propsów jak każdą inną wartość
function SpaceButton({ ref, children, variant = 'primary', ...props }) {
  const colors = {
    primary: { background: '#00d4ff', color: '#0a0e27' },
    danger: { background: '#ff6b6b', color: '#fff' },
    success: { background: '#00ff88', color: '#0a0e27' },
  };

  return (
    <button ref={ref} style={{ ...styles.button, ...(colors[variant] || colors.primary) }} {...props}>
      {children}
    </button>
  );
}

function SpaceInput({ ref, label, ...props }) {
  return (
    <label style={styles.field}>
      <span style={styles.label}>{label}</span>
      <input ref={ref} style={styles.input} {...props} />
    </label>
  );
}

// useImperativeHandle z ref z propsów: rodzic dostaje tylko open, close i toggle
function SpaceDialog({ ref, title, children }) {
  const [isOpen, setIsOpen] = useState(false);

  useImperativeHandle(ref, () => ({
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    toggle: () => setIsOpen(prev => !prev),
  }), []);

  if (!isOpen) return null;

  return (
    <div style={styles.overlay}>
      <div style={styles.dialog}>
        <h3 style={{ color: '#00d4ff', margin: '0 0 12px' }}>{title}</h3>
        {children}
        <button onClick={() => setIsOpen(false)} style={styles.closeButton}>Zamknij</button>
      </div>
    </div>
  );
}

export default function App() {
  const buttonRef = useRef(null);
  const oldButtonRef = useRef(null);
  const inputRef = useRef(null);
  const dialogRef = useRef(null);
  const [log, setLog] = useState([]);

  const addLog = message => setLog(prev => [message, ...prev].slice(0, 6));

  return (
    <div style={styles.page}>
      <div style={{ maxWidth: '600px', margin: '0 auto' }}>
        <h1 style={styles.title}>React 19: ref jako prop</h1>
        <p style={styles.subtitle}>forwardRef nie jest już potrzebny, choć nadal działa</p>

        <section style={styles.card}>
          <h3 style={styles.cardTitle}>Przycisk z ref w propsach</h3>
          <div style={styles.row}>
            <SpaceButton ref={buttonRef} onClick={() => addLog('Kliknięto przycisk z ref')}>
              Uruchom silniki
            </SpaceButton>
            <SpaceButton variant="success" onClick={() => { buttonRef.current?.focus(); addLog('Fokus na przycisku (nowy sposób)'); }}>
              Ustaw fokus
            </SpaceButton>
          </div>
        </section>

        <section style={styles.card}>
          <h3 style={styles.cardTitle}>Stary przycisk z forwardRef</h3>
          <div style={styles.row}>
            <OldSpaceButton ref={oldButtonRef} onClick={() => addLog('Kliknięto stary przycisk')}>
              Stary przekaźnik
            </OldSpaceButton>
            <SpaceButton variant="success" onClick={() => { oldButtonRef.current?.focus(); addLog('Fokus na przycisku (forwardRef)'); }}>
              Ustaw fokus
            </SpaceButton>
          </div>
        </section>

        <section style={styles.card}>
          <h3 style={styles.cardTitle}>Pole tekstowe z ref w propsach</h3>
          <SpaceInput ref={inputRef} label="Nazwa misji" placeholder="Wpisz nazwę..." />
          <SpaceButton onClick={() => { inputRef.current?.focus(); addLog('Fokus na polu tekstowym'); }}>
            Ustaw fokus na polu
          </SpaceButton>
        </section>

        <section style={styles.card}>
          <h3 style={styles.cardTitle}>Okno dialogowe z useImperativeHandle</h3>
          <div style={styles.row}>
            <SpaceButton onClick={() => { dialogRef.current?.open(); addLog('Otwarto okno'); }}>Otwórz okno</SpaceButton>
            <SpaceButton variant="danger" onClick={() => { dialogRef.current?.close(); addLog('Zamknięto okno'); }}>Zamknij okno</SpaceButton>
          </div>
        </section>

        <SpaceDialog ref={dialogRef} title="Komunikat z mostka">
          <p style={{ margin: 0 }}>To okno udostępnia rodzicowi tylko metody open, close i toggle przez useImperativeHandle.</p>
        </SpaceDialog>

        <section style={styles.card}>
          <h3 style={styles.cardTitle}>Dziennik zdarzeń</h3>
          {log.length === 0 ? (
            <p style={styles.muted}>Kliknij przyciski powyżej...</p>
          ) : (
            log.map((entry, i) => <div key={i} style={styles.logRow}>{entry}</div>)
          )}
        </section>
      </div>
    </div>
  );
}

const styles = {
  page: { minHeight: '100vh', background: 'linear-gradient(135deg, #0a0e27 0%, #1a1a3e 100%)', padding: '24px', color: '#e0e1dd', fontFamily: 'system-ui, sans-serif' },
  title: { textAlign: 'center', color: '#00d4ff', margin: '0 0 6px' },
  subtitle: { textAlign: 'center', color: '#8892b0', margin: '0 0 18px', fontSize: '14px' },
  card: { background: 'rgba(0,0,0,0.3)', padding: '16px', borderRadius: '12px', marginBottom: '12px' },
  cardTitle: { color: '#64ffda', margin: '0 0 10px', fontSize: '15px' },
  row: { display: 'flex', gap: '8px', flexWrap: 'wrap' },
  button: { padding: '9px 16px', border: 'none', borderRadius: '8px', cursor: 'pointer', fontWeight: 'bold', fontSize: '14px', color: '#0a0e27' },
  field: { display: 'block', marginBottom: '10px' },
  label: { display: 'block', color: '#8892b0', fontSize: '13px', marginBottom: '4px' },
  input: { width: '100%', boxSizing: 'border-box', padding: '9px 12px', background: 'rgba(255,255,255,0.08)', border: '1px solid rgba(0,212,255,0.3)', borderRadius: '8px', color: '#e0e1dd', fontSize: '14px' },
  overlay: { position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.7)', display: 'flex', alignItems: 'center', justifyContent: 'center', zIndex: 1000 },
  dialog: { background: '#1a1a3e', padding: '24px', borderRadius: '12px', border: '1px solid rgba(0,212,255,0.3)', maxWidth: '400px', width: '90%' },
  closeButton: { marginTop: '16px', padding: '8px 16px', background: 'rgba(255,255,255,0.1)', color: '#e0e1dd', border: '1px solid rgba(255,255,255,0.2)', borderRadius: '6px', cursor: 'pointer' },
  muted: { color: '#8892b0', fontSize: '13px', margin: 0 },
  logRow: { fontSize: '12px', color: '#8892b0', padding: '2px 0', fontFamily: 'monospace' },
};

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jak przekazać ref do komponentu funkcyjnego w React 19?

  2. 2. Jaki jest status forwardRef w React 19?

Zadania praktyczne w grze

  • Klikanie w kolejności

    Ułóż nowy sposób definiowania komponentu z ref w React 19:

  1. Pytanieref jako prop w React 19
  2. Kliknij w kolejnościMigracja z forwardRef do React 19
  3. PytanieStatus forwardRef w React 19

Przydatne artykuły