Riferimento API
React DOM Components

Componenti comuni (es. <div>)

Nota bene

Questa pagina è stata tradotta automaticamente e supervisionata da un maintainer. Un’ulteriore revisione da parte della community sarebbe comunque utile. Migliora questa traduzione.

Tutti i componenti browser integrati, come <div>, supportano alcune props ed eventi comuni.

Reference

Componenti comuni (es. <div>) 

<div className="wrapper">Qualche contenuto</div>

Vedi altri esempi sotto.

Props

Queste props React speciali sono supportate per tutti i componenti integrati:

  • children: Un nodo React (un elemento, una stringa, un numero, un portal, un nodo vuoto come null, undefined e booleani, oppure un array di altri nodi React). Specifica il contenuto all’interno del componente. Quando usi JSX, di solito specifichi la prop children implicitamente annidando tag come <div><span /></div>.

  • dangerouslySetInnerHTML: Un oggetto della forma { __html: '<p>some html</p>' } con una stringa HTML grezza o un valore TrustedHTML all’interno. Sostituisce la proprietà innerHTML del nodo DOM e visualizza l’HTML passato al suo interno. Va usato con estrema cautela! Se l’HTML al suo interno non è attendibile (ad esempio, se si basa su dati dell’utente), rischi di introdurre una vulnerabilità XSS. Leggi di più sull’uso di dangerouslySetInnerHTML.

  • ref: Un oggetto ref da useRef o createRef, oppure una funzione callback ref, o una stringa per i ref legacy. Il tuo ref verrà popolato con l’elemento DOM di questo nodo. Leggi di più sulla manipolazione del DOM con i ref.

  • suppressContentEditableWarning: Un booleano. Se true, sopprime l’avviso che React mostra per gli elementi che hanno sia children sia contentEditable={true} (che normalmente non funzionano insieme). Usalo se stai costruendo una libreria di input di testo che gestisce manualmente il contenuto contentEditable.

  • suppressHydrationWarning: Un booleano. Se usi la renderizzazione lato server, normalmente c’è un avviso quando server e client renderizzano contenuti diversi. In alcuni casi rari (come i timestamp), è molto difficile o impossibile garantire una corrispondenza esatta. Se imposti suppressHydrationWarning su true, React non ti avviserà delle discrepanze negli attributi e nel contenuto di quell’elemento. Funziona solo a un livello di profondità ed è pensato come via di fuga. Non abusarne. Leggi come sopprimere gli errori di hydration.

  • style: Un oggetto con stili CSS, ad esempio { fontWeight: 'bold', margin: 20 }. Analogamente alla proprietà DOM style, i nomi delle proprietà CSS devono essere scritti in camelCase, ad esempio fontWeight invece di font-weight. Puoi passare stringhe o numeri come valori. Se passi un numero, come width: 100, React aggiungerà automaticamente px (“pixel”) al valore a meno che non sia una proprietà senza unità. Consigliamo di usare style solo per stili dinamici in cui non conosci i valori degli stili in anticipo. In altri casi, applicare classi CSS semplici con className è più efficiente. Leggi di più su className e style.

Queste props DOM standard sono supportate anche per tutti i componenti integrati:

Puoi anche passare attributi personalizzati come props, ad esempio mycustomprop="someValue". Può essere utile quando integri librerie di terze parti. Il nome dell’attributo personalizzato deve essere minuscolo e non deve iniziare con on. Il valore verrà convertito in stringa. Se passi null o undefined, l’attributo personalizzato verrà rimosso.

Questi eventi scattano solo per gli elementi <form>:

Questi eventi scattano solo per gli elementi <dialog>. A differenza degli eventi del browser, in React propagano:

Questi eventi scattano solo per gli elementi <details>. A differenza degli eventi del browser, in React propagano:

Questi eventi scattano per elementi <img>, <iframe>, <object>, <embed>, <link> e SVG <image>. A differenza degli eventi del browser, in React propagano:

Questi eventi scattano per risorse come <audio> e <video>. A differenza degli eventi del browser, in React propagano:

Caveats

  • Non puoi passare contemporaneamente sia children sia dangerouslySetInnerHTML.
  • Alcuni eventi (come onAbort e onLoad) non propagano nel browser, ma propagano in React.

Funzione callback ref

