Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

CKTIS / JavaScript

HTMLImageElement: načítanie obrázkov, rozmery a stav complete

HTMLImageElement umožňuje nastaviť zdroj obrázka a alternatívny text, spracovať udalosti load a error a čítať prirodzené rozmery. Vlastnosť complete nedokazuje úspešné načítanie: hodnotu true má aj pri poškodenom obrázku alebo prvku bez zdroja.

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

Syntax

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

HTMLImageElement predstavuje obrazový prvok; new Image() vytvorí takýto prvok bez jeho pripojenia k dokumentu. HTMLImageElement.src nastavuje URL zdroja a HTMLImageElement.alt alternatívny text. Pri informatívnom obrázku uveď zmysluplný opis; pri dekoratívnom použi prázdny alt.

HTMLImageElement.load a HTMLImageElement.error tu označujú udalosti load a error, nie volateľné metódy. Prvá signalizuje úspešné načítanie, druhá chybu pri načítaní alebo vykresľovaní. Oba poslucháče zaregistruj pomocou addEventListener pred priradením src, aby sa rýchle načítanie neskončilo skôr, než ich zaregistruješ.

Vlastnosti iba na čítanie HTMLImageElement.naturalWidth a HTMLImageElement.naturalHeight udávajú hustotne korigované prirodzené rozmery v CSS pixeloch, nie veľkosť určenú štýlmi. Nedostupný rozmer má hodnotu 0. HTMLImageElement.complete je iba na čítanie: hodnotu true môže mať po úspechu, po chybe, bez zdroja alebo s prázdnym src. Samotné complete teda úspech nedokazuje.

Pri existujúcom prvku najprv zaregistruj oba poslucháče a potom skontroluj aktuálny stav. Ak prvok nemá zdroj, spracuj tento prípad samostatne, ale pamätaj, že zdroj môže poskytnúť nadradený prvok picture. Ak má prvok zdroj a complete má hodnotu false, počkaj na load alebo error. Podmienka complete && naturalWidth > 0 nedokazuje úspešné načítanie. Pri prvku img bez vlastných atribútov src a srcset môže mať complete hodnotu true, aj keď sa obrázok z nadradeného prvku picture ešte načítava. naturalWidth môže nadobudnúť kladnú hodnotu hneď, ako sú rozmery dostupné, ešte pred dokončením načítania. Ak platí complete && naturalWidth === 0, z týchto vlastností výsledok takisto nezistíš: aj obrázok bez vlastnej šírky sa môže načítať úspešne. Nepovažuj ho preto za nedostupný. Ak máš pre aktuálnu požiadavku na obrázok zaznamenanú udalosť load alebo error, použi tento výsledok. Novo zaregistrovaný poslucháč nezachytí udalosť, ktorá už nastala. Zabezpeč, aby kontrola stavu a poslucháče nespracovali ten istý výsledok dvakrát.

Ide o rozhranie prehliadača definované štandardom HTML, nie o funkciu konkrétneho vydania ECMAScriptu. Opísané základné mechanizmy sú široko podporované; prítomnosť Node 24 v úložisku nedokazuje dostupnosť rozhrania prehliadača. Príklad vytvorí dekoratívny obrázok SVG v pamäti bez jeho pripojenia k dokumentu. SVG má výslovne určenú kladnú šírku a výšku, takže príklad neukazuje úspešné načítanie obrázka bez vlastnej šírky.

Prí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ýsledok

load: 2x3; complete=true

Zobrazený kód a uvedený výsledok boli overené v izolovanom prostredí metódou zaznamenanou v dôkaze o overení tejto presnej verzie.

Zdroje