Propsy w React: przekazywanie danych do komponentów

Propsy to dane wejściowe komponentu Reacta. Rodzic przekazuje je jako atrybuty w JSX, <UserCard name="Ada" online={true} />, a dziecko otrzymuje je jako jeden obiekt, który zwykle destrukturyzujesz w parametrach funkcji. Propsy pozwalają jednemu komponentowi pokazywać inne dane za każdym razem, gdy go używasz.

function UserCard({ name, role, online }) {
    return (
        <div style={{ border: '1px solid #ddd', borderRadius: 8, padding: 10, marginBottom: 8 }}>
            <strong>{name}</strong> <span style={{ color: '#666' }}>{role}</span>
            <div style={{ color: online ? 'green' : '#999' }}>
                {online ? 'Online' : 'Offline'}
            </div>
        </div>
    );
}

export default function App() {
    return (
        <div>
            <UserCard name="Ada Lovelace" role="Engineer" online={true} />
            <UserCard name="Alan Turing" role="Researcher" online={false} />
            <UserCard name="Grace Hopper" role="Admiral" online />
        </div>
    );
}

Ten sam UserCard renderuje trzy różne osoby. Zwróć uwagę na ostatnią: atrybut bez wartości, online, oznacza online={true}. Dodaj czwartą kartę z własnym imieniem i rolą.

Przekazywanie i odczytywanie propsów

Tekst przekazuj w cudzysłowie, a każdą inną wartość w nawiasach klamrowych: liczby, wartości logiczne, tablice, obiekty, funkcje, nawet JSX.

<Product
    title="Desk lamp"
    price={39.5}
    inStock={false}
    tags={['light', 'office']}
    seller={{ name: 'Lumen', rating: 4.8 }}
/>

React zbiera wszystkie atrybuty w jeden obiekt i przekazuje go jako pierwszy argument komponentu. Możesz go odczytać jako props albo rozpakować potrzebne pola od razu w liście parametrów:

function Product(props) {
    return <h3>{props.title}</h3>;
}

function Product({ title, price, seller }) {
    return <h3>{title}, ${price} from {seller.name}</h3>;
}

Obie wersje dostają ten sam obiekt. Destrukturyzacja to popularny styl, bo sygnatura funkcji wymienia wtedy dokładnie, których propsów komponent używa.

Wartości domyślne

Nadaj propsowi wartość domyślną przez domyślną wartość destrukturyzacji JavaScriptu, = value. Działa ona, gdy rodzic pominie prop albo przekaże undefined. Nie działa dla null, 0, false ani '', które są prawdziwymi wartościami.

function Button({ label = 'Click me', size = 'medium', color = '#2563eb' }) {
    const padding = { small: '2px 8px', medium: '6px 14px', large: '10px 20px' }[size];
    return (
        <button style={{ padding, background: color, color: 'white', border: 0, borderRadius: 6, margin: 4 }}>
            {label} ({String(size)})
        </button>
    );
}

export default function App() {
    return (
        <div>
            <Button />
            <Button label="Save" size="large" />
            <Button label="Undefined" size={undefined} />
            <Button label="Null" size={null} />
        </div>
    );
}

Pierwsze trzy przyciski wracają do wartości domyślnych tam, gdzie propsa brakuje albo jest undefined. Ostatni przekazuje null, więc size naprawdę jest null, a wyszukiwanie nie znajduje żadnego paddingu. Zmień size={null} na size="small", żeby to naprawić.

Starszy kod ustawia wartości domyślne przez statyczną właściwość, Button.defaultProps = { size: 'medium' }. React 19 usunął defaultProps dla komponentów funkcyjnych: JSX ignoruje go na funkcji, bez ostrzeżenia. Na komponentach klasowych nadal działa. Używaj wartości domyślnych w destrukturyzacji.

Przekazywanie funkcji jako propsów

Dane płyną w dół: rodzic przekazuje propsy dzieciom, nigdy odwrotnie. Gdy dziecko musi powiedzieć rodzicowi, że coś się stało, rodzic przekazuje funkcję, a dziecko ją wywołuje. Zgodnie z konwencją takie propsy nazywa się onSomething.

import { useState } from 'react';

function Rating({ value, onRate }) {
    return (
        <div>
            {[1, 2, 3, 4, 5].map((n) => (
                <button key={n} onClick={() => onRate(n)} style={{ fontWeight: n === value ? 'bold' : 'normal' }}>
                    {n}
                </button>
            ))}
        </div>
    );
}

export default function App() {
    const [rating, setRating] = useState(0);

    function handleRate(n) {
        console.log('Rating picked a value:', n);
        setRating(n);
    }

    return (
        <div>
            <Rating value={rating} onRate={handleRate} />
            <p>{rating === 0 ? 'Not rated yet' : `You rated it ${rating} out of 5`}</p>
        </div>
    );
}

Rating niczego nie przechowuje. Pokazuje value, które otrzymuje, i zgłasza kliknięcia przez onRate. Stan znajduje się w App, który przekazuje go z powrotem w dół. Przekaż bezpośrednio onRate={setRating} zamiast handleRate, a nadal będzie działać: setter też jest funkcją. Takie przenoszenie stanu do wspólnego rodzica nazywa się podnoszeniem stanu.

Rozpakowywanie propsów (spread)

Gdy masz już obiekt, którego klucze pasują do propsów komponentu, rozpakuj go przez {...object}, zamiast pisać każdy atrybut. Składnia rest robi odwrotną rzecz w liście parametrów: weź kilka propsów po nazwie, zbierz całą resztę i przekaż ją dalej.

