Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Eventos `load` y `error` de una imagen

Gestiona el éxito y el fallo de carga en el propio elemento de imagen. Registra los dos manejadores antes de asignar `src` y no interpretes `complete` como prueba de éxito.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

const image = new Image();
image.addEventListener("load", onLoad);
image.addEventListener("error", onError);
image.src = url;

// Alternative to addEventListener():
// image.onload = onLoad;
// image.onerror = onError;

new Image() crea un HTMLImageElement, es decir, un elemento <img> que puede cargar una imagen sin insertarse en el documento. Es una API del navegador, no parte de ECMAScript 2024. El navegador dispara load en el elemento si el recurso se carga correctamente y error si no puede cargarlo o utilizarlo, por ejemplo, porque la URL es inaccesible o los datos de imagen no son válidos. El evento error de una imagen no es una excepción lanzada en JavaScript ni una respuesta con un código de estado HTTP.

Escucha los eventos en la propia imagen: ninguno se propaga por burbujeo y ninguno se puede cancelar. Registra ambos manejadores con addEventListener() antes de asignar src. También puedes usar onload y onerror; una nueva asignación sustituye el manejador de esa propiedad. Leer src devuelve una URL, no el resultado de la carga ni una Promise.

Si una imagen existente ya disparó un evento, un nuevo listener no lo recibirá retroactivamente. complete no basta para confirmar el éxito: también puede valer true si la imagen está dañada o no se ha indicado un origen. Si esperas una imagen con anchura intrínseca positiva, image.complete && image.naturalWidth > 0 sirve para comprobar si ya está disponible.

load no significa que la imagen ya se haya pintado. Si necesitas esperar a que se decodifique antes de insertarla en el documento, usa await image.decode() y gestiona el rechazo de la promesa. Cargar una imagen de otro origen no te permite por sí solo leer sus píxeles desde un canvas; siguen aplicándose las restricciones de CORS.

Ejemplos

<!doctype html>
<meta charset="utf-8">
<title>Image load and error events</title>
<script>
(async () => {
  function imageOutcome(url) {
    return new Promise((resolve) => {
      const image = new Image();
      function finish(event) {
        image.removeEventListener("load", finish);
        image.removeEventListener("error", finish);
        resolve(event.type);
      }
      image.addEventListener("load", finish);
      image.addEventListener("error", finish);
      image.src = url;
    });
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><rect width="1" height="1"/></svg>';
  const dataURL = (text) => `data:image/svg+xml,${encodeURIComponent(text)}`;
  console.log(await imageOutcome(dataURL(svg)));
  console.log(await imageOutcome(dataURL("not an SVG")));
})();
</script>

Resultado

load
error

Guarda el ejemplo como archivo `.html`, ábrelo en un navegador que permita imágenes `data:` en esa página y consulta la consola del navegador. Sin contactar con un servidor externo, el código prueba primero un SVG válido y luego datos de imagen no válidos. Usa una imagen distinta para cada intento y retira ambos listeners al recibir el resultado. Los mensajes esperados son `load` y después `error`.

Lecciones relacionadas

  • JavaScript · Lección 33 · Avanzado · Versión: 4

Fuentes