L'API haut-niveau de React

L’objet React est le point d’entrée de la bibliothèque React. Si vous chargez React depuis une balise <script>, ces API de haut-niveau sont disponibles depuis l’objet global React. Si vous utilisez npm avec la syntaxe ES6, vous pouvez écrire : import React from 'react'. Si vous utilisez npm avec la syntaxe ES5, vous pouvez écrire : var React = require('react').

Aperçu

Composants

Les composants React vous permettent de découper une interface utilisateur (UI, pour User Interface, NdT) en blocs indépendants et réutilisables, ce qui vous permet de concevoir chaque partie en isolation. Un composant React peut être défini en étendant les classes React.Component ou React.PureComponent.

• React.Component
• React.PureComponent

Si vous n’utilisez pas les classes ES6, vous pouvez utiliser le module create-react-class à la place. Lisez React sans ES6 pour plus de détails.

Un composant React peut aussi être défini via une fonction que l’on pourra choisir d’enrober avec React.memo :

• React.memo

Créer des éléments React

Nous vous recommandons d’utiliser JSX pour définir à quoi ressemblera votre UI. Tous les éléments JSX ne sont que du sucre syntaxique qui cache des appels à React.createElement(). Si vous utilisez JSX, vous ne devriez pas avoir besoin d’appeler les méthodes suivantes :

• createElement()
• createFactory()

Lisez React sans JSX pour plus de détails.

Transformer des éléments

React propose plusieurs API pour manipuler les éléments :

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

Fragments

React fournit également un composant particulier pour réaliser le rendu de plusieurs éléments sans avoir à les envelopper avec un autre.

• React.Fragment

Refs

• React.createRef
• React.forwardRef

Suspense

Suspense permet aux composants « d’attendre » quelque chose avant de s’afficher. Pour le moment, Suspense ne prend en charge qu’un seul cas d’usage : le chargement dynamique de composants avec React.lazy. À l’avenir, il permettra de gérer d’autres cas d’usages tels que le chargement de données distantes.

• 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

Les Hooks sont une nouveauté de React 16.8. Ils vous permettent d’utiliser les états et d’autres fonctionnalités de React sans avoir à écrire de classes. Les Hooks disposent de leur propre documentation et leur API est détaillée à part :

• Hooks de base

  • useState
  • useEffect
  • useContext

• Hooks supplémentaires

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

• Library Hooks

  • useSyncExternalStore
  • useInsertionEffect

Référence de l’API

React.Component

React.Component est la classe de base utilisée pour créer des composants React avec la syntaxe des classes ES6 :

class Greeting extends React.Component {
  render() {
    return <h1>Bonjour {this.props.name}</h1>;
  }
}

Rendez-vous sur la page de référence de l’API React.Component pour voir la liste complète des méthodes et propriétés de la classe de base React.Component.

React.PureComponent

React.PureComponent est similaire à React.Component. La seule différence est que React.Component n’implémente pas la méthode shouldComponentUpdate(), alors que React.PureComponent l’implémente en réalisant une comparaison de surface de l’état et des propriétés.

Si la fonction render() d’un de vos composants React produit un rendu identique pour le même état et les mêmes propriétés, le faire étendre React.PureComponent devrait améliorer les performances dans certains cas.

Remarque

La méthode shouldComponentUpdate() de React.PureComponent réalise une simple comparaison de surface. Avec des données complexes, elle peut produire des faux négatifs si la structure de données subit des changements profonds. Ne créez des composants avec PureComponent que si vous avez des états et des props simples, et le cas échéant utilisez forceUpdate() si vous savez que vos données ont changé en profondeur. Vous pouvez aussi envisager d’utiliser des objets immuables pour simplifier la comparaison rapide de données imbriquées.

De plus, la méthode shouldComponentUpdate() de React.PureComponent ignore la mise à jour des propriétés de tout l’arbre des composants enfants. Assurez-vous donc que tous les composants enfants sont également « purs ».

React.memo

const MyComponent = React.memo(function MyComponent(props) {
  /* Faire le rendu en utilisant les props */
});

React.memo est un composant d’ordre supérieur.

Si vous avez un composant qui affiche toujours le même résultat pour un même jeu de propriétés, vous pouvez l’enrober avec React.memo, ce qui mémoïsera le résultat et devrait augmenter les performances dans certains cas. Cela signifie que React sautera le rafraîchissement du composant en réutilisant son dernier rendu en date.

React.memo ne se préoccupe que des modifications de props. Si votre fonction composant enrobée par React.memo utilise un Hook useState ou useContext dans son implémentation, des changements d’état local ou de contexte entraîneront tout de même un nouveau rendu.

