Référence de l’API
Fonctions

preload - Cette fonctionnalité est disponible dans le dernier Canary

Canary (fonctionnalité expérimentale)

La fonction preload n’est actuellement disponible que sur les canaux de livraison Canary et Expérimental de React. Apprenez-en davantage sur les canaux de livraison React.

Remarque

Les frameworks basés sur React s’occupent fréquemment pour vous du chargement des ressources, de sorte que vous n’aurez peut-être pas besoin d’appeler ces API vous-même. Consultez la documentation de votre framework pour en savoir plus à ce sujet.

preload vous permet de charger en avance une ressource telle qu’une feuille de styles, une fonte ou un script extérieurs que vous avez l’intention d’utiliser.

preload("https://example.com/font.woff2", { as: "font" });

Référence

preload(href, options)

Pour précharger une ressource, appelez la fonction preload de react-dom.

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/font.woff2", { as: "font" });
  // ...
}

Voir d’autres exemples plus bas.

La fonction preload suggère au navigateur de commencer à télécharger une ressource donnée, ce qui peut faire gagner du temps.

Paramètres

  • href : une chaîne de caractères. L’URL de la ressource que vous souhaitez télécharger.
  • options : un objet. Il contient les propriétés suivantes :
    • as : une chaîne de caractères obligatoire. Le type de la ressource. Les valeurs possibles sont audio, document, embed, fetch, font, image, object, script, style, track, video et worker.
    • precedence : une chaîne de caractères. Indique à React où placer le nœud DOM <style> par rapport aux autres présents dans le <head> du document, ce qui détermine quelle feuille de styles a priorité sur quelle autre. La valeur peut être (par ordre de précédence) "reset", "low", "medium" ou "high".
    • crossOrigin : une chaîne de caractères. La politique CORS à utiliser. Les valeurs possibles sont anonymous et use-credentials. Elle est obligatoire lorsque as vaut "fetch".
    • referrerPolicy : une chaîne de caractères. L’en-tête Referrer à envoyer lors du chargement. Les valeurs possibles sont no-referrer-when-downgrade (par défaut), no-referrer, origin, origin-when-cross-origin ou unsafe-url.
    • integrity : une chaîne de caractères. Une empreinte cryptographique de la ressource afin de vérifier son authenticité.
    • type : une chaîne de caractères. Le type MIME de la ressource liée.
    • nonce : une chaîne de caractères. Un nonce cryptographique autorisant la ressource dans le cadre d’une Politique de Sécurité de Contenu (CSP) stricte.
    • fetchPriority : une chaîne de caractères. Suggère une priorité relative pour le chargement de la ressource. Les valeurs possibles sont auto (par défaut), high ou low.
    • imageSrcSet : une chaîne de caractères. À n’utiliser que pour as: "image". Indique le jeu de sources de l’image.
    • imageSizes : une chaîne de caractères. À n’utiliser que pour as: "image". Indique les tailles de l’image.

Valeur renvoyée

preload ne renvoie rien.

Limitations

  • Plusieurs appels équivalents à preload ont le même effet qu’un unique appel. Des appels à preload sont considérés équivalents selon les règles que voici :
    • Deux appels sont équivalents s’ils ont le même href, sauf si :
    • L’option as vaut image, auquel cas les deux appels sont équivalents s’ils ont les mêmes href, imageSrcSet et imageSizes.
  • Côté client, vous pouvez appeler preload n’importe où : lors du rendu d’un composant, dans un Effet, dans un gestionnaire d’événement, etc.
  • Lors d’un rendu côté serveur ou du rendu de Composants Serveur, preload n’a d’effet que si vous l’appelez lors du rendu d’un composant ou dans une fonction asynchrone issue du rendu d’un composant. Tout autre appel sera ignoré.

Utilisation

Précharger lors du rendu

Appelez preload lors du rendu d’un composant si vous savez que ses enfants auront besoin de charger une ressource spécifique.

Exemples de préchargement

Exemple 1 sur 4 ·
Précharger un script 

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/script.js", { as: "script" });
  return ...;
}

Si vous souhaitez que le navigateur évalue la ressource immédiatement après chargement (plutôt que simplement le charger), utilisez plutôt preinit. Si vous souhaitez charger un module ESM, utilisez preloadModule.

Précharger dans un gestionnaire d’événement

Appelez preload depuis un gestionnaire d’événement avant de passer à une page ou un état qui auront besoin de ressources extérieures. Ça permet de déclencher le processus plus tôt que si vous l’appeliez au sein de la nouvelle page ou suite au nouvel état.

import { preload } from 'react-dom';

function CallToAction() {
  const onClick = () => {
    preload("https://example.com/wizardStyles.css", { as: "style" });
    startWizard();
  }
  return (
    <button onClick={onClick}>Démarrer l’assistant</button>
  );
}
PrécédentpreinitModule
SuivantpreloadModule