API di Primo Livello di React

React è il punto d’ingresso della libreria React. Se carichi React da un tag <script>, le seguenti API di primo livello sono disponibili nella variabile globale React. Se utilizzi ES6 con npm, puoi scrivere import React from 'react'. Se utilizzi ES5 con npm, puoi scrivere var React = require('react').

Panoramica

Componenti

I componenti React ti consentono di suddividere l’UI in parti indipendenti e riutilizzabili e di ragionare su ciascuna parte in modo isolato dalle altre. I componenti React possono essere definiti creando sottoclassi di React.Component o React.PureComponent.

• React.Component
• React.PureComponent

Se non ami le classi ES6, puoi utilizzare il modulo create-react-class al loro posto. Leggi Utilizzare React senza ES6 per maggiori informazioni.

I componenti React possono anche essere definiti tramite funzioni, che possono essere “wrappate”:

• React.memo

Creare Elementi React

Raccomandiamo di utilizzare JSX per descrivere l’aspetto che la tua UI dovrebbe avere. Ogni elemento JSX è solamente “zucchero sintattico” sul metodo React.createElement(). Se utilizzi JSX, non dovresti mai avere bisogno di invocare direttamente i seguenti metodi.

• createElement()
• createFactory()

Leggi Utilizzare React senza JSX per maggiori informazioni.

Trasformare Gli Elementi

React fornisce numerose API per la manipolazione degli elementi:

• cloneElement()
• isValidElement()
• React.Children

Frammenti

React fornisce anche un componente che può essere utilizzato per renderizzare elementi multipli senza un wrapper.

• React.Fragment

Refs

• React.createRef
• React.forwardRef

Suspense

La Suspense consente ai componenti di “aspettare” qualcosa prima di renderizzare. Ad oggi, la Suspense supporta solamente un caso d’uso: il caricamento dinamico dei componenti tramite React.lazy. In futuro, supporterà anche altri casi d’uso, come il caricamento dei dati.

• React.lazy
• React.Suspense

Transitions

Transitions are a new concurrent feature introduced in React 18. They allow you to mark updates as transitions, which tells React that they can be interrupted and avoid going back to Suspense fallbacks for already visible content.

• React.startTransition
• React.useTransition

Hooks

Gli Hooks sono una nuova aggiunta in React 16.8. Consentono di utilizzare lo state e altre feature di React senza dichiarare una classe. Gli Hooks hanno una sezione dedicata della documentazione e un riferimento delle API separato:

• Hooks Di Base

  • useState
  • useEffect
  • useContext

• Hooks Aggiuntivi

  • useReducer
  • useCallback
  • useMemo
  • useRef
  • useImperativeHandle
  • useLayoutEffect
  • useDebugValue
  • useDeferredValue
  • useTransition
  • useId

• Library Hooks

  • useSyncExternalStore
  • useInsertionEffect

Riferimenti

React.Component

React.Component è la classe base per definire i componenti React utilizzando le classi ES6:

class Benvenuto extends React.Component {
  render() {
    return <h1>Ciao, {this.props.name}</h1>;
  }
}

Leggi i Riferimenti di React.Component per un elenco dei metodi e delle proprietà disponibili nella classe base React.Component.

React.PureComponent

React.PureComponent è simile a React.Component. La differenza è che React.Component non implementa shouldComponentUpdate() mentre React.PureComponent lo implementa con una comparazione “shallow” delle props e dello state.

Se il metodo render() del tuo componente React produce sempre lo stesso risultato a partire dagli stessi valori di props e state (ovvero è un componente “puro”), puoi utilizzare React.PureComponent per avere un miglioramento della performance in alcuni casi.

Nota

Il metodo shouldComponentUpdate() di React.PureComponent effettua solamente una comparazione di tipo “shallow” degli oggetti. Se questi ultimi contengono strutture dati complesse, questo tipo di comparazione potrebbe produrre falsi negativi qualora le differenze siano annidate negli oggetti. Dichiara i tuoi componenti estendendo PureComponent solamente quando ti aspetti di avere props o state semplici, oppure utilizza forceUpdate() quando sei sicuro che le tue strutture dati siano cambiate in profondità. In alternativa, considera se utilizzare oggetti immutabili per facilitare la comparazione veloce di strutture dati annidate.