Par défaut, seule une comparaison de surface des props sera faite. Si vous voulez gérer cette comparaison vous-même, vous pouvez fournir une fonction de comparaison personnalisée en deuxième argument.

function MyComponent(props) {
  /* Faire le rendu en utilisant les props */
}
function areEqual(prevProps, nextProps) {
  /*
  Renvoie `true` si passer l'objet nextProps à la fonction de rendu
  produira le même résultat que de lui passer l'objet prevProps.
  Renvoie `false` dans le cas contraire.
  */
}
export default React.memo(MyComponent, areEqual);

Cette méthode n’est qu’un outil d’optimisation des performances. Ne vous y fiez pas pour « empêcher » un rendu car cela peut causer des bugs.

Remarque

Contrairement à la méthode shouldComponentUpdate() des composants créés à l’aide de classes, la fonction areEqual renvoie true si les props sont égales et false dans le cas contraire. C’est donc l’inverse de shouldComponentUpdate.

createElement()

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

Cette méthode crée et renvoie un nouvel élément React du type indiqué. L’argument type peut être au choix : une chaîne contenant un nom de balise (tel que 'div' ou 'span'), un type de composant React (une classe ou une fonction), ou encore un fragment React.

Tout code écrit avec JSX sera converti de manière à utiliser React.createElement(). Normalement vous ne devriez pas appeler React.createElement() si vous utilisez JSX. Lisez React sans JSX pour en savoir plus.

cloneElement()

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

Cette méthode clone et renvoie un nouvel élément en utilisant element comme point de départ. L’élément obtenu aura les props de l’élément originel augmentées par une fusion de surface des nouvelles props. Les nouveaux éléments enfants (children) remplaceront les anciens. Les key et ref issues de l’élément originel seront préservées.

React.cloneElement() est quasiment équivalent à :

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

Cependant elle préserve les ref. Concrètement, ça signifie que si vous avez un enfant avec une ref associée, vous ne la volerez pas accidentellement à votre ancêtre. Vous aurez la même ref associée au nouvel élément. The new ref or key will replace old ones if present.

Cette API a été introduite pour remplacer la méthode dépréciée React.addons.cloneWithProps().

createFactory()

React.createFactory(type)

Cette méthode renvoie une fonction qui produit des éléments React d’un type donné. Comme pour React.createElement(), l’argument type peut être au choix : une chaîne contenant un nom de balise (tel que 'div' ou 'span'), un type de composant React (une classe ou une fonction), ou encore un type de fragment React.

Cette fonction d’aide est historique et nous vous encourageons plutôt à utiliser JSX ou directement React.createElement().

Normalement vous ne devriez pas appeler React.createFactory() si vous utilisez JSX. Lisez React sans JSX pour en savoir plus.

isValidElement()

React.isValidElement(object)

Cette méthode vérifie qu’un objet est bien un élément React. Elle renvoie true ou false.

React.Children

React.Children fournit des utilitaires pour interagir avec la structure de données opaque de this.props.children.

React.Children.map

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

Cette méthode exécute une fonction sur chacun des enfants directs contenus dans children avec le this en vigueur transmis dans l’argument thisArg. Si children est un tableau, il sera parcouru et la fonction sera appelée sur chacun des enfants du tableau. Si children est null ou undefined, la méthode renverra null ou undefined plutôt qu’un tableau.

Remarque

Si children est un Fragment il sera traité comme un unique enfant et ne sera pas parcouru.

React.Children.forEach

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

Même chose que React.Children.map() mais sans renvoyer de tableau.

React.Children.count

React.Children.count(children)

Cette méthode renvoie le nombre total de composants présents dans children, ce total étant égal au nombre de fois qu’une fonction de rappel passée à map ou forEach serait exécutée.

React.Children.only

React.Children.only(children)

Cette méthode vérifie que children n’a qu’un seul enfant (un élément React) et le renvoie. Si ce n’est pas le cas elle lèvera une erreur.

Remarque

React.Children.only() n’accepte pas la valeur de retour de React.Children.map() car il s’agit d’un tableau et non d’un élément React.

React.Children.toArray

React.Children.toArray(children)

Cette méthode renvoie la structure de donnée opaque de children sous la forme d’un tableau linéarisé ou chaque enfant est doté d’une key. C’est utile si vous voulez manipuler une collection d’enfants dans votre méthode de rendu, en particulier si vous voulez réorganiser ou découper this.props.children avant de le passer à d’autres éléments.

Remarque

React.Children.toArray() change les key pour préserver la sémantique des tableaux imbriqués pendant la linéarisation des enfants. Pour cela, toArray préfixe chaque key dans le tableau qui sera renvoyé de manière a ce que la key de chaque élément soit associée au tableau originel qui les contient.

