Kurs JavaScript i React · Moduł 12: React i TypeScript

Typowanie Props - Interfejsy i Właściwości Opcjonalne

5 min czytania ·
W tej lekcji5

Komponent karty członka załogi działa świetnie, dopóki ktoś nie zapomni przekazać rangi albo nie poda doświadczenia jako tekstu "piętnaście". Props to kosmiczna komunikacja między komponentami. TypeScript pozwala Ci dokładnie określić, jakie dane mogą być przesyłane - to jak protokół komunikacyjny na statku kosmicznym: wiadomość niezgodna z protokołem nie zostanie nawet wysłana.

Interfejsy dla props

Interfejsy to najczęstszy sposób definiowania typów props w React. Nazwa interfejsu zwykle kończy się słowem Props, a każde pole odpowiada jednemu atrybutowi, który rodzic przekazuje w JSX. Najpierw sam protokół:

// Interfejs definiuje "kształt" danych
interface CrewMemberProps {
  name: string;
  rank: string;
  experience: number;
  specialization: string;
}

Teraz podpinamy go pod parametr komponentu, tak jak w poprzedniej lekcji, i pokazujemy użycie:

function CrewMember({ name, rank, experience, specialization }: CrewMemberProps) {
  return (
    <div>
      <h3>{name}</h3>
      <p>Ranga: {rank}</p>
      <p>Lata doświadczenia: {experience}</p>
      <p>Specjalizacja: {specialization}</p>
    </div>
  );
}

// Użycie - TypeScript sprawdzi wszystkie props
<CrewMember
  name="Nova"
  rank="Kapitan"
  experience={15}
  specialization="Nawigacja"
/>

Zwróć uwagę na experience={15}: liczby przekazujemy w klamrach, a tekst w cudzysłowie. Gdybyś pominął rank albo napisał experience="15", edytor podkreśli błąd jeszcze przed uruchomieniem. Samo wywołanie w JSX wygląda tak samo jak w JavaScript - protokół działa w tle.

Props opcjonalne

Nie wszystkie props są wymagane. Użyj znaku ? po nazwie pola, aby oznaczyć props jako opcjonalny. Typ takiego pola to w praktyce "wartość albo undefined". W przykładzie pojawia się też union type, czyli typ złożony z kilku dozwolonych wartości połączonych znakiem |, oraz Date - wbudowany typ daty.

interface MissionProps {
  title: string;          // wymagany
  description: string;    // wymagany
  priority?: "low" | "medium" | "high";  // opcjonalny
  deadline?: Date;        // opcjonalny
  assignedCrew?: string[]; // opcjonalny
}

Pole priority przyjmie tylko jeden z trzech napisów - literówka "hihg" zostanie odrzucona. Jak nadać wartość domyślną? Najprościej w destrukturyzacji parametru, znakiem =:

function MissionCard({ title, description, priority = "medium", deadline, assignedCrew }: MissionProps) {
  return (
    <div>
      <h3>{title}</h3>
      <p>{description}</p>
      <span>Priorytet: {priority}</span>
      {deadline && <p>Termin: {deadline.toLocaleDateString()}</p>}
      {assignedCrew && (
        <ul>
          {assignedCrew.map(member => <li key={member}>{member}</li>)}
        </ul>
      )}
    </div>
  );
}

Wewnątrz komponentu priority ma już typ bez undefined, bo wartość domyślna wypełnia lukę. Pola deadline i assignedCrew mogą być puste, dlatego sprawdzamy je operatorem &&, zanim wywołamy na nich metodę - TypeScript by na to nie pozwolił bez sprawdzenia. Uwaga dla czytelników starszych poradników: defaultProps dla komponentów funkcyjnych zostało usunięte w React 19, więc wartości domyślne ustawiaj wyłącznie w destrukturyzacji.

Oba poniższe wywołania są poprawne:

// Można użyć bez opcjonalnych props
<MissionCard title="Zwiad" description="Rozpoznanie sektora 7" />

// Lub ze wszystkimi
<MissionCard
  title="Zwiad"
  description="Rozpoznanie sektora 7"
  priority="high"
  assignedCrew={["Nova", "Ra"]}
/>

Pominięcie title lub description byłoby błędem, ale pola opcjonalne możesz dodawać w dowolnej kombinacji.

Typowanie children

Props children to specjalny props w React: trafia do niego wszystko, co wpiszesz między znacznik otwierający a zamykający komponentu. Typ React.ReactNode obejmuje wszystko, co React potrafi wyrenderować: elementy JSX, tekst, liczby, null i tablice tych wartości.

// React.ReactNode - przyjmuje wszystko co React może renderować
interface PanelProps {
  title: string;
  children: React.ReactNode;
}

function Panel({ title, children }: PanelProps) {
  return (
    <div className="panel">
      <h2>{title}</h2>
      <div className="content">{children}</div>
    </div>
  );
}

// Użycie
<Panel title="Dane Misji">
  <p>Status: aktywna</p>
  <MissionCard title="Zwiad" description="..." />
</Panel>

Panel nie wie, co dostanie w środku, i nie musi - przyjmie akapit, inną kartę albo zwykły tekst. Gdybyś chciał przyjmować wyłącznie elementy JSX, react.dev wskazuje węższy typ React.ReactElement, ale do paneli i kontenerów React.ReactNode jest właściwym wyborem.

Typ vs Interfejs

