CKTIS / JavaScript
HTMLImageElement: ładowanie obrazu, wymiary i stan complete
HTMLImageElement pozwala ustawić źródło i tekst alternatywny obrazu, obsłużyć zdarzenia load oraz error i odczytać naturalne wymiary. Właściwość complete nie potwierdza sukcesu: ma wartość true także dla uszkodzonego obrazu lub elementu bez źródła.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
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 reprezentuje element obrazu; new Image() tworzy go bez dołączania do dokumentu. HTMLImageElement.src ustawia URL zasobu, a HTMLImageElement.alt — tekst alternatywny. Dla obrazu niosącego informację podaj znaczący opis; pusty alt stosuj dla obrazu dekoracyjnego.
HTMLImageElement.load i HTMLImageElement.error oznaczają tutaj zdarzenia load oraz error, nie metody do wywołania. Pierwsze sygnalizuje pomyślne załadowanie, drugie błąd ładowania lub renderowania. Zarejestruj oba nasłuchiwania przez addEventListener przed przypisaniem src, aby nie przegapić szybkiego zakończenia ładowania.
Właściwości tylko do odczytu HTMLImageElement.naturalWidth i HTMLImageElement.naturalHeight podają wewnętrzne wymiary skorygowane o gęstość, w pikselach CSS, a nie rozmiar narzucony stylami. Niedostępny wymiar ma wartość 0. HTMLImageElement.complete jest tylko do odczytu: może wynosić true po sukcesie, po błędzie, bez źródła albo przy pustym src. Samo complete nie dowodzi więc sukcesu.
W przypadku istniejącego elementu najpierw zarejestruj nasłuchiwanie obu zdarzeń, a potem sprawdź bieżący stan. Jeśli element nie ma źródła, obsłuż ten przypadek osobno, ale pamiętaj, że źródło może pochodzić z nadrzędnego elementu picture. Jeśli element ma źródło i complete ma wartość false, poczekaj na load lub error. Warunek complete && naturalWidth > 0 nie potwierdza pomyślnego załadowania. Gdy img nie ma własnych atrybutów src ani srcset, complete może mieć wartość true, mimo że obraz ze źródła wskazanego przez picture nadal się ładuje. naturalWidth może mieć wartość dodatnią, gdy tylko wymiary staną się dostępne, jeszcze przed zakończeniem ładowania. Jeśli complete && naturalWidth === 0, na podstawie tych właściwości również nie da się rozstrzygnąć wyniku: obraz bez własnej szerokości może się załadować poprawnie. Nie uznawaj go za niedostępny na tej podstawie. Jeśli masz zapisany wynik zdarzenia load lub error dla bieżącego żądania obrazu, użyj go. Nowo zarejestrowane nasłuchiwanie nie przechwyci zdarzenia, które już wystąpiło. Zadbaj o to, by sprawdzenie stanu i obsługa zdarzenia nie obsłużyły tego samego wyniku dwukrotnie.
To API przeglądarki zdefiniowane przez HTML, a nie funkcja konkretnego wydania ECMAScript. Opisane podstawowe mechanizmy są szeroko obsługiwane; obecność Node 24 w repozytorium nie dowodzi dostępności API przeglądarki. Przykład tworzy dekoracyjny obraz SVG w pamięci i nie dołącza go do dokumentu. SVG ma jawnie określoną dodatnią szerokość i wysokość, więc przykład nie pokazuje pomyślnego ładowania obrazu bez własnej szerokości.
Przykłady
(() => {
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)}`;
})();Wynik
load: 2x3; complete=true
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.