HTMLImageElement

Базовая линия Широко доступно *

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузера. Она доступна в браузерах с июля 2015 года.

* Некоторые части этой функции могут иметь различный уровень поддержки.

Интерфейс HTMLImageElement представляет собой элемент HTML <img>, предоставляя свойства и методы для управления элементами изображения.

Конструктор

Image(): Конструктор Image() создает и возвращает новый объект HTMLImageElement, представляющий элемент HTML <img>, который не привязан к дереву DOM. Он принимает необязательные параметры ширины и высоты. Если вызван без параметров, new Image() эквивалентен вызову document.createElement('img').

Свойства экземпляра

Наследует свойства от родителя, HTMLElement.

HTMLImageElement.alt: Строка, отражающая атрибут alt HTML, указывающая альтернативное содержимое, которое будет отображено, если изображение не загружено.
HTMLImageElement.attributionSrc Безопасный контекст Экспериментальная: Получает и устанавливает атрибут attributionsrc элемента <img> программно, отражая значение этого атрибута. attributionsrc указывает, что вы хотите, чтобы браузер отправлял заголовок Attribution-Reporting-Eligible вместе с запросом на изображение. На стороне сервера это используется для отправки заголовка Attribution-Reporting-Register-Source или Attribution-Reporting-Register-Trigger в ответе, для регистрации источника атрибуции на основе изображения или триггера атрибуции соответственно.
HTMLImageElement.complete Только для чтения: Возвращает логическое значение, равное true если браузер завершил загрузку изображения, независимо от успеха. Это также означает, что это значение равно true если у изображения нет значения src, указывающего на изображение для загрузки.
HTMLImageElement.crossOrigin: Строка, определяющая настройку CORS для этого элемента изображения. Подробнее см. атрибуты настроек CORS. Может быть null если CORS не используется.
HTMLImageElement.currentSrc Только для чтения: Возвращает строку, представляющую URL, с которого было загружено текущее отображаемое изображение. Это может меняться по мере изменения изображения в зависимости от условий, указанных любыми средствами запроса.
HTMLImageElement.decoding: Необязательная строка, представляющая подсказку для браузера, как следует декодировать изображение. Если это значение указано, оно должно быть одним из допустимых значений: sync для синхронной декодировки, async для асинхронной декодировки или auto для указания отсутствия предпочтения (по умолчанию). Подробности о последствиях значений этого свойства см. на странице decoding.
HTMLImageElement.fetchPriority: Необязательная строка, представляющая подсказку для браузера о том, как следует определить приоритет получения изображения по отношению к другим изображениям. Если это значение указано, оно должно быть одним из допустимых значений: high для получения высокого приоритета, low для получения низкого приоритета или auto для указания отсутствия предпочтения (по умолчанию).
HTMLImageElement.height: Целочисленное значение, отражающее атрибут height HTML, указывающее рендерную высоту изображения в пикселях CSS.
HTMLImageElement.isMap: Логическое значение, отражающее атрибут ismap HTML, указывающее, что изображение является частью карты изображений на стороне сервера. Это отличается от карты изображений на стороне клиента, заданной с помощью элемента <img> и соответствующего <map>, содержащего элементы <area>, указывающие на нажимаемые области на изображении. Изображение должно быть включено в элемент <a>; подробнее см. на странице ismap.
HTMLImageElement.loading: Строка, дающая подсказку браузеру, используемая для оптимизации загрузки документа, определяя, следует ли загружать изображение немедленно (eager) или по мере необходимости (lazy).
HTMLImageElement.naturalHeight Только для чтения: Возвращает целочисленное значение, представляющее внутреннюю высоту изображения в пикселях CSS, если оно доступно; в противном случае отображается 0. Это высота изображения, если оно отображается в натуральную величину.
HTMLImageElement.naturalWidth Только для чтения: Целочисленное значение, представляющее внутреннюю ширину изображения в пикселях CSS, если оно доступно; в противном случае отображается 0. Это ширина изображения, если оно отображается в натуральную величину.
HTMLImageElement.referrerPolicy: Строка, отражающая атрибут referrerpolicy HTML, который сообщает агенту пользователя, как определить, какой реферер использовать для получения изображения. Подробнее о возможных значениях этой строки см. в этой статье.
HTMLImageElement.sizes: Строка, отражающая атрибут sizes HTML. Эта строка определяет список разделенных запятыми условных размеров изображения; то есть для данного размера экрана используется определённый размер изображения. Подробности о формате этой строки см. на странице sizes.
HTMLImageElement.src: Строка, отражающая атрибут src HTML, содержащий полный URL изображения, включая базовый URI. Вы можете загрузить другое изображение в элемент, изменив URL в атрибуте src.
HTMLImageElement.srcset: Строка, отражающая атрибут srcset HTML. Указывает список кандидатов на изображение, разделенных запятыми (',', U+002C COMMA). Каждый кандидат — это URL, за которым следует пробел и специально отформатированная строка, указывающая размер изображения. Размер может быть указан либо шириной, либо кратным размером. Подробности о формате подстроки размера см. на странице srcset.
HTMLImageElement.useMap: Строка, отражающая атрибут usemap HTML, содержащая локальный URL страницы элемента <map>, описывающего карту изображений для использования. Локальный URL страницы — это символ решетки (#) (#) и ID элемента <map>, например #my-map-element. В свою очередь, <map> содержит элементы <area>, указывающие на нажимаемые области на изображении.
HTMLImageElement.width: Целочисленное значение, отражающее атрибут width HTML, указывающее рендерную ширину изображения в пикселях CSS.
HTMLImageElement.x Только для чтения: Целое число, указывающее горизонтальный отступ левой границы области расположения изображения CSS относительно начала блока содержимого элемента <html>.
HTMLImageElement.y Только для чтения: Целое число, указывающее вертикальный отступ верхней границы области расположения изображения CSS относительно начала блока содержимого элемента <html>.

Устаревшие свойства

HTMLImageElement.align Устаревший: Строка, указывающая выравнивание изображения относительно окружающего контекста. Возможные значения: "left", "right", "justify", и "center". Эта функция устарела; для задания выравнивания используйте CSS (например, text-align, который работает с изображениями, несмотря на своё название).
HTMLImageElement.border Устаревший: Строка, определяющая ширину границы вокруг изображения. Данная функция устарела; используйте свойство CSS border вместо неё.
HTMLImageElement.hspace Устаревший: Целочисленное значение, определяющее количество пикселей, которые необходимо оставить пустого места слева и справа от изображения.
HTMLImageElement.longDesc Устаревший: Строка, содержащая URL, по которому можно найти подробное описание содержимого изображения. Это используется для автоматической трансформации изображения в гиперссылку. В современном HTML необходимо поместить <img> внутри тега <a> для определения гиперссылки.
HTMLImageElement.name Устаревший: Строка, представляющая имя элемента.
HTMLImageElement.vspace Устаревший: Целочисленное значение, определяющее количество пикселей пустого пространства, которое необходимо оставить сверху и снизу от изображения.

Методы экземпляра

Наследует методы от родительского класса, HTMLElement.

HTMLImageElement.decode(): Возвращает Promise, который разрешается, когда изображение декодировано и безопасно для добавления в DOM. Это предотвращает приостановку рендеринга следующей кадра для декодирования изображения, что может произойти, если не декодированное изображение добавить в DOM.

Ошибки

Если при загрузке или рендеринге изображения произошла ошибка, и обработчик события onerror был сконфигурирован для обработки события error, этот обработчик будет вызван. Это может произойти в ряде ситуаций, включая:

Атрибут src пустой или null.
Указанный src URL совпадает с URL текущей страницы пользователя.
Указанное изображение повреждено каким-либо образом, что предотвращает его загрузку.
Метаданные указанного изображения повреждены таким образом, что невозможно получить его размеры, и размеры не были указаны в атрибутах элемента <img>.
Указанное изображение в формате, не поддерживаемом пользовательским агентом.

Пример

const img1 = new Image(); // Image constructor
img1.src = "image1.png";
img1.alt = "alt";
document.body.appendChild(img1);

const img2 = document.createElement("img"); // Use DOM HTMLImageElement
img2.src = "image2.jpg";
img2.alt = "alt text";
document.body.appendChild(img2);

// using first image in the document
alert(document.images[0].src);

Спецификации

Спецификация
HTML # htmlimageelement

Совместимость с браузерами

	Рабочий стол					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на IOS	Samsung Internet	WebView Android

`Image`	1	12	1	8	1	18	4	10.1	1	1.0	4.4
`HTMLImageElement`	1	12	1	8	1	18	4	10.1	1	1.0	4.4
`align`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`alt`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`attributionSrc`	125	125	Нет	111	Нет	125	Нет	83	Нет	27.0	125
`border`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`complete`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`crossOrigin`	13	12	8	≤12.1	6	18	8	≤12.1	6	1.0	4.4
`currentSrc`	38	13	38	25	9.1	38	38	25	9.3	3.0	38
`decode`	64	79	68	51	11.1	64	68	47	11.3	9.0	64
`decoding`	65	79	63	52	11.1	65	63	47	11.3	9.0	65
`fetchPriority`	102101–102	102101–102	132	8887–88	17.2	102101–102	132	70	17.2	19.0	102101–102
`height`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`hspace`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`isMap`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`loading`	77	79	75	64	15.4	77	79	55	15.4	12.0	77
`longDesc`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`lowsrc`	1	12	1	≤12.1	3	18	4	≤12.1	2	1.0	4.4
`name`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`naturalHeight`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`naturalWidth`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`referrerPolicy`	5251–52	79	50	3938–39	14	5251–52	50	41	14	6.05.0–6.0	5251–52
`sharedStorageWritable`	124	124	Нет	110	Нет	124	Нет	82	Нет	27.0	124
`sizes`	38	13	38	25	9.1	38	38	25	9.3	3.0	38
`src`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`srcset`	34	12	38	21	8	34	38	21	8	2.0	37

`useMap`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`vspace`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`width`	1	12	1	≤12.1	3	18	4	≤12.1	1	1.0	4.4
`x`	1	12	141–7	≤12.1	3	18	144–7	≤12.1	1	1.0	4.4
`y`	1	12	141–7	≤12.1	3	18	144–7	≤12.1	1	1.0	4.4

См. также

Элемент HTML, реализующий этот интерфейс: <img>

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement