Carregamento de Recursos em JavaScript: onload e onerror

Recursos externos — imagens, scripts, folhas de estilo, iframes — são carregados de forma assíncrona e independente do JavaScript que os solicita. O navegador inicia o download e seu código continua executando; o recurso pode não estar pronto por milissegundos ou segundos. Para saber quando um recurso está pronto (ou que falhou), cada elemento carregável dispara dois eventos: load em caso de sucesso e error em caso de falha. Esta página mostra como usá-los com as propriedades de manipulador onload / onerror.

Isso está intimamente relacionado ao ciclo de vida no nível da página abordado em DOMContentLoaded, load, beforeunload, unload, e às estratégias de carregamento em Scripts: async, defer.

Tratando o Carregamento de Recursos com o Evento onload

O que é o Evento onload?

O evento load é disparado em um elemento quando seu recurso terminou de ser baixado completamente e está pronto para uso. Você pode ouvi-lo de duas formas equivalentes:

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

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

A forma de propriedade (onload) é conveniente, mas armazena apenas um único manipulador — atribuir um novo substitui o antigo. Prefira addEventListener('load', ...) quando mais de um trecho de código precisar lidar com o mesmo recurso.

Um ponto importante: para um <img>, o evento load cobre apenas os bytes daquela imagem específica. Ele não é o window.onload de toda a página, que aguarda todos os recursos. Não confunda os dois.

Exemplo: Exibindo uma Imagem Após o Carregamento Completo

Para ilustrar, considere um cenário em que você deseja exibir uma imagem apenas após ela estar completamente carregada, para evitar mostrar uma imagem parcial ou quebrada.

<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>

Este script garante que a imagem seja adicionada à div #imageContainer somente após ter sido completamente carregada, melhorando a experiência do usuário ao evitar a exibição de uma imagem incompleta.

Utilizando o Evento onerror para Tratamento de Erros

O que é o Evento onerror?

O evento onerror é essencial para o desenvolvimento web robusto. Ele é disparado quando ocorre um erro durante o carregamento de um recurso externo, como um script ou uma imagem. Este evento é fundamental para tratar erros de forma adequada e garantir que a experiência do usuário não seja interrompida.

Exemplo: Tratamento de Erro para Falha no Carregamento de uma Imagem

Considere um cenário em que uma imagem falha ao carregar devido a um link quebrado ou problema no servidor. Usando o evento onerror, você pode fornecer uma solução de fallback ou notificar o usuário. No exemplo a seguir, o src quebrado aciona o manipulador de erro assim que a página é executada, pois o link da imagem não aponta para um arquivo real.

Um recurso dispara apenas load ou error, nunca ambos. Assim, você pode anexar manipuladores para cada um e ter certeza de que apenas um será executado.

<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>

Neste exemplo, se a imagem falhar ao carregar, o contêiner exibirá uma mensagem de fallback em vez de um ícone de imagem quebrada, tratando o erro de forma transparente.

Exemplo: Carregando um Script ou Folha de Estilo

O mesmo padrão se aplica aos elementos <script> e <link>. Você pode criá-los dinamicamente e anexar manipuladores 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>

Scripts criados dinamicamente se comportam como scripts async: eles são baixados em paralelo e executados assim que chegam, portanto a ordem de carregamento não é garantida. Se um script depende de outro, encadeie-os dentro do onload do primeiro script.

Exemplo: Encapsulando load/error em uma Promise

Para código moderno, encapsular os dois eventos em uma Promise oferece ergonomia com async/await e um único lugar para tratar falhas:

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));

Como load e error são mutuamente exclusivos, a Promise é resolvida exatamente uma vez — como resolvida ou rejeitada.

Otimizando o Desempenho Web por Meio do Tratamento de Eventos

Otimizar o desempenho web envolve gerenciar sequências de carregamento de recursos e tratar falhas de forma adequada. Os eventos onload e onerror são particularmente valiosos para injeção dinâmica de recursos. Em vez de codificar todos os ativos diretamente no HTML, você pode carregar recursos não críticos sob demanda. Quando um recurso falha ao carregar, o evento onerror é disparado, permitindo implementar lógica de fallback — como substituir uma imagem quebrada por um placeholder ou tentar novamente uma requisição de script que falhou. Ao combinar esses eventos com renderização progressiva, você garante que o conteúdo crítico apareça imediatamente enquanto os ativos secundários carregam em segundo plano, mantendo uma experiência de usuário fluida mesmo em condições de rede precárias.

Conclusão

Compreender e implementar os eventos onload e onerror em JavaScript é fundamental para qualquer desenvolvedor web que busca melhorar a confiabilidade e o desempenho de suas aplicações web. Ao empregar esses eventos de forma eficaz, os desenvolvedores podem garantir que os recursos sejam gerenciados com eficiência, melhorando tanto o desempenho quanto a experiência do usuário em seus sites. Os exemplos fornecidos oferecem um ponto de partida para implementar essas técnicas em diversos cenários, promovendo uma compreensão e domínio mais profundos do carregamento de recursos em JavaScript.

Prática