Invece di un oggetto ref (come quello restituito da useRef), puoi passare una funzione all’attributo ref.

<div ref={(node) => {
  console.log('Attached', node);

  return () => {
    console.log('Clean up', node)
  }
}}>

Vedi un esempio di utilizzo della callback ref.

Quando il nodo DOM <div> viene aggiunto allo schermo, React chiamerà la tua callback ref con il node DOM come argomento. Quando quel nodo DOM <div> viene rimosso, React chiamerà la funzione di cleanup restituita dalla callback.

React chiamerà anche la tua callback ref ogni volta che passi una callback ref diversa. Nell’esempio sopra, (node) => { ... } è una funzione diversa a ogni renderizzazione. Quando il tuo componente viene ri-renderizzato, la funzione precedente verrà chiamata con null come argomento, e la funzione successiva verrà chiamata con il nodo DOM.

Parameters

  • node: Un nodo DOM. React ti passerà il nodo DOM quando il ref viene collegato. A meno che tu non passi lo stesso riferimento di funzione per la callback ref a ogni renderizzazione, la callback verrà temporaneamente pulita e ricreata a ogni ri-renderizzazione del componente.

Nota bene

React 19 ha aggiunto funzioni di cleanup per le callback ref.

Per supportare la retrocompatibilità, se una funzione di cleanup non viene restituita dalla callback ref, node verrà chiamato con null quando il ref viene scollegato. Questo comportamento verrà rimosso in una versione futura.

Returns

  • opzionale cleanup function: Quando il ref viene scollegato, React chiamerà la funzione di cleanup. Se una funzione non viene restituita dalla callback ref, React chiamerà di nuovo la callback con null come argomento quando il ref viene scollegato. Questo comportamento verrà rimosso in una versione futura.

Caveats

  • Quando Strict Mode è attivo, React eseguirà un ciclo aggiuntivo setup+cleanup solo in sviluppo prima del primo setup reale. È un stress test che assicura che la tua logica di cleanup “specchi” la logica di setup e che fermi o annulli ciò che il setup sta facendo. Se questo causa un problema, implementa la funzione di cleanup.
  • Quando passi una callback ref diversa, React chiamerà la funzione di cleanup della callback precedente se fornita. Se nessuna funzione di cleanup è definita, la callback ref verrà chiamata con null come argomento. La funzione successiva verrà chiamata con il nodo DOM.

Oggetto evento React

I tuoi gestori di eventi riceveranno un oggetto evento React. È anche talvolta noto come “evento sintetico”.

<button onClick={e => {
  console.log(e); // React event object
}} />

Rispetta lo stesso standard degli eventi DOM sottostanti, ma corregge alcune inconsistenze del browser.

Alcuni eventi React non corrispondono direttamente agli eventi nativi del browser. Ad esempio in onMouseLeave, e.nativeEvent punterà a un evento mouseout. La mappatura specifica non fa parte dell’API pubblica e potrebbe cambiare in futuro. Se hai bisogno dell’evento browser sottostante per qualche motivo, leggilo da e.nativeEvent.

Proprietà

Gli oggetti evento React implementano alcune delle proprietà standard Event:

  • bubbles: Un booleano. Restituisce se l’evento propaga attraverso il DOM.
  • cancelable: Un booleano. Restituisce se l’evento può essere annullato.
  • currentTarget: Un nodo DOM. Restituisce il nodo a cui il gestore corrente è collegato nell’albero React.
  • defaultPrevented: Un booleano. Restituisce se preventDefault è stato chiamato.
  • eventPhase: Un numero. Restituisce in quale fase si trova attualmente l’evento.
  • isTrusted: Un booleano. Restituisce se l’evento è stato avviato dall’utente.
  • target: Un nodo DOM. Restituisce il nodo su cui l’evento si è verificato (che potrebbe essere un discendente distante).
  • timeStamp: Un numero. Restituisce l’ora in cui l’evento si è verificato.

Inoltre, gli oggetti evento React forniscono queste proprietà:

  • nativeEvent: Un Event DOM. L’oggetto evento originale del browser.

Metodi

Gli oggetti evento React implementano alcuni dei metodi standard Event:

  • preventDefault(): Impedisce l’azione predefinita del browser per l’evento.
  • stopPropagation(): Interrompe la propagazione dell’evento attraverso l’albero React.

