1. Web
  2. Web API
  3. HTMLImageElement

HTMLImageElement

Baseline 廣泛可用 *

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

* 此特性的某些部分可能存在不同級別的支援。

HTMLImageElement 介面表示一個 HTML <img> 元素，提供用於操作影像元素的屬性和方法。

EventTarget Node Element HTMLElement HTMLImageElement

建構函式

Image()

Image() 建構函式建立並返回一個新的 HTMLImageElement 物件，該物件表示一個未附加到任何 DOM 樹的 HTML <img> 元素。它接受可選的 width 和 height 引數。當不帶引數呼叫時，new Image() 相當於呼叫 document.createElement('img')。

例項屬性

繼承自其父級 HTMLElement 的屬性。

HTMLImageElement.alt

一個字串，反映 alt HTML 屬性，指示影像未載入時要顯示的備用內容。

HTMLImageElement.attributionSrc 安全上下文

以程式設計方式獲取和設定 <img> 元素的 attributionsrc 屬性，反映該屬性的值。attributionsrc 指定您希望瀏覽器在影像請求中傳送 Attribution-Reporting-Eligible 標頭。在伺服器端，這用於觸發在響應中傳送 Attribution-Reporting-Register-Source 或 Attribution-Reporting-Register-Trigger 標頭，以分別註冊基於影像的歸因源或歸因觸發器。

HTMLImageElement.complete 只讀

返回一個布林值，如果瀏覽器已完成獲取影像（無論成功與否），則該值為 true。這意味著如果影像沒有指示要載入影像的 src 值，則此值也為 true。

HTMLImageElement.crossOrigin

一個字串，指定此影像元素的 CORS 設定。有關詳細資訊，請參閱 CORS 設定屬性。如果未使用 CORS，則此值可能為 null。

HTMLImageElement.currentSrc 只讀

返回一個字串，表示當前顯示的影像的載入 URL。根據任何現有的 媒體查詢 的指示，當條件變化時，影像可能會隨之調整，此值也可能發生變化。

HTMLImageElement.decoding

一個可選的字串，表示瀏覽器應該如何解碼影像的提示。如果提供了此值，則它必須是允許的可能值之一：sync 同步解碼影像，async 非同步解碼影像，或 auto 表示沒有偏好（這是預設值）。有關此屬性值的含義的詳細資訊，請閱讀 decoding 頁面。

HTMLImageElement.fetchPriority

一個可選的字串，表示瀏覽器應該如何相對於其他影像優先獲取影像的提示。如果提供了此值，則它必須是允許的可能值之一：high 以高優先順序獲取，low 以低優先順序獲取，或 auto 表示沒有偏好（這是預設值）。

HTMLImageElement.height

一個整數值，反映 height HTML 屬性，指示影像在 CSS 畫素中的渲染高度。

HTMLImageElement.isMap

一個布林值，反映 ismap HTML 屬性，指示影像是伺服器端影像對映的一部分。這與客戶端影像對映不同，客戶端影像對映使用 <img> 元素和包含 <area> 元素（指示影像中的可點選區域）的相應 <map> 來指定。影像必須包含在 <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。您可以透過更改 src 屬性中的 URL 來將不同的影像載入到元素中。

HTMLImageElement.srcset

一個字串，反映 srcset HTML 屬性。這指定了一個候選影像列表，由逗號 (',', U+002C COMMA) 分隔。每個候選影像是一個 URL，後跟一個空格，再後跟一個特殊格式的字串，指示影像的大小。大小可以指定為寬度或大小倍數。有關大小子字串格式的詳細資訊，請閱讀 srcset 頁面。

HTMLImageElement.useMap

一個字串，反映 usemap HTML 屬性，其中包含描述要使用的影像對映的 <map> 元素的頁面區域性 URL。頁面區域性 URL 是一個井號 (hash) 符號 (#)，後跟 <map> 元素的 ID，例如 #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 時，該 Promise 將解析。這可以防止在將未解碼的影像新增到 DOM 時，下一幀的渲染暫停以解碼影像。

錯誤

如果嘗試載入或渲染影像時發生錯誤，並且已配置 onerror 事件處理程式來處理 error 事件，則將呼叫該事件處理程式。這可能發生在多種情況下，包括：

  • src 屬性為空或 null。
  • 指定的 src URL 與使用者當前所在的頁面 URL 相同。
  • 指定的影像以某種方式損壞，導致無法載入。
  • 指定的影像元資料以某種方式損壞，導致無法檢索其尺寸，並且在 <img> 元素的屬性中未指定任何尺寸。
  • 指定的影像格式不受 使用者代理 支援。

示例

建立和插入影像元素

js
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);

獲取寬度和高度

以下示例展示了 height 和 width 屬性與不同尺寸影像的用法：

html
<p>
  Image 1: no height, width, or style
  <img id="image1" src="https://www.mozilla.org/images/mozilla-banner.gif" />
</p>

<p>
  Image 2: height="50", width="500", but no style
  <img
    id="image2"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
    height="50"
    width="500" />
</p>

<p>
  Image 3: no height, width, but style="height: 50px; width: 500px;"
  <img
    id="image3"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
    style="height: 50px; width: 500px;" />
</p>

<div id="output"></div>
js
const arrImages = [
  document.getElementById("image1"),
  document.getElementById("image2"),
  document.getElementById("image3"),
];

const objOutput = document.getElementById("output");
let strHtml = "<ul>";

for (let i = 0; i < arrImages.length; i++) {
  const img = arrImages[i];
  strHtml += `<li>image${i + 1}: height=${img.height}, width=${img.width}, style.height=${img.style.height}, style.width=${img.style.width}</li>`;
}

strHtml += "</ul>";

objOutput.innerHTML = strHtml;

規範

規範
HTML
# htmlimageelement

瀏覽器相容性

另見

  • 實現此介面的 HTML 元素：<img>

幫助改進 MDN

瞭解如何貢獻

此頁面由 MDN 貢獻者 上次修改於 。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.