Presentiamo react.dev

16 marzo 2023 di Dan Abramov e Rachel Nabors

---

---

tl;dr

• Il nuovo sito React (react.dev) insegna React moderno con componenti funzione e Hooks.
• Abbiamo incluso diagrammi, illustrazioni, sfide e oltre 600 nuovi esempi interattivi.
• Il precedente sito di documentazione React è ora su legacy.reactjs.org.

Nuovo sito, nuovo dominio, nuova homepage

Prima, un po’ di organizzazione.

Per celebrare il lancio della nuova documentazione e, soprattutto, per separare chiaramente i contenuti vecchi e nuovi, ci siamo spostati sul dominio più corto react.dev. Il vecchio dominio reactjs.org ora reindirizza qui.

La vecchia documentazione React è archiviata su legacy.reactjs.org. Tutti i link esistenti ai contenuti vecchi reindirizzeranno automaticamente lì per evitare di “rompere il web”, ma il sito legacy non riceverà molti altri aggiornamenti.

Che tu ci creda o no, React compirà presto dieci anni. In anni JavaScript, è come un secolo intero! Abbiamo rinnovato la homepage React per riflettere perché pensiamo che React sia un ottimo modo per creare interfacce utente oggi, e abbiamo aggiornato le guide per iniziare menzionando più in evidenza i framework moderni basati su React.

Se non hai ancora visto la nuova homepage, dagli un’occhiata!

Tutto su React moderno con gli Hooks

Quando abbiamo rilasciato React Hooks nel 2018, la documentazione sugli Hooks presupponeva che il lettore conoscesse i componenti class. Questo ha aiutato la community ad adottare gli Hooks molto rapidamente, ma col tempo la vecchia documentazione non serviva più i nuovi lettori. I nuovi lettori dovevano imparare React due volte: prima con i componenti class e poi di nuovo con gli Hooks.

La nuova documentazione insegna React con gli Hooks fin dall’inizio. La documentazione è divisa in due sezioni principali:

• Impara React è un corso autogestito che insegna React da zero.
• API Reference fornisce i dettagli e gli esempi d’uso per ogni API React.

Vediamo più da vicino cosa trovi in ciascuna sezione.

Avvio Rapido

La sezione Impara React inizia con la pagina Avvio Rapido. È un breve tour introduttivo di React. Introduce la sintassi per concetti come componenti, props e state, ma non entra in molto dettaglio su come usarli.

Se ti piace imparare facendo, ti consigliamo di provare subito dopo il Tutorial: Tic-Tac-Toe. Ti guida nella costruzione di un piccolo gioco con React, insegnandoti le competenze che userai ogni giorno. Ecco cosa costruirai:

import { useState } from 'react';

function Square({ value, onSquareClick }) {
  return (
    <button className="square" onClick={onSquareClick}>
      {value}
    </button>
  );
}

function Board({ xIsNext, squares, onPlay }) {
  function handleClick(i) {
    if (calculateWinner(squares) || squares[i]) {
      return;
    }
    const nextSquares = squares.slice();
    if (xIsNext) {
      nextSquares[i] = 'X';
    } else {
      nextSquares[i] = 'O';
    }
    onPlay(nextSquares);
  }

  const winner = calculateWinner(squares);
  let status;
  if (winner) {
    status = 'Winner: ' + winner;
  } else {
    status = 'Next player: ' + (xIsNext ? 'X' : 'O');
  }

  return (
    <>
      <div className="status">{status}</div>
      <div className="board-row">
        <Square value={squares[0]} onSquareClick={() => handleClick(0)} />
        <Square value={squares[1]} onSquareClick={() => handleClick(1)} />
        <Square value={squares[2]} onSquareClick={() => handleClick(2)} />
      </div>
      <div className="board-row">
        <Square value={squares[3]} onSquareClick={() => handleClick(3)} />
        <Square value={squares[4]} onSquareClick={() => handleClick(4)} />
        <Square value={squares[5]} onSquareClick={() => handleClick(5)} />
      </div>
      <div className="board-row">
        <Square value={squares[6]} onSquareClick={() => handleClick(6)} />
        <Square value={squares[7]} onSquareClick={() => handleClick(7)} />
        <Square value={squares[8]} onSquareClick={() => handleClick(8)} />
      </div>
    </>
  );
}

