CKTIS / JavaScript
HTMLImageElement: načítání obrázků, rozměry a stav complete
HTMLImageElement umožňuje nastavit zdroj obrázku a alternativní text, zpracovat události load a error a číst přirozené rozměry. Vlastnost complete nedokazuje úspěšné načtení: hodnotu true má také u poškozeného obrázku nebo prvku bez zdroje.
Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
const image = new Image();
image.alt = description;
image.addEventListener("load", onLoad, { once: true });
image.addEventListener("error", onError, { once: true });
image.src = url;
// Read: image.naturalWidth, image.naturalHeight, image.completeHTMLImageElement představuje obrazový prvek; new Image() vytvoří takový prvek, aniž by ho připojil k dokumentu. HTMLImageElement.src nastavuje URL zdroje a HTMLImageElement.alt alternativní text. U informativního obrázku uveď smysluplný popis; u dekorativního použij prázdný alt.
HTMLImageElement.load a HTMLImageElement.error zde označují události load a error, nikoli volatelné metody. První signalizuje úspěšné načtení, druhá chybu při načítání nebo vykreslování. Oba posluchače zaregistruj pomocí addEventListener před přiřazením src, aby rychlé načtení neskončilo dřív, než je zaregistruješ.
Vlastnosti pouze pro čtení HTMLImageElement.naturalWidth a HTMLImageElement.naturalHeight udávají hustotně korigované přirozené rozměry v CSS pixelech, nikoli velikost určenou styly. Nedostupný rozměr má hodnotu 0. HTMLImageElement.complete je pouze pro čtení: může mít hodnotu true po úspěchu, po chybě, bez zdroje nebo s prázdným src. Samotné complete tedy úspěch nedokazuje.
U existujícího prvku nejprve zaregistruj oba posluchače a pak ověř aktuální stav. Nemá-li prvek zdroj, zpracuj tento případ zvlášť, ale pamatuj, že zdroj může poskytnout nadřazený prvek picture. Pokud má prvek zdroj a complete má hodnotu false, počkej na load nebo error. Podmínka complete && naturalWidth > 0 nedokazuje úspěšné načtení. U prvku img bez vlastních atributů src a srcset může mít complete hodnotu true, i když se obrázek z nadřazeného prvku picture ještě načítá. naturalWidth může nabýt kladné hodnoty, jakmile jsou k dispozici rozměry, tedy ještě před dokončením načítání. Pokud platí complete && naturalWidth === 0, z těchto vlastností výsledek také nepoznáš: i obrázek bez vlastní šířky se může úspěšně načíst. Nepovažuj ho proto za nedostupný. Pokud máš pro aktuální požadavek na obrázek zaznamenanou událost load nebo error, použij tento výsledek. Nově zaregistrovaný posluchač nezachytí událost, která už nastala. Zajisti, aby kontrola stavu a posluchače nezpracovali tentýž výsledek dvakrát.
Jde o rozhraní prohlížeče definované standardem HTML, nikoli o funkci konkrétního vydání ECMAScriptu. Popsané základní mechanismy jsou široce podporovány; přítomnost Node 24 v repozitáři nedokazuje dostupnost rozhraní prohlížeče. Příklad vytvoří dekorativní obrázek SVG v paměti, aniž by ho připojil k dokumentu. SVG má výslovně zadanou kladnou šířku a výšku, takže příklad neukazuje úspěšné načtení obrázku bez vlastní šířky.
Příklady
(() => {
const image = new Image();
image.alt = "";
image.addEventListener("load", () => {
console.log(`load: ${image.naturalWidth}x${image.naturalHeight}; complete=${image.complete}`);
}, { once: true });
image.addEventListener("error", () => {
console.log("error: image unavailable");
}, { once: true });
const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="2" height="3"><rect width="2" height="3" fill="blue"/></svg>';
image.src = `data:image/svg+xml,${encodeURIComponent(svg)}`;
})();Výsledek
load: 2x3; complete=true
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.