Inoltre, gli oggetti evento React forniscono questi metodi:

  • isDefaultPrevented(): Restituisce un boolean value indicating whether preventDefault was called.
  • isPropagationStopped(): Restituisce un boolean value indicating whether stopPropagation was called.
  • persist(): Non usato con React DOM. Con React Native, chiamalo per leggere le proprietà dell’evento dopo l’evento.
  • isPersistent(): Non usato con React DOM. Con React Native, restituisce se persist è stato chiamato.

Caveats

  • I valori di currentTarget, eventPhase, target e type riflettono i valori che il tuo codice React si aspetta. Sotto il cofano, React collega i gestori di eventi alla radice, ma questo non si riflette negli oggetti evento React. Ad esempio, e.currentTarget potrebbe non essere lo stesso di e.nativeEvent.currentTarget sottostante. Per eventi polyfillati, e.type (tipo evento React) potrebbe differire da e.nativeEvent.type (tipo sottostante).

Funzione gestore AnimationEvent

Un tipo di gestore di eventi per gli eventi di animazione CSS.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

Parameters

Funzione gestore ClipboardEvent

Un tipo di gestore di eventi per gli eventi della Clipboard API.

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

Parameters

Funzione gestore CompositionEvent

Un tipo di gestore di eventi per gli eventi dell’editor di metodo di input (IME).

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

Parameters

Funzione gestore DragEvent

Un tipo di gestore di eventi per gli eventi dell’HTML Drag and Drop API.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Sorgente drag
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Target di drop
  </div>
</>

Parameters

Funzione gestore FocusEvent

Un tipo di gestore di eventi per gli eventi di focus.

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

Vedi un esempio.

Parameters

Funzione gestore Event

Un tipo di gestore di eventi per eventi generici.

Parameters

Funzione gestore InputEvent

Un tipo di gestore di eventi per l’evento onBeforeInput.

<input onBeforeInput={e => console.log('onBeforeInput')} />

Parameters

Funzione gestore KeyboardEvent

Un tipo di gestore di eventi per gli eventi da tastiera.

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

Vedi un esempio.

Parameters

Funzione gestore MouseEvent

Un tipo di gestore di eventi per gli eventi del mouse.

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

Vedi un esempio.

Parameters

Funzione gestore PointerEvent

Un tipo di gestore di eventi per gli eventi pointer.

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

Vedi un esempio.

Parameters

Funzione gestore TouchEvent

Un tipo di gestore di eventi per gli eventi touch.

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

Parameters

Funzione gestore TransitionEvent

Un tipo di gestore di eventi per gli eventi di transizione CSS.

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

Parameters

Funzione gestore UIEvent

Un tipo di gestore di eventi per eventi UI generici.

<div
  onScroll={e => console.log('onScroll')}
/>

Parameters

Funzione gestore WheelEvent

Un tipo di gestore di eventi per l’evento onWheel.

<div
  onWheel={e => console.log('onWheel')}
/>

Parameters

Usage

Applicare stili CSS

In React, specifichi una classe CSS con className. Funziona come l’attributo class in HTML:

<img className="avatar" />

Poi scrivi le regole CSS in un file CSS separato:

/* Nel tuo CSS */
.avatar {
  border-radius: 50%;
}

React non prescrive come aggiungere file CSS. Nel caso più semplice, aggiungerai un tag <link> al tuo HTML. Se usi un build tool o un framework, consulta la sua documentazione per sapere come aggiungere un file CSS al tuo progetto.

A volte, i valori degli stili dipendono dai dati. Usa l’attributo style per passare alcuni stili dinamicamente:

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

Nell’esempio sopra, style={{}} non è una sintassi speciale, ma un normale oggetto {} all’interno delle parentesi graffe JSX di style={ }. Consigliamo di usare l’attributo style solo quando i tuoi stili dipendono da variabili JavaScript.

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
Approfondimento

Come applicare più classi CSS condizionalmente?

Per applicare classi CSS condizionalmente, devi produrre la stringa className tu stesso usando JavaScript.

Ad esempio, className={'row ' + (isSelected ? 'selected': '')} produrrà className="row" o className="row selected" a seconda che isSelected sia true.

Per renderlo più leggibile, puoi usare una piccola libreria helper come classnames:

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