In aggiunta, il metodo shouldComponentUpdate() di React.PureComponent salta completamente gli aggiornamenti delle props per tutto il sottoalbero del componente. Di conseguenza, se utilizzi React.PureComponent assicurati che anche tutti gli eventuali figli del tuo componente siano a loro volta “puri”.

React.memo

const MioComponente = React.memo(function MioComponente(props) {
  /* renderizza utilizzando le props */
});

React.memo è un cosiddetto higher order component (componente di ordine superiore).

Se il tuo componente renderizza lo stesso risultato a partire dalle stesse props, puoi racchiuderlo in una chiamata a React.memo per ottenere un miglioramento della performance in alcuni casi tramite la memoizzazione del risultato. In altre parole, React eviterà di ri-renderizzare il componente, riutilizzando l’ultima renderizzazione.

React.memo controlla solo i cambiamenti delle props. Se il tuo componente funzione racchiuso in React.memo ha un Hook useState, useReducer o useContext nella sua implementazione, verrà comunque rirenderizzato al cambiamento di state o del context.

Il comportamento predefinito di React è quello di limitarsi a una comparazione shallow degli oggetti complessi contenuti in props. Se vuoi avere un controllo diretto sulla comparazione effettuata, puoi fornire una funzione personalizzata che effettui la comparazione come secondo argomento.

function MioComponente(props) {
  /* renderizza utilizzando le props */
}
function sonoUguali(propsPrecedenti, propsSuccessive) {
  /*
  restituisci true se l'invocazione di render con propsSuccessive
  restituirebbe lo stesso risultato dell'invocazione di render con
  propsPrecedenti, altrimenti restituisci false
  */
}
export default React.memo(MioComponente, sonoUguali);

Questo metodo esiste solamente come strumento per ottimizzare la performance. Non utilizzarlo per “prevenire” la renderizzazione, in quanto farlo può essere causa di bug.

Nota

A differenza del metodo shouldComponentUpdate() delle classi componente, la funzione sonoUguali restituisce true se le props sono uguali e false se non lo sono. Il metodo shouldComponentUpdate fa esattamente il contrario.

createElement()

React.createElement(
  type,
  [props],
  [...children]
)

Crea e restituisce un nuovo elemento React del tipo indicato. L’argomento type può essere un nome di tag (ad esempio 'div' o 'span'), un tipo di componente React (una classe o una funzione), o un tipo di frammento React.

Il codice scritto in JSX verrà convertito in modo da utilizzare React.createElement(). Tipicamente, non invocherai direttamente React.createElement() se utilizzi JSX. Leggi React Senza JSX per saperne di più.

cloneElement()

React.cloneElement(
  element,
  [config],
  [...children]
)

Clona e restituisce un nuovo elemento React utilizzando element come punto di partenza. config dovrebbe contenere tutte le nuove props, key, o ref. L’elemento risultante riceverà come props lo shallow merge delle props dell’elemento originale e le props passate come argomento. I nuovi children specificati come argomento sostituiranno i children dell’elemento originale. key e ref dell’elemento originale verranno preservati se non ci sono key e ref nel config.

React.cloneElement() è pressoché equivalente a:

<element.type {...element.props} {...props}>{children}</element.type>

Tuttavia, preserva anche la ref. Questo significa che se selezioni un child con una ref ad esso, non la “ruberai” accidentalmente dal suo progenitore. Otterrai invece la stessa ref assegnata al nuovo componente. I nuovi ref o key sostituiranno quelli precedenti se presenti.

Questa API è stata introdotta per sostituire il metodo deprecato React.addons.cloneWithProps().

createFactory()

React.createFactory(type)

Restituisce una funzione che produce elementi React di un certo tipo. Così come React.createElement(), l’argomento type può essere un nome di tag (ad esempio 'div' o 'span'), un tipo di componente React (una classe o una funzione), o un tipo di frammento React.