function Avatar({ name, color, size }) {
    return (
        <span
            style={{ display: 'inline-grid', placeItems: 'center', width: size, height: size, borderRadius: '50%', background: color, marginInlineEnd: 6 }}
        >
            {name[0]}
        </span>
    );
}

function TextField({ label, ...inputProps }) {
    return (
        <label style={{ display: 'block', marginTop: 10 }}>
            {label} <input {...inputProps} />
        </label>
    );
}

export default function App() {
    const person = { name: 'Ada', color: '#fde68a', size: 40 };

    return (
        <div>
            <Avatar {...person} />
            <Avatar {...person} color="#bbf7d0" />
            <TextField label="Email" type="email" placeholder="you@example.com" maxLength={40} />
        </div>
    );
}

Drugi awatar rozpakowuje person, a potem ustawia color: gdy ten sam prop pojawia się dwa razy, wygrywa późniejszy, więc nadpisania umieszczaj po spreadzie. TextField zatrzymuje label dla siebie i przekazuje type, placeholder i maxLength prosto do <input>. Używaj spreadu w takich opakowaniach; w innych miejscach jawne wypisanie propsów ułatwia zobaczenie, co komponent dostaje.

Propsy są tylko do odczytu

Komponent nigdy nie może zmieniać własnych propsów. Należą one do rodzica, a ten sam obiekt może być współdzielony. Traktuj je jak argumenty funkcji, których nie wolno ci nadpisywać:

function Counter({ count }) {
    count = count + 1; // wrong: changes a local copy, the parent never sees it
    return <p>{count}</p>;
}

function Profile(props) {
    props.name = 'Someone else'; // wrong: in development React freezes props, so this throws a TypeError
    return <p>{props.name}</p>;
}

Propsy mimo to zmieniają się w czasie. Gdy rodzic renderuje się ponownie z nowymi wartościami, dziecko dostaje nowy obiekt propsów i renderuje się z nim:

import { useState } from 'react';

function Temperature({ celsius }) {
    const fahrenheit = (celsius * 9) / 5 + 32;
    return (
        <p>
            {celsius}°C is {fahrenheit}°F, {celsius >= 25 ? 'warm' : 'cool'}.
        </p>
    );
}

export default function App() {
    const [celsius, setCelsius] = useState(20);

    return (
        <div>
            <input type="range" min={-10} max={40} value={celsius} onChange={(e) => setCelsius(Number(e.target.value))} />
            <Temperature celsius={celsius} />
            <button onClick={() => setCelsius(celsius + 5)}>Warmer</button>
        </div>
    );
}

Temperature nigdy nie zmienia celsius. Wylicza z niego fahrenheit przy każdym renderowaniu. Przesuń suwak, a zmieni się stan rodzica, więc dziecko dostanie nowy prop. Jeśli dziecko potrzebuje wartości, którą może zmieniać samo, ta wartość jest stanem, a nie propsem.

Propsy a stan

Propsy i stan to zwykłe wartości JavaScript, które wpływają na to, co renderuje komponent, a zmiana któregokolwiek z nich renderuje komponent ponownie. Różnica polega na tym, kto jest właścicielem wartości.

Ta sama wartość jest często jednym i drugim. W przykładzie z temperaturą powyżej celsius jest stanem w App i propsem w Temperature. Właściciel trzyma ją jako stan i przekazuje w dół jako prop, razem z funkcją do jej zmiany, gdy dziecko jej potrzebuje.

Prop może przechowywać dowolną wartość, w tym JSX i komponenty. Przekazanie elementu, na przykład icon={<StarIcon />}, pozwala rodzicowi wypełnić miejsce w dziecku; to ten sam pomysł co children, tylko z nazwą, którą sam wybierasz.

Prop children

Cokolwiek umieścisz między tagiem otwierającym i zamykającym komponentu, trafia do niego jako prop o nazwie children. Tak buduje się opakowania, takie jak karty, panele i układy, które nie znają z góry swojej zawartości:

function Panel({ title, children }) {
    return (
        <section style={{ border: '1px solid #ddd', borderRadius: 8, padding: 12, marginBottom: 8 }}>
            <h4 style={{ margin: '0 0 8px' }}>{title}</h4>
            {children}
        </section>
    );
}

export default function App() {
    return (
        <div>
            <Panel title="About">
                <p>Panels can hold any JSX.</p>
            </Panel>
            <Panel title="Links">
                <ul>
                    <li>Props</li>
                    <li>State</li>
                </ul>
            </Panel>
        </div>
    );
}

Strona o children omawia przekazywanie kilku slotów i bezpieczną pracę z children.

Klucze to nie propsy

key wygląda jak atrybut, ale React zatrzymuje go dla siebie, żeby dopasowywać elementy listy między renderowaniami. Komponent nigdy go nie dostaje:

function Row(props) {
    console.log('Row props.key =', String(props.key), 'props.id =', props.id);
    return <li>{props.label}</li>;
}

export default function App() {
    const fruits = [
        { id: 'a1', label: 'Apple' },
        { id: 'b2', label: 'Banana' },
    ];

    return (
        <ul>
            {fruits.map((fruit) => (
                <Row key={fruit.id} id={fruit.id} label={fruit.label} />
            ))}
        </ul>
    );
}

Konsola pokazuje props.key jako undefined, a props.id z prawdziwą wartością. Gdy dziecko potrzebuje identyfikatora, przekaż go drugi raz pod inną nazwą, tak jak robi to tutaj id. Build deweloperski ostrzega też, gdy odczytujesz props.key; podgląd działa jak build produkcyjny, więc widzisz tylko undefined.