React.Fragment

Le composant React.Fragment vous permet de renvoyer plusieurs éléments depuis une méthode render() sans avoir à créer un élément DOM supplémentaire :

render() {
  return (
    <React.Fragment>
      Du texte.
      <h2>Un en-tête</h2>
    </React.Fragment>
  );
}

Vous pouvez également l’utiliser via la syntaxe raccourcie <></> . Pour plus d’information, lisez React v16.2.0: Improved Support for Fragments (en anglais).

React.createRef

React.createRef crée une ref qui peut être associée à des éléments React via l’attribut ref.

class MyComponent 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 crée un composant React qui transfère la valeur de l’attribut ref qu’il reçoit à un autre composant plus bas dans l’arbre. Cette technique est assez inhabituelle mais elle est particulièrement utile dans deux cas :

• Transférer une référence à un composant DOM
• Transférer une référence au sein d’un composant d’ordre supérieur

React.forwardRef prend une fonction de rendu comme argument. React appellera cette fonction avec deux arguments props et ref. Cette fonction devrait renvoyer un nœud React.

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

// You can now get a ref directly to the DOM button:
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

Dans l’exemple ci-avant, la fonction de rendu passée à React.forwardRef recevra comme deuxième argument la ref initialement fournie à l’élément <FancyButton ref={ref}>. Cette fonction va alors transférer la ref à l’élément <button ref={ref}>.

En conséquence, après que React aura attaché la ref, ref.current pointera directement vers l’instance de l’élément DOM de <button>.

Pour en savoir plus, lisez Transférer les refs

React.lazy

React.lazy() vous permet de définir un composant qui sera chargé dynamiquement. Cela aide à réduire la taille du fichier initial en reportant à plus tard le chargement des composants inutiles lors du rendu initial.

Vous pouvez apprendre comment l’utiliser en lisant la documentation sur la découpe du code. Vous voudrez peut-être aussi jeter un œil à cet article, qui explique comment l’utiliser en détail.

// Ce composant est chargé dynamiquement
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Notez bien que l’affichage d’un composant lazy a besoin d’un composant <React.Suspense> plus haut dans l’arbre de rendu. C’est de cette manière que vous pouvez spécifier un indicateur de chargement.

React.Suspense

React.Suspense lets you specify the loading indicator in case some components in the tree below it are not yet ready to render. In the future we plan to let Suspense handle more scenarios such as data fetching. You can read about this in our roadmap.

React.Suspense vous permet de définir un indicateur de chargement pour le cas où certains composants plus bas dans l’arbre de rendu ne seraient pas encore prêts à être affichés. Pour le moment le seul cas d’usage pris en charge par <React.Suspense>, c’est le chargement différé de composants via React.lazy :

// Ce composant est chargé dynamiquement
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Affiche <Spinner> jusqu'à ce que <OtherComponent> soit chargé
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Tout ça est détaillé dans notre guide sur la découpe du code. Remarquez que les composants lazy peuvent être profondément enfouis dans l’arbre des descendants de Suspense—ils n’ont pas besoin d’être enveloppés individuellement. La bonne pratique consiste à placer un <Suspense> aux endroits où vous souhaitez voir un indicateur de chargement, et à utiliser lazy() partout ou vous voulez découper votre code.

Note

For content that is already shown to the user, switching back to a loading indicator can be disorienting. It is sometimes better to show the “old” UI while the new UI is being prepared. To do this, you can use the new transition APIs startTransition and useTransition to mark updates as transitions and avoid unexpected fallbacks.

React.Suspense in Server Side Rendering

During server side rendering Suspense Boundaries allow you to flush your application in smaller chunks by suspending. When a component suspends we schedule a low priority task to render the closest Suspense boundary’s fallback. If the component unsuspends before we flush the fallback then we send down the actual content and throw away the fallback.

React.Suspense during hydration

Suspense boundaries depend on their parent boundaries being hydrated before they can hydrate, but they can hydrate independently from sibling boundaries. Events on a boundary before it is hydrated will cause the boundary to hydrate at a higher priority than neighboring boundaries. Read more

React.startTransition

React.startTransition(callback)

React.startTransition lets you mark updates inside the provided callback as transitions. This method is designed to be used when React.useTransition is not available.

Remarque

Updates in a transition yield to more urgent updates such as clicks.

Updates in a transition will not show a fallback for re-suspended content, allowing the user to continue interacting while rendering the update.

React.startTransition does not provide an isPending flag. To track the pending status of a transition see React.useTransition.