Questo metodo è considerato obsoleto e ti incoraggiamo ad utilizzare al suo posto JSX oppure direttamente React.createElement().

Tipicamente, non invocherai direttamente React.createFactory() se utilizzi JSX. Leggi React Senza JSX per saperne di più.

isValidElement()

React.isValidElement(object)

Verifica che l’oggetto sia un elemento React. Restituisce true o false.

React.Children

React.Children fornisce metodi utili per gestire la struttura dati opaca di this.props.children.

React.Children.map

React.Children.map(children, function[(thisArg)])

Invoca la funzione specificata su ciascun figlio diretto contenuto in children. Nella funzione, this verrà impostato a thisArg. Se children è un array, verrà attraversato e la funzione verrà invocata per ciascun child nell’array. Se children è null o undefined, questo metodo restituirà il valore null o undefined, altrimenti restituirà un array.

Nota

Se children è un Fragment, verrà trattato come se fosse un singolo child (e non un array) e quindi non verrà attraversato.

React.Children.forEach

React.Children.forEach(children, function[(thisArg)])

Funziona esattamente come React.Children.map() ma non restituisce un array.

React.Children.count

React.Children.count(children)

Restituisce il numero totale di componenti in children. Se si passasse una funzione ai metodi map o forEach già descritti, essa verrebbe invocata esattamente quel numero di volte.

React.Children.only

React.Children.only(children)

Verifica che children contenga un solo figlio (un elemento React) e lo restituisce. Negli altri casi questo metodo solleva un errore.

Nota:

React.Children.only() non può essere invocato sul valore restituito da React.Children.map() perché è un array e non un elemento React.

React.Children.toArray

React.Children.toArray(children)

Restituisce la struttura opaca di children come un array appiattito, con una chiave assegnata a ciascun figlio. È utile se vuoi manipolare collezioni di figli nei tuoi metodi render, specialmente se vuoi riordinare this.props.children prima di passarlo ai componenti figli o se vuoi passarne solo una parte.

Nota:

React.Children.toArray() modifica le chiavi per conservare la semantica degli array annidati quando appiattisce liste di figli. In altre parole, toArray aggiunge un prefisso in ciascuna chiave nell’array restituito in modo che la chiave di ciascun elemento sia riferita all’array di input che conteneva quell’elemento.

React.Fragment

Il componente React.Fragment ti consente di restituire elementi multipli come risultato di un metodo render() senza dover creare un element DOM aggiuntivo per contenerli:

render() {
  return (
    <React.Fragment>
      Un po' di testo.
      <h2>Un'intestazione</h2>
    </React.Fragment>
  );
}

Puoi utilizzarlo anche tramite la notazione compatta <></>. Per saperne di più, leggi React v16.2.0: Supporto ai Frammenti Migliorato.

React.createRef

React.createRef crea una ref che può essere assegnata agli elementi React tramite l’attributo ref.

class MioComponente extends React.Component {
  constructor(props) {
    super(props);

    this.inputRef = React.createRef();  }

  render() {
    return <input type="text" ref={this.inputRef} />;  }

  componentDidMount() {
    this.inputRef.current.focus();  }
}

React.forwardRef

React.forwardRef crea un componente React che inoltra l’attributo ref che riceve a un altro componente più in basso nell’albero. Questa tecnica non è molto comune, ma è particolarmente utile in due scenari:

• Inoltrare le refs ai componenti del DOM
• Inoltrare le refs nei componenti di ordine superiore

React.forwardRef accetta una funzione di renderizzazione come argomento. React invocherà quella funzione passando props e ref come argomenti. La funzione dovrebbe restituire un nodo React.

const BottoneFigo = React.forwardRef((props, ref) => (  <button ref={ref} className="BottoneFigo">    {props.children}
  </button>
));

// Puoi ottenere una ref diretta al bottone del DOM:
const ref = React.createRef();
<BottoneFigo ref={ref}>Cliccami!</BottoneFigo>;

Nell’esempio in alto, React passa una ref all’elemento <BottoneFigo ref={ref}> come secondo argomento alla funzione di renderizzazione all’interno della chiamata a React.forwardRef. Questa funzione di renderizzazione a sua volta passa la ref all’elemento <button ref={ref}>.