Możesz użyć również type zamiast interface. Słowo type tworzy alias, czyli nową nazwę dla dowolnego typu - także dla union type, czego interfejs nie potrafi.

// Type alias - alternatywa dla interface
type ButtonVariant = "primary" | "secondary" | "danger";

type ButtonProps = {
  label: string;
  variant: ButtonVariant;
  disabled?: boolean;
  onClick: () => void;
};

Zapis () => void to typ funkcji, która nic nie przyjmuje i nic nie zwraca - tak opisujemy callbacki. Interfejs z kolei można rozszerzać słowem extends, dziedzicząc wszystkie pola bazowego protokołu:

// Interface - można rozszerzać
interface BaseProps {
  id: string;
  className?: string;
}

interface ShipProps extends BaseProps {
  name: string;
  speed: number;
}

// ShipProps ma: id, className, name, speed

Moja rekomendacja: interface dla props obiektów, type dla unii i aliasów. Najważniejsza jest jednak spójność w całym projekcie.

Rozszerzanie interfejsów

Interfejsy można łączyć i rozszerzać, tworząc bardziej skomplikowane struktury. Pole może mieć typ innego interfejsu, a kilka interfejsów może rozszerzać ten sam bazowy:

interface Coordinates {
  x: number;
  y: number;
  z: number;
}

interface SpaceObject {
  name: string;
  coordinates: Coordinates;
}

interface Planet extends SpaceObject {
  radius: number;
  habitable: boolean;
  atmosphere: string[];
}

interface Star extends SpaceObject {
  temperature: number;
  luminosity: number;
  spectralClass: string;
}

Planet i Star dzielą name i coordinates, a każdy dokłada własne pola. Zmiana w SpaceObject od razu obejmie oba typy. Te hierarchie wrócą w lekcji o discriminated unions, gdzie nauczymy komponent rozpoznawać, który obiekt dostał.

Kod do tej lekcji: App.tsx
import React from 'react';

// Interfejsy z opcjonalnymi propsami
interface Coordinates {
  x: number;
  y: number;
  z: number;
}

interface SpaceObjectProps {
  name: string;
  type: string;
  coordinates: Coordinates;
  description?: string;       // opcjonalny
  dangerLevel?: 1 | 2 | 3 | 4 | 5;  // opcjonalny
  tags?: string[];             // opcjonalny
}

// Komponent z opcjonalnymi propsami i wartosciami domyslnymi
function SpaceObject({
  name,
  type,
  coordinates,
  description = "Brak opisu",
  dangerLevel = 1,
  tags = []
}: SpaceObjectProps) {
  const dangerColors = ["#22c55e", "#84cc16", "#eab308", "#f97316", "#ef4444"];

  return (
    <div className="object-card">
      <h3>{name}</h3>
      <span className="type-badge">{type}</span>
      <p>{description}</p>
      <p className="coords">
        Pozycja: ({coordinates.x}, {coordinates.y}, {coordinates.z})
      </p>
      <div className="danger" style={{ color: dangerColors[dangerLevel - 1] }}>
        Zagrozenie: {"*".repeat(dangerLevel)}{"*".repeat(0)}
      </div>
      {tags.length > 0 && (
        <div className="tags">
          {tags.map(tag => <span key={tag} className="tag">{tag}</span>)}
        </div>
      )}
    </div>
  );
}

// Komponent z children
interface PanelProps {
  title: string;
  children: React.ReactNode;
}

function Panel({ title, children }: PanelProps) {
  return (
    <div className="panel">
      <h2>{title}</h2>
      <div className="panel-content">{children}</div>
    </div>
  );
}

function App() {
  return (
    <div className="app">
      <h1>Mapa Kosmiczna</h1>
      <Panel title="Wykryte obiekty">
        <SpaceObject
          name="Kepler-442b"
          type="Planeta"
          coordinates={{ x: 1206, y: 340, z: -89 }}
          description="Potencjalnie zamieszkiwalna superziemia"
          dangerLevel={1}
          tags={["zamieszkiwalna", "skalista"]}
        />
        <SpaceObject
          name="Betelgeuse"
          type="Gwiazda"
          coordinates={{ x: 700, y: -200, z: 45 }}
          dangerLevel={5}
        />
        <SpaceObject
          name="99942 Apophis"
          type="Asteroida"
          coordinates={{ x: 0.1, y: 0.02, z: 0 }}
          description="Asteroida bliskiej Ziemi"
          dangerLevel={4}
          tags={["NEO", "niebezpieczna"]}
        />
      </Panel>
    </div>
  );
}

export default App;

Pamiętaj: interfejs props to protokół łączności - co nie pasuje do protokołu, nie przejdzie przez śluzę.

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 oznaczyć props jako opcjonalny w interfejsie TypeScript?

  2. 2. Jaki typ TypeScript należy użyć dla propsa children, aby akceptował dowolną treść React?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Typowanie propsów z interfejsem i children

  • Układanie w poziomie

    Ułóż składnię typowania propsów komponentu za pomocą interfejsu:

  1. Zadanie z kodemPraktyka: Typowanie propsów komponentu
  2. PytanieOpcjonalne propsy w TypeScript
  3. PytanieTyp React.ReactNode
  4. Ułóż w kolejnościSkładnia props z interfejsem
  5. PytanieWartość domyślna opcjonalnego propsa

Przydatne artykuły