export default function Game() {
  const [history, setHistory] = useState([Array(9).fill(null)]);
  const [currentMove, setCurrentMove] = useState(0);
  const xIsNext = currentMove % 2 === 0;
  const currentSquares = history[currentMove];

  function handlePlay(nextSquares) {
    const nextHistory = [...history.slice(0, currentMove + 1), nextSquares];
    setHistory(nextHistory);
    setCurrentMove(nextHistory.length - 1);
  }

  function jumpTo(nextMove) {
    setCurrentMove(nextMove);
  }

  const moves = history.map((squares, move) => {
    let description;
    if (move > 0) {
      description = 'Go to move #' + move;
    } else {
      description = 'Go to game start';
    }
    return (
      <li key={move}>
        <button onClick={() => jumpTo(move)}>{description}</button>
      </li>
    );
  });

  return (
    <div className="game">
      <div className="game-board">
        <Board xIsNext={xIsNext} squares={currentSquares} onPlay={handlePlay} />
      </div>
      <div className="game-info">
        <ol>{moves}</ol>
      </div>
    </div>
  );
}

function calculateWinner(squares) {
  const lines = [
    [0, 1, 2],
    [3, 4, 5],
    [6, 7, 8],
    [0, 3, 6],
    [1, 4, 7],
    [2, 5, 8],
    [0, 4, 8],
    [2, 4, 6],
  ];
  for (let i = 0; i < lines.length; i++) {
    const [a, b, c] = lines[i];
    if (squares[a] && squares[a] === squares[b] && squares[a] === squares[c]) {
      return squares[a];
    }
  }
  return null;
}

Vorremmo anche evidenziare Pensare in React — è il tutorial che ha fatto “cliccare” React per molti di noi. Abbiamo aggiornato entrambi questi tutorial classici per usare componenti funzione e Hooks, quindi sono come nuovi.

Impara React passo dopo passo

Vorremmo che tutti nel mondo avessero la stessa opportunità di imparare React gratuitamente, in autonomia.

Ecco perché la sezione Impara React è organizzata come un corso autogestito diviso in capitoli. I primi due capitoli descrivono i fondamentali di React. Se sei nuovo a React, o vuoi rinfrescarlo in memoria, inizia da qui:

• Descrivere la UI insegna come mostrare informazioni con i componenti.
• Aggiungere le Interazioni insegna come aggiornare lo schermo in risposta all’input dell’utente.

I prossimi due capitoli sono più avanzati e ti daranno una comprensione più profonda delle parti più complesse:

• Gestione dello state insegna come organizzare la logica man mano che la tua app cresce in complessità.
• Soluzioni alternative insegna come puoi “uscire” da React e quando ha più senso farlo.

Ogni capitolo consiste di diverse pagine correlate. La maggior parte di queste pagine insegna una competenza o una tecnica specifica — ad esempio Scrivere Markup con JSX, Aggiornare gli Oggetti nello State, o Condividere lo State tra Componenti. Alcune pagine si concentrano sull’esplicazione di un’idea — come Renderizzare e Aggiornare, o Lo State come un’Istantanea. E ce ne sono alcune, come Potresti non avere bisogno di un Effetto, che condividono i nostri suggerimenti basati su ciò che abbiamo imparato in questi anni.

Non devi leggere questi capitoli in sequenza. Chi ha tempo per questo?! Ma potresti. Le pagine nella sezione Impara React si basano solo su concetti introdotti dalle pagine precedenti. Se vuoi leggerlo come un libro, fallo pure!

Verifica la comprensione con le sfide

La maggior parte delle pagine nella sezione Impara React termina con alcune sfide per verificare la comprensione. Ad esempio, ecco alcune sfide dalla pagina sulla Renderizzazione Condizionale.

Non devi risolverle adesso! A meno che non voglia davvero.

function Item({ name, isPacked }) {
  return (
    <li className="item">
      {name} {isPacked && '✅'}
    </li>
  );
}

export default function PackingList() {
  return (
    <section>
      <h1>Sally Ride's Packing List</h1>
      <ul>
        <Item
          isPacked={true}
          name="Space suit"
        />
        <Item
          isPacked={true}
          name="Helmet with a golden leaf"
        />
        <Item
          isPacked={false}
          name="Photo of Tam"
        />
      </ul>
    </section>
  );
}

Nota il pulsante “Mostra soluzione” nell’angolo in basso a sinistra. È comodo se vuoi verificare da solo!

Costruisci un’intuizione con diagrammi e illustrazioni

Quando non riuscivamo a spiegare qualcosa solo con codice e parole, abbiamo aggiunto diagrammi che aiutano a fornire intuizione. Ad esempio, ecco uno dei diagrammi da Preservare e Resettare lo Stato:

Vedrai anche alcune illustrazioni in tutta la documentazione — ecco una del browser che dipinge lo schermo:

Abbiamo confermato con i vendor dei browser che questa rappresentazione è scientificamente accurata al 100%.

Una nuova API Reference dettagliata

Nell’API Reference, ogni API React ha ora una pagina dedicata. Questo include tutti i tipi di API:

