Black Lives Matter. Soutenez la Equal Justice Initiative.
React
v16.13.1 LanguesGitHub

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.

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 :

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 :

Lisez React sans JSX pour plus de détails.

Transformer des éléments

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

Fragments

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

Refs

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.

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 :

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,
  [props],
  [...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.

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 :

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.

Remarque

Utiliser React.lazy avec un import() dynamique requiert une prise en charge des Promises par l’environnement JS. Vous aurez donc besoin d’un polyfill pour IE11 et inférieurs.

React.Suspense

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.

Bien que ce ne soit pas le cas pour le moment, nous prévoyons d’étendre les capacités de Suspense pour qu’il puisse gérer d’autre scénarios tel que le chargement de données. Vous pourrez en savoir plus en jetant un coup d’œil à notre feuille de route.

Remarque

React.lazy() et <React.Suspense> ne sont pas encore pris en charge par ReactDOMServer. C’est une limitation connue qui devrait être résolue à l’avenir.

Avez-vous trouvé cette page utile ?Modifier cette page