Il risultato è che, dopo che React ha connesso la ref, ref.current punterà direttamente all’istanza dell’elemento del DOM <button>.

Per maggiori informazioni, leggi inoltrare le refs.

React.lazy

React.lazy() ti consente di definire un componente che è caricato dinamicamente (“lazy” significa letteralmente “pigro”). Questo aiuta a ridurre le dimensioni del pacchetto della tua applicazione ritardando il caricamento dei componenti che non sono utilizzati durante la renderizzazione iniziale.

Puoi imparare come utilizzare questo metodo nella nostra documentazione sulla suddivisione del codice. Potresti voler anche leggere questo articolo in cui si spiega con ancora maggior dettaglio come utilizzarlo.

// Questo componente è caricato dinamicamente
const UnComponente = React.lazy(() => import('./UnComponente'));

Nota che la renderizzazione dei componenti lazy richiede che sia presente un componente <React.Suspense> più in alto nell’albero di renderizzazione. Questo è il modo in cui puoi specificare un indicatore di caricamento.

React.Suspense

React.Suspense ti permette di specificare un indicatore di caricamento nel caso in cui qualche componente nell’albero sottostante non è ancora pronto per essere renderizzato. Nel futuro intendiamo far si che Suspense gestisca altri scenari quali ad esempio il data fetching. Puoi saperne di più dalla nostra roadmap.

Ad oggi, il lazy loading dei componenti è il solo use case supportato da <React.Suspense>:

// Questo componente viene caricato dinamicamente
const UnAltroComponente = React.lazy(() => import('./UnAltroComponente'));

function MioComponente() {
  return (
    // Mostra <Clessidra> finché UnAltroComponente non è pronto
    <React.Suspense fallback={<Clessidra />}>
      <div>
        <UnAltroComponente />
      </div>
    </React.Suspense>
  );
}

Tutto ciò è documentato nella nostra guida per la separazione del codice. Nota che i componenti lazy possono anche essere molto in profondità nell’albero che fa capo a Suspense — non è necessario usarlo per racchiuderli uno per uno. La pratica consigliata è quella di inserire <Suspense> nel punto in cui vuoi visualizzare un indicatore di caricamento, e di utilizzare lazy() dovunque vuoi effettuare la separazione del codice.

Nota

Per contenuto che è stati già mostrato all’utente, visualizzare nuovamente un indicatore di caricamento può creare confusione. A volte è meglio mostrare la “vecchia” UI mentre la nuova UI viene preparata. Per fare ciò puoi utilizzare le nuove APIs di transizione startTransition ed useTransition per marcare aggiornamenti come transizioni ed evitare fallbacks inaspettati.

React.Suspense nel Server Side Rendering

Durante il server side rendering, Suspense Boundaries ti permettono di emettere contenuto in blocchi più piccoli sospendendo. QUando un componente si sospende, scheduliamo una task a bassa priorità per renderizzare la fallback della Suspense boundary più vicina. Se il componente si “desospende” prima che venga emessa la fallback, emetteremo il contenuto attuale ignorando del tutto la fallback.

React.Suspense durante hydration

Suspense boundaries dipendono dall’idratazione dalle loro boundaries genitori prima che possano essere idratate, ma possono idratarsi indipendentemente dalle loro boundaries sibling. Eventi su una boundary prima che venga idradata causeranno una idratazione con una priorità maggiore rispetto alle bonduaries vicine. Maggiori informazioni

React.startTransition

React.startTransition(callback)

React.startTransition ti permette di marcare aggiornamenti all’interno della callback come transizioni. Questo metodo è disegnato per essere usato quanto React.useTransition non è disponibile.

Nota:

Aggiornamenti in una transizione creano aggiornamenti con maggiore priorità, come i clicks.

Aggiornamenti in una transizione non mostreranno una fallback per contenuto sospeso, permettendo all’utente di interagire con la “vecchia” UI mentre la “nuova” UI viene preparata.

React.startTransition non offre un flag isPending. Per tenere traccia dello stato pending di una transizione guarda React.useTransition.