Chargement de ressources JavaScript : onload et onerror

Les ressources externes — images, scripts, feuilles de style, iframes — se chargent de manière asynchrone et indépendamment du JavaScript qui les demande. Le navigateur lance le téléchargement et votre code continue de s'exécuter ; la ressource peut ne pas être prête pendant des millisecondes, voire des secondes. Pour savoir quand une ressource est prête (ou qu'elle a échoué), chaque élément chargeable déclenche deux événements : load en cas de succès et error en cas d'échec. Cette page montre comment les utiliser avec les propriétés de gestionnaire onload / onerror.

Cela est étroitement lié au cycle de vie de la page couvert dans DOMContentLoaded, load, beforeunload, unload, et aux stratégies de chargement dans Scripts : async, defer.

Gestion du chargement des ressources avec l'événement onload

Qu'est-ce que l'événement onload ?

L'événement load se déclenche sur un élément lorsque sa ressource a entièrement fini de se télécharger et est prête à être utilisée. Vous pouvez l'écouter de deux façons équivalentes :

// 1. Handler property (only one handler allowed)
img.onload = () => { /* ... */ };

// 2. addEventListener (multiple handlers allowed)
img.addEventListener('load', () => { /* ... */ });

La forme avec propriété (onload) est pratique mais ne stocke qu'un seul gestionnaire — en assigner un nouveau écrase l'ancien. Préférez addEventListener('load', ...) lorsque plus d'un bout de code s'intéresse à la même ressource.

Un piège important : pour une <img>, l'événement load ne couvre que les octets de cette seule image. Ce n'est pas le window.onload à l'échelle de la page, qui attend toutes les ressources. Ne les confondez pas.

Exemple : afficher une image après son chargement complet

Pour illustrer cela, imaginez un scénario où vous souhaitez afficher une image uniquement après qu'elle soit entièrement chargée, afin d'éviter d'afficher une image partielle ou cassée.

<div>Here you see the w3docs logo when the page is loaded.</div>
<br />
<div id="imageContainer" style="background-color: grey;"></div>
<script>
document.addEventListener('DOMContentLoaded', function() {
    var img = new Image();
    img.onload = function() {
        document.getElementById('imageContainer').appendChild(img);
    };
    img.src = 'https://www.w3docs.com/build/images/logo-color-w3.png';
});
</script>

Ce script garantit que l'image n'est ajoutée au div #imageContainer qu'après son chargement complet, améliorant l'expérience utilisateur en évitant l'affichage d'une image incomplète.

Utilisation de l'événement onerror pour la gestion des erreurs

Qu'est-ce que l'événement onerror ?

L'événement onerror est essentiel pour un développement web robuste. Il se déclenche lorsqu'une erreur survient lors du chargement d'une ressource externe, comme un script ou une image. Cet événement est crucial pour gérer les erreurs de manière élégante et garantir que l'expérience utilisateur reste ininterrompue.

Exemple : gestion des erreurs pour un chargement d'image échoué

Imaginez un scénario où une image ne parvient pas à se charger en raison d'un lien cassé ou d'un problème de serveur. En utilisant l'événement onerror, vous pouvez fournir une solution de repli ou informer l'utilisateur. Dans l'exemple suivant, le src cassé déclenche le gestionnaire d'erreurs dès que la page s'exécute, car le lien de l'image ne pointe pas vers un fichier réel.

Une ressource déclenche soit load soit error, jamais les deux. Vous pouvez donc attacher des gestionnaires pour chacun et compter sur le fait qu'un seul s'exécutera.

<div>If there was no error, you could see an image below. But it's a broken link!</div>
<br />
<div id="imageContainer" style="background-color: grey;"></div>
<script>
const img = new Image();
const imageContainer = document.getElementById('imageContainer');
img.onerror = function() {
    imageContainer.innerHTML = 'An error happened.';
};
img.onload = function() {
    imageContainer.appendChild(img);
};
img.src = 'https://www.w3docs.com/build/images/broken-link.png';
</script>

Dans cet exemple, si l'image ne parvient pas à se charger, le conteneur affiche un message de repli à la place d'une icône d'image cassée, gérant l'erreur de façon transparente.

Exemple : chargement d'un script ou d'une feuille de style

Le même schéma s'applique aux éléments <script> et <link>. Vous pouvez les créer dynamiquement et attacher des gestionnaires onload/onerror :

<script>
function loadScript(url) {
    const script = document.createElement('script');
    script.src = url;
    script.onload = () => console.log('Script loaded successfully');
    script.onerror = () => console.error('Failed to load script');
    document.head.appendChild(script);
}
loadScript('https://example.com/app.js');

function loadStylesheet(url) {
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.href = url;
    link.onload = () => console.log('Stylesheet loaded successfully');
    link.onerror = () => console.error('Failed to load stylesheet');
    document.head.appendChild(link);
}
loadStylesheet('https://example.com/styles.css');
</script>

Les scripts créés dynamiquement se comportent comme des scripts async : ils se téléchargent en parallèle et s'exécutent dès qu'ils arrivent, de sorte que l'ordre de chargement n'est pas garanti. Si un script dépend d'un autre, enchaînez-les à l'intérieur du onload du premier script.

Exemple : encapsuler load/error dans une Promise

Pour du code moderne, encapsuler les deux événements dans une Promise vous offre l'ergonomie de async/await et un seul endroit pour gérer les échecs :

function loadScript(src) {
  return new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = src;
    script.onload = () => resolve(script);
    script.onerror = () => reject(new Error(`Failed to load: ${src}`));
    document.head.append(script);
  });
}

// Usage
loadScript('https://example.com/app.js')
  .then(() => console.log('Ready to use the script'))
  .catch((err) => console.error(err.message));

Étant donné que load et error s'excluent mutuellement, la Promise se règle exactement une fois — soit résolue, soit rejetée.

Optimisation des performances web grâce à la gestion des événements

L'optimisation des performances web implique de gérer les séquences de chargement des ressources et de gérer les échecs de manière élégante. Les événements onload et onerror sont particulièrement utiles pour l'injection dynamique de ressources. Au lieu de coder en dur toutes les ressources dans le HTML, vous pouvez charger les ressources non critiques à la demande. Lorsqu'une ressource ne parvient pas à se charger, l'événement onerror se déclenche, vous permettant d'implémenter une logique de repli — comme remplacer une image cassée par un espace réservé ou réessayer une requête de script échouée. En combinant ces événements avec le rendu progressif, vous vous assurez que le contenu critique apparaît immédiatement tandis que les ressources secondaires se chargent en arrière-plan, maintenant une expérience utilisateur fluide même dans de mauvaises conditions réseau.

Conclusion

Comprendre et implémenter les événements onload et onerror en JavaScript est fondamental pour tout développeur web cherchant à améliorer la fiabilité et les performances de ses applications web. En utilisant efficacement ces événements, les développeurs peuvent s'assurer que les ressources sont gérées efficacement, améliorant à la fois les performances et l'expérience utilisateur de leurs sites web. Les exemples fournis constituent un point de départ pour implémenter ces techniques dans divers scénarios, favorisant une compréhension approfondie et la maîtrise du chargement des ressources en JavaScript.

Pratique