• Hooks integrati come useState.
• Componenti integrati come <Suspense>.
• Componenti browser integrati come <input>.
• API orientate ai framework come renderToPipeableStream.
• Altre API React come memo.

Noterai che ogni pagina API è divisa in almeno due segmenti: Reference e Usage.

Reference descrive la firma formale dell’API elencando argomenti e valori di ritorno. È concisa, ma può sembrare un po’ astratta se non conosci quell’API. Descrive cosa fa un’API, ma non come usarla.

Usage mostra perché e come useresti questa API in pratica, come potrebbe spiegare un collega o un amico. Mostra gli scenari canonici di come ogni API era pensata per essere usata dal team React. Abbiamo aggiunto snippet con codifica colori, esempi di uso di API diverse insieme e ricette che puoi copiare e incollare:

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <button onClick={handleClick}>
      You pressed me {count} times
    </button>
  );
}

Alcune pagine API includono anche Troubleshooting (per problemi comuni) e Alternatives (per API deprecate).

Speriamo che questo approccio renda l’API reference utile non solo per cercare un argomento, ma per vedere tutte le cose diverse che puoi fare con una data API — e come si collega alle altre.

Cosa c’è dopo?

Questo conclude il nostro piccolo tour! Dai un’occhiata al nuovo sito, vedi cosa ti piace o non ti piace e continua a inviarci feedback nel nostro issue tracker.

Riconosciamo che questo progetto ha impiegato molto tempo per essere rilasciato. Volevamo mantenere un alto standard di qualità che la community React merita. Mentre scrivevamo questa documentazione e creavamo tutti gli esempi, abbiamo trovato errori in alcune nostre spiegazioni, bug in React e persino lacune nel design di React che stiamo ora lavorando per affrontare. Speriamo che la nuova documentazione ci aiuti a tenere React stesso a uno standard più alto in futuro.

Abbiamo sentito molte delle vostre richieste di espandere contenuti e funzionalità del sito, ad esempio:

• Fornire una versione TypeScript per tutti gli esempi;
• Creare le guide aggiornate su performance, testing e accessibilità;
• Documentare React Server Components indipendentemente dai framework che li supportano;
• Lavorare con la nostra community internazionale per tradurre la nuova documentazione;
• Aggiungere funzionalità mancanti al nuovo sito (ad esempio, RSS per questo blog).

Ora che react.dev è uscito, potremo spostare il focus dal “recuperare” le risorse educative React di terze parti all’aggiungere nuove informazioni e migliorare ulteriormente il nostro nuovo sito.

Pensiamo che non ci sia mai stato un momento migliore per imparare React.

Chi ha lavorato a questo?

Nel team React, Rachel Nabors ha guidato il progetto (e fornito le illustrazioni), e Dan Abramov ha progettato il curriculum. Hanno anche co-autorato la maggior parte dei contenuti insieme.

Naturalmente, nessun progetto così grande avviene in isolamento. Abbiamo molte persone da ringraziare!

Sylwia Vargas ha rinnovato i nostri esempi andando oltre “foo/bar/baz” e gattini, includendo scienziati, artisti e città da tutto il mondo. Maggie Appleton ha trasformato i nostri scarabocchi in un chiaro sistema di diagrammi.

Grazie a David McCabe, Sophie Alpert, Rick Hanlon, Andrew Clark, e Matt Carroll per i contributi di scrittura aggiuntivi. Vorremmo anche ringraziare Natalia Tepluhina e Sebastian Markbåge per le loro idee e feedback.

Grazie a Dan Lebowitz per il design del sito e Razvan Gradinar per il design delle sandbox.

Sul fronte dello sviluppo, grazie a Jared Palmer per lo sviluppo del prototipo. Grazie a Dane Grant e Dustin Goodman di ThisDotLabs per il supporto allo sviluppo UI. Grazie a Ives van Hoorne, Alex Moldovan, Jasper De Moor, e Danilo Woznica di CodeSandbox per il lavoro sull’integrazione delle sandbox. Grazie a Rick Hanlon per sviluppo spot e lavoro di design, perfezionando colori e dettagli. Grazie a Harish Kumar e Luna Ruan per aver aggiunto nuove funzionalità al sito e aiutato a mantenerlo.

Enormi grazie alle persone che hanno donato il loro tempo per partecipare al programma di alpha e beta testing. Il vostro entusiasmo e feedback inestimabile ci hanno aiutato a plasmare questa documentazione. Un ringraziamento speciale alla nostra beta tester, Debbie O’Brien, che ha tenuto un talk sulla sua esperienza usando la documentazione React a React Conf 2021.

Infine, grazie alla community React per essere l’ispirazione dietro questo sforzo. Siete la ragione per cui lo facciamo, e speriamo che la nuova documentazione vi aiuti a usare React per costruire qualsiasi interfaccia utente desideriate.