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

CKTIS / JavaScript

Imágenes en JavaScript: `src`, `alt`, `load` y `error`

Define la URL y el texto alternativo de una imagen, y responde al éxito o al fallo de la carga con eventos del elemento.

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

Sintaxis

const img = new Image();
img.alt = text;
img.addEventListener("load", onLoad);
img.addEventListener("error", onError);

// To use handler properties, replace the two listener registrations above with:
// img.onload = onLoad;
// img.onerror = onError;

img.src = url;

new Image() crea un elemento img de tipo HTMLImageElement que inicialmente está fuera del árbol del documento. Es una API de la plataforma web, no de ECMAScript 2024. El entorno de ejecución debe proporcionarla.

img.src es una propiedad de tipo cadena que refleja el atributo src. Al asignarle un valor se inicia el procesamiento asíncrono de la fuente, aunque el elemento no se haya insertado en el documento. Al leer img.src, una URL relativa válida se resuelve con respecto a la URL base del documento; img.getAttribute("src") devuelve el valor almacenado del atributo. Con imágenes adaptables, consulta img.currentSrc para saber qué URL ha seleccionado el navegador.

img.alt refleja el atributo alt. Escribe un texto que transmita el significado o la función de la imagen en su contexto a quien no pueda verla. Si es puramente decorativa, usa alt = "" en vez de omitir el atributo. alt no es la URL de una imagen de sustitución.

load indica que la imagen se ha cargado correctamente; error indica que el recurso seleccionado no se ha podido cargar o utilizar. Son eventos del elemento, no métodos ni excepciones que capture un try...catch alrededor de la asignación a src. Registra ambos escuchadores antes de asignar src. También puedes asignar controladores a onload y onerror; una nueva asignación sustituye al controlador de esa propiedad.

Ejemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Image load and error events</title>
</head>
<body>
<script>
(async () => {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><circle cx="5" cy="5" r="5" fill="blue"/></svg>';
  const valid = 'data:image/svg+xml,' + encodeURIComponent(svg);
  const invalid = 'data:image/svg+xml,not-an-svg';

  function reportImage(url) {
    return new Promise((resolve) => {
      const img = new Image();
      img.alt = 'Blue dot';
      const report = (event) => {
        console.log(`${event.type}: ${img.alt}`);
        resolve();
      };
      img.addEventListener('load', report, { once: true });
      img.addEventListener('error', report, { once: true });
      img.src = url;
    });
  }

  await reportImage(valid);
  await reportImage(invalid);
})();
</script>
</body>
</html>

Resultado

load: Blue dot
error: Blue dot

Guarda el ejemplo como archivo HTML, ábrelo en un navegador y consulta el resultado en la consola de desarrollador. El código prueba primero un SVG válido y luego datos de imagen no válidos, sin peticiones de red. Cada línea muestra el evento y el valor de `alt`, que no cambia; no muestra cómo presenta el navegador el texto alternativo. Si la política de seguridad de contenido (CSP) bloquea las imágenes `data:`, la primera prueba también puede disparar `error`.

Lecciones relacionadas

  • JavaScript · Lección 30 · Intermedio · Versión: 3

Fuentes