È particolarmente comodo se hai più classi condizionali:

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

Manipolare un nodo DOM con un ref

A volte, avrai bisogno di ottenere il nodo DOM del browser associato a un tag in JSX. Ad esempio, se vuoi mettere a fuoco un <input> quando viene cliccato un bottone, devi chiamare focus() sul nodo DOM <input> del browser.

Per ottenere il nodo DOM del browser per un tag, dichiara un ref e passalo come attributo ref a quel tag:

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

React inserirà il nodo DOM in inputRef.current dopo che è stato renderizzato sullo schermo.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Metti a fuoco l'input
      </button>
    </>
  );
}

Leggi di più sulla manipolazione del DOM con i ref e consulta altri esempi.

Per casi d’uso più avanzati, l’attributo ref accetta anche una funzione callback.

Impostare pericolosamente l’inner HTML

Puoi passare una stringa HTML grezza o un valore TrustedHTML a un elemento così:

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

Questo è pericoloso. Come con la proprietà DOM innerHTML sottostante, devi usare estrema cautela! A meno che il markup non provenga da una fonte completamente attendibile, è banale introdurre una vulnerabilità XSS in questo modo.

Se il tuo sito applica Trusted Types, passa un valore TrustedHTML creato dalla tua policy di sicurezza come __html. React passa il valore al browser senza convertirlo in stringa, permettendo al browser di validarlo. La tua policy deve comunque assicurare che qualsiasi input usato per creare il valore sia attendibile e sanitizzato.

Ad esempio, se usi una libreria Markdown che converte Markdown in HTML, ti fidi che il suo parser non contenga bug, e l’utente vede solo il proprio input, puoi visualizzare l’HTML risultante così:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // Questo è sicuro SOLO perché l'HTML in output
  // viene mostrato allo stesso utente, e perché ti
  // fidi che questo parser Markdown non abbia bug.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

L’oggetto {__html} dovrebbe essere creato il più vicino possibile al punto in cui l’HTML viene generato, come fa l’esempio sopra nella funzione renderMarkdownToHTML. Questo assicura che tutto l’HTML grezzo usato nel tuo codice sia esplicitamente contrassegnato come tale, e che solo le variabili che ti aspetti contengano HTML vengano passate a dangerouslySetInnerHTML. Non è consigliato creare l’oggetto inline come <div dangerouslySetInnerHTML={{__html: markup}} />.

Per capire perché renderizzare HTML arbitrario è pericoloso, sostituisci il codice sopra con questo:

const post = {
  // Immagina che questo contenuto sia salvato nel database.
  content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
  // 🔴 BUCO DI SICUREZZA: passare input non attendibile a dangerouslySetInnerHTML
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

Il codice incorporato nell’HTML verrà eseguito. Un hacker potrebbe usare questo buco di sicurezza per rubare informazioni dell’utente o eseguire azioni per conto suo. Usa dangerouslySetInnerHTML solo con dati attendibili e sanitizzati.

Gestire eventi del mouse

Questo esempio mostra alcuni comuni eventi del mouse e quando scattano.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        Primo bottone
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Secondo bottone
      </button>
    </div>
  );
}

Gestire eventi pointer

Questo esempio mostra alcuni comuni eventi pointer e quando scattano.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        Primo figlio
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Secondo figlio
      </div>
    </div>
  );
}

Gestire eventi di focus

In React, gli eventi di focus propagano. Puoi usare currentTarget e relatedTarget per distinguere se gli eventi di focus o blur hanno origine al di fuori dell’elemento genitore. L’esempio mostra come rilevare il focus su un figlio, il focus sull’elemento genitore e come rilevare l’ingresso o l’uscita del focus dall’intero sottoalbero.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Non scatta quando si scambia il focus tra i figli
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Non scatta quando si scambia il focus tra i figli
          console.log('focus left parent');
        }
      }}
    >
      <label>
        Nome:
        <input name="firstName" />
      </label>
      <label>
        Cognome:
        <input name="lastName" />
      </label>
    </div>
  );
}

Gestire eventi da tastiera

Questo esempio mostra alcuni comuni eventi da tastiera e quando scattano.

export default function KeyboardExample() {
  return (
    <label>
      Nome:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
PreviousReact DOM Components
Next<form>