Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

HTMLElement.onload — tratar o carregamento de um recurso

HTMLElement.onload é a propriedade do processador do evento load. Atribui-lhe uma função para reagir ao carregamento do recurso de um elemento, como uma imagem. Uma atribuição posterior substitui a função anterior, enquanto null desativa esse processador.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

element.onload = function (event) { /* handle load */ };
element.onload = null;

HTMLElement.onload é a propriedade do processador do evento load, disponibilizada pelo mecanismo GlobalEventHandlers. É uma interface do navegador definida por HTML, não uma funcionalidade do próprio ECMAScript; a presença do Node.js 24 não comprova a sua disponibilidade.

Numa imagem, load significa que o recurso foi carregado com êxito. Define a função antes de atribuíres src, para não perderes o evento. A existência desta propriedade num elemento não significa que todos os elementos emitam automaticamente load. Os elementos body e frameset são um caso especial: o respetivo onload trata o evento de Window, e não o carregamento de um recurso separado do elemento.

Atribuir uma nova função substitui a anterior; null remove esse processador. Usa addEventListener('load', handler) para subscrições independentes. No exemplo, a imagem mede 1x1 e a função recebe event. A função normal usa this para se referir à imagem.

Exemplos

(() => {
  const image = document.createElement('img');
  image.onload = function (event) {
    console.log(event.type + ': ' + this.naturalWidth + 'x' + this.naturalHeight);
    this.onload = null;
  };
  image.onerror = () => console.log('error');
  image.src = 'data:image/svg+xml,' + encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>'
  );
})();

Resultado

load: 1x1

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes