База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

HTMLImageElement: зареждане на изображения, размери и състояние complete

HTMLImageElement позволява да зададете източника и алтернативния текст на изображение, да обработвате събитията load и error и да четете естествените размери. Свойството complete не доказва успех: то е true и за повредено изображение или елемент без източник.

Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Синтаксис

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 представлява елемент за изображение; new Image() създава такъв, без да го добавя към документа. HTMLImageElement.src задава URL адреса на ресурса, а HTMLImageElement.alt — алтернативния текст. За информативно изображение посочете смислено описание; за декоративно използвайте празен alt.

HTMLImageElement.load и HTMLImageElement.error тук означават събитията load и error, а не методи за извикване. Първото сигнализира успешно зареждане, а второто — грешка при зареждане или визуализиране. Регистрирайте и двата слушателя чрез addEventListener, преди да зададете src, за да не приключи бързото зареждане преди регистрацията.

Свойствата само за четене HTMLImageElement.naturalWidth и HTMLImageElement.naturalHeight показват коригираните спрямо плътността естествени размери в CSS пиксели, а не размера, зададен със стилове. Недостъпен размер има стойност 0. HTMLImageElement.complete е само за четене: може да е true след успех, след грешка, без източник или с празен src. Следователно само complete не доказва успех.

При съществуващ елемент първо регистрирайте и двата слушателя, а след това проверете текущото състояние. Ако елементът няма източник, обработете този случай отделно, но имайте предвид, че обхващащ елемент picture може да предостави източник. Ако елементът има източник и complete е false, изчакайте load или error. Условието complete && naturalWidth > 0 не доказва, че изображението е заредено успешно. При img без собствени атрибути src и srcset стойността на complete може да е true, докато изображението, предоставено от обхващащия го picture, все още се зарежда. naturalWidth може да има положителна стойност веднага щом размерите станат достъпни, още преди края на зареждането. Ако complete && naturalWidth === 0, тези свойства също не позволяват да определите резултата: изображение без собствена ширина може да се зареди успешно. Не го приемайте за недостъпно само на това основание. Ако сте записали събитие load или error за текущата заявка за изображението, използвайте този резултат. Новорегистриран слушател няма да получи събитие, което вече е настъпило. Не допускайте проверката на състоянието и слушателите да обработят един и същ резултат два пъти.

Това е API на браузъра, дефиниран от HTML, а не функция на конкретно издание на ECMAScript. Описаните основни механизми се поддържат широко; наличието на Node 24 в хранилище не доказва наличност на API на браузъра. Примерът създава декоративно SVG изображение в паметта, без да го добавя към документа. SVG изображението има изрично зададени положителни ширина и височина, затова примерът не показва успешно зареждане на изображение без собствена ширина.

Примери

(() => {
  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)}`;
})();

Резултат

load: 2x3; complete=true

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници