<img>: 圖片嵌入元素

以上示例顯示了 <img> 元素的使用方法

• src 屬性是必需的，它包含要嵌入的影像的路徑。
• alt 屬性儲存影像的文字替換，這是強制性的，並且對於輔助功能非常有用——螢幕閱讀器將其屬性值讀給使用者，以便他們知道影像的含義。如果影像由於某種原因無法載入，則 alt 文字也會顯示在頁面上：例如，網路錯誤、內容阻止或連結失效。

還有許多其他屬性可以實現各種目的

• Referrer/CORS 用於安全和隱私控制：請參閱 crossorigin 和 referrerpolicy。
• 同時使用 width 和 height 設定影像的固有大小，使其在載入前佔用空間，從而減輕內容佈局偏移。
• 使用 sizes 和 srcset 提供響應式影像提示（另請參閱 <picture> 元素和我們的 響應式影像 教程）。

HTML 標準未列出要支援的影像格式，因此 使用者代理 可能支援不同的格式。

Web 上最常用的影像檔案格式有：

• APNG（動畫行動式網路圖形）—— 無損動畫序列的不錯選擇（GIF 的效能較差）
• AVIF（AV1 影像檔案格式）—— 由於高效能，影像和動畫影像的不錯選擇。
• GIF（圖形交換格式）—— 簡單影像和動畫的不錯選擇。
• JPEG（聯合影像專家組影像）—— 靜止影像的有失真壓縮的不錯選擇（目前最流行）。
• PNG（行動式網路圖形）—— 靜止影像的無失真壓縮的不錯選擇（質量略優於 JPEG）。
• SVG（可縮放向量圖形）—— 向量影像格式。用於必須以不同尺寸精確繪製的影像。
• WebP（Web 圖片格式）—— 影像和動畫影像的絕佳選擇

建議使用 WebP 和 AVIF 等格式，因為它們在靜止影像和動畫影像方面都比 PNG、JPEG、GIF 具有更好的效能。

對於必須以不同尺寸精確繪製的影像，SVG 仍然是推薦的格式。

如果在載入或渲染影像時發生錯誤，並且已為 error 事件設定了 onerror 事件處理程式，則將呼叫該事件處理程式。這可能發生在以下幾種情況下：

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

此元素包含全域性屬性。

alt

定義可在頁面中替換影像的文字。

注意：瀏覽器並不總是顯示影像。在多種情況下，瀏覽器可能不會顯示影像，例如

• 非視覺瀏覽器（例如視障人士使用的瀏覽器）
• 使用者選擇不顯示影像（節省頻寬、出於隱私原因）
• 影像無效或不支援的型別

在這些情況下，瀏覽器可能會用元素的alt屬性中的文字替換影像。出於這些以及其他原因，請儘可能為alt提供有用的值。

將此屬性設定為空字串（alt=""）表示此影像不是內容的關鍵部分（它是裝飾或跟蹤畫素），非視覺瀏覽器可能會將其從渲染中省略。如果alt屬性為空且影像未能顯示，視覺瀏覽器也會隱藏損壞的影像圖示。

此屬性還用於將影像複製貼上到文字中或將連結的影像儲存到書籤中。

attributionsrc 實驗性

指定您希望瀏覽器在傳送影像請求時同時傳送Attribution-Reporting-Eligible標頭。

在伺服器端，這用於觸發在響應中傳送Attribution-Reporting-Register-Source或Attribution-Reporting-Register-Trigger標頭，以分別註冊基於影像的歸因來源或歸因觸發器。應傳送回哪個響應標頭取決於觸發註冊的Attribution-Reporting-Eligible標頭的值。

一旦瀏覽器收到包含影像檔案的響應，相應的源或觸發事件就會被觸發。

注意：有關詳細資訊，請參閱歸因報告 API。

您可以設定此屬性的兩個版本

• 布林值，即僅使用attributionsrc名稱。這表示您希望將Attribution-Reporting-Eligible標頭髮送到與src屬性指向的伺服器相同的伺服器。當您在同一伺服器上處理歸因來源或觸發器註冊時，這很好用。註冊歸因觸發器時，此屬性是可選的，如果省略，將使用布林值。
• 包含一個或多個 URL 的值，例如

html

<img
  src="image-file.png"
  alt="My image file description"
  attributionsrc="https://a.example/register-source
                     https://b.example/register-source" />

這在請求的資源不在您控制的伺服器上或您只想在不同的伺服器上處理歸因來源註冊的情況下非常有用。在這種情況下，您可以將一個或多個 URL 指定為attributionsrc的值。當資源請求發生時，Attribution-Reporting-Eligible標頭將傳送到attributionSrc中指定的一個或多個 URL 以及資源來源。然後，這些 URL 可以根據需要響應Attribution-Reporting-Register-Source或Attribution-Reporting-Register-Trigger標頭以完成註冊。

注意：指定多個 URL 意味著可以在同一功能上註冊多個歸因來源。例如，您可能有不同的廣告系列需要衡量其成功率，這涉及到針對不同資料生成不同的報告。

crossorigin

指示是否必須使用CORS請求獲取影像。從 CORS 請求返回的啟用 CORS 的影像中的影像資料可以在<canvas>元素中重複使用，而無需標記為“受汙染的”。

如果未指定crossorigin屬性，則會發送非 CORS 請求（不帶Origin請求標頭），並且瀏覽器會將影像標記為受汙染，並限制對其影像資料的訪問，從而阻止其在<canvas>元素中使用。

如果指定了crossorigin屬性，則會發送 CORS 請求（帶有Origin請求標頭）；但是，如果伺服器沒有選擇透過來源站點允許跨源訪問影像資料（不傳送任何Access-Control-Allow-Origin響應標頭，或者不在其傳送的任何Access-Control-Allow-Origin響應標頭中包含站點的來源），則瀏覽器會阻止影像載入，並在開發者工具控制檯中記錄 CORS 錯誤。

允許的值

anonymous

傳送 CORS 請求時省略憑據（即沒有cookie、X.509 證書或Authorization請求標頭）。

use-credentials

傳送 CORS 請求時包含任何憑據（即 cookie、X.509 證書和Authorization請求標頭）。如果伺服器沒有選擇與來源站點共享憑據（透過傳送回Access-Control-Allow-Credentials: true響應標頭），則瀏覽器會將影像標記為受汙染，並限制對其影像資料的訪問。

如果屬性具有無效值，瀏覽器會將其視為使用了anonymous值。有關其他資訊，請參閱CORS 設定屬性。

decoding

此屬性為瀏覽器提供了一個提示，指示它是否應在單個呈現步驟中執行影像解碼以及呈現其他 DOM 內容，以使影像看起來更“正確”（sync），或者先呈現和顯示其他 DOM 內容，然後解碼影像並在稍後呈現（async）。實際上，async表示下一個繪製不會等待影像解碼。

在靜態<img>元素上使用decoding時，通常很難察覺到任何明顯的差異。它們可能會最初呈現為空影像，而影像檔案正在獲取（從網路或快取中獲取），然後無論如何都會獨立處理，因此內容更新的“同步”不太明顯。但是，解碼期間呈現的阻塞雖然通常很小，但可以衡量——即使用肉眼很難觀察到。有關更詳細的分析，請參閱影像解碼屬性到底做了什麼？（tunetheweb.com，2023）。

當透過 JavaScript 將<img>元素動態插入 DOM 時，使用不同的decoding型別會導致更明顯的差異——有關更多詳細資訊，請參閱HTMLImageElement.decoding。

允許的值

sync

與渲染其他 DOM 內容同步解碼影像，並將所有內容一起呈現。

async

非同步解碼影像，在渲染和呈現其他 DOM 內容之後。

auto

對解碼模式沒有偏好；瀏覽器決定對使用者最有利的模式。這是預設值。

elementtiming

標記影像以供PerformanceElementTimingAPI 觀察。給定的值成為觀察到的影像元素的識別符號。另請參閱elementtiming屬性頁面。

fetchpriority

提供獲取影像時應使用的相對優先順序的提示。允許的值

high

相對於其他影像發出高優先順序獲取訊號。

low

相對於其他影像發出低優先順序獲取訊號。

auto

預設值：發出相對於其他影像自動確定獲取優先順序的訊號。

height

影像的固有高度（以畫素為單位）。必須是無單位的整數。

注意：包含height和width使瀏覽器能夠在影像載入之前計算影像的縱橫比。此縱橫比用於預留顯示影像所需的空間，減少甚至防止影像下載並繪製到螢幕上時發生佈局偏移。減少佈局偏移是良好的使用者體驗和網頁效能的主要組成部分。

ismap

此布林屬性表示影像屬於伺服器端對映的一部分。如果是，則使用者在影像上單擊的座標將傳送到伺服器。

注意：僅當<img>元素是具有有效href屬性的<a>元素的後代時，才允許使用此屬性。這為沒有指向裝置的使用者提供了備用目標。

loading

指示瀏覽器應如何載入影像

eager

立即載入影像，而不管影像當前是否在可見視口中（這是預設值）。

lazy

延遲載入影像，直到它到達距視口一定計算距離，該距離由瀏覽器定義。目的是避免處理影像所需的網路和儲存頻寬，直到確定它很可能需要為止。這通常會在大多數典型用例中提高內容的效能。

注意：僅在啟用 JavaScript 時才會延遲載入。這是一項反跟蹤措施，因為如果使用者代理在指令碼停用時支援延遲載入，則網站仍然可以透過在頁面標記中策略性地放置影像來跟蹤使用者在整個會話中的大致滾動位置，以便伺服器可以跟蹤請求了多少影像以及何時請求。

注意：如果影像與可見元素的一部分沒有交集，即使載入它們會改變這一點，設定了loading為lazy的影像也永遠不會載入，因為未載入的影像的width和height為0。在延遲載入的影像上放置width和height可以解決此問題，並且是一種最佳實踐，規範推薦這樣做。這樣做也有助於防止佈局偏移。

referrerpolicy

一個字串，指示在獲取資源時使用哪個推薦來源。

• no-referrer：不會發送Referer標頭。
• no-referrer-when-downgrade：不會將Referer標頭髮送到沒有TLS（HTTPS）的來源。
• origin：傳送的推薦來源將限制為推薦頁面的來源：其方案、主機和埠。
• origin-when-cross-origin：傳送到其他來源的推薦來源將限制為方案、主機和埠。相同來源的導航仍將包含路徑。
• same-origin：將為相同來源傳送推薦來源，但跨源請求將不包含推薦來源資訊。
• strict-origin：僅在協議安全級別保持不變（HTTPS→HTTPS）時傳送文件的來源作為推薦來源，但不要將其傳送到安全性較低的目的地（HTTPS→HTTP）。
• strict-origin-when-cross-origin（預設值）：在執行相同來源請求時傳送完整 URL，僅在協議安全級別保持不變（HTTPS→HTTPS）時傳送來源，並將沒有標頭髮送到安全性較低的目的地（HTTPS→HTTP）。
• unsafe-url：推薦來源將包含來源和路徑（但不包含片段、密碼或使用者名稱）。此值不安全，因為它會將受 TLS 保護的資源的來源和路徑洩漏到不安全的來源。

sizes

一個或多個以逗號分隔的字串，指示一組源大小。每個源大小由以下組成：

1. 媒體條件。對於列表中的最後一項，必須省略此條件。
2. 源大小值。

媒體條件描述的是視口的屬性，而不是影像的屬性。例如，(max-height: 500px) 1000px建議如果視口的高度不超過 500px，則使用 1000px 寬度的源。

源大小值指定影像的預期顯示大小。使用者代理使用當前源大小從srcset屬性提供的源中選擇一個源，當這些源使用寬度（w）描述符進行描述時。所選源大小會影響影像的固有大小（如果未應用任何CSS樣式，則影像的顯示大小）。如果srcset屬性不存在或不包含任何具有寬度描述符的值，則sizes屬性無效。

src

影像URL。對於<img>元素是必需的。在支援srcset的瀏覽器中，src被視為具有畫素密度描述符1x的候選影像，除非srcset中已定義具有此畫素密度描述符的影像，或者除非srcset包含w描述符。

srcset

一個或多個以逗號分隔的字串，指示使用者代理可能使用的影像源。每個字串由以下組成：

1. 影像的URL
2. 可選地，後面跟有一個空格，然後是以下之一：
   • 寬度描述符（正整數後跟w）。寬度描述符除以sizes屬性中給定的源大小以計算有效畫素密度。
   • 畫素密度描述符（正浮點數後跟x）。

如果未指定描述符，則源將分配預設描述符1x。

在同一個srcset屬性中混合寬度描述符和畫素密度描述符是不正確的。重複描述符（例如，同一個srcset中的兩個源都用2x描述）也是無效的。

如果srcset屬性使用寬度描述符，則還必須存在sizes屬性，否則srcset本身將被忽略。

使用者代理可自行決定選擇任何可用的源。這為他們提供了很大的自由度來根據使用者偏好或頻寬條件定製其選擇。有關示例，請參閱我們的響應式影像教程。

width

影像的固有寬度（以畫素為單位）。必須是無單位的整數。

usemap

與元素關聯的影像對映的部分URL（以#開頭）。

注意：如果<img>元素位於<a>或<button>元素內部，則不能使用此屬性。

align 已棄用

將影像與其周圍環境對齊。請使用float和/或vertical-alignCSS屬性來代替此屬性。允許的值

top

等效於vertical-align: top或vertical-align: text-top

middle

等效於vertical-align: -moz-middle-with-baseline

bottom

預設值，等效於vertical-align: unset或vertical-align: initial

left

等效於float: left

right

等效於float: right

border 已棄用

影像周圍邊框的寬度。請使用borderCSS屬性來代替。

hspace 已棄用

影像左右兩側空白區域的畫素數。請使用marginCSS 屬性來代替。

longdesc 已棄用

指向影像更詳細描述的連結。可能的值為URL或元素id。

注意：此屬性在最新的W3C版本HTML 5.2中提到，但已從WHATWG的HTML 活躍標準中刪除。它的未來尚不確定；作者應使用WAI-ARIA替代方案，例如aria-describedby或aria-details。

name 已棄用

元素的名稱。請使用id屬性來代替。

vspace 已棄用

影像上下兩側空白區域的畫素數。請使用marginCSS 屬性來代替。

<img>是一個替換元素；預設情況下，它的display值為inline，但其預設尺寸由嵌入影像的內在值定義，就像它是inline-block一樣。您可以設定諸如border/border-radius、padding/margin、width、height等屬性在影像上。

<img>沒有基線，因此當影像在內聯格式化上下文中與vertical-align: baseline一起使用時，影像的底部將放置在文字基線上。

您可以使用object-position屬性在元素的框內定點陣圖像，並使用object-fit屬性調整影像在框內的尺寸（例如，影像是否應該適合框或即使需要裁剪也填充框）。

根據影像的型別，它可能具有內在寬度和高度。但是，對於某些影像型別，內在尺寸是不必要的。例如，如果SVG影像的根<svg>元素沒有設定width或height，則它沒有內在尺寸。

alt屬性的值應為影像內容提供清晰簡潔的文字替換。它不應描述影像本身的存在或影像的檔名。如果alt屬性被故意省略，因為影像沒有文字等效項，請考慮使用其他方法來呈現影像試圖傳達的內容。

不要

<img alt="image" src="penguin.jpg" />

做

<img alt="A Rockhopper Penguin is standing on a beach." src="penguin.jpg" />

當影像上沒有alt屬性時，一些螢幕閱讀器可能會宣佈影像的檔名。如果檔名不能代表影像的內容，這可能會導致令人困惑的體驗。

• 替代文字決策樹 • 影像 • WAI Web 可訪問性教程
• 替代文字：終極指南 — Axess Lab
• 如何設計優秀的替代文字：簡介 | Deque
• MDN 理解 WCAG，指南 1.1 說明
• 理解成功標準 1.1.1 | W3C 理解 WCAG 2.0

由於VoiceOver 錯誤，VoiceOver 無法正確地將 SVG 影像宣佈為影像。將role="img"包含到所有具有 SVG 原始檔的<img>元素中，以確保輔助技術正確地將 SVG 宣佈為影像內容。

<img src="mdn.svg" alt="MDN" role="img" />

title屬性不是alt屬性的可接受替代品。此外，避免在同一影像上宣告的title屬性中複製alt屬性的值。這樣做可能會導致某些螢幕閱讀器兩次宣佈相同的文字，從而造成混亂的體驗。

title屬性也不應被用作補充字幕資訊來伴隨影像的alt描述。如果影像需要標題，請使用figure和figcaption元素。

title屬性的值通常以工具提示的形式呈現給使用者，該工具提示在游標停止在影像上移動後不久出現。雖然這可以為使用者提供其他資訊，但你不應該假設使用者會看到它：使用者可能只有鍵盤或觸控式螢幕。如果您有對使用者特別重要或有價值的資訊，請使用上述方法之一內聯顯示，而不是使用title。

• 使用 HTML title 屬性 – 更新 | Paciello Group

以下示例將影像嵌入到頁面中，幷包含用於輔助功能的替代文字。

<img src="favicon144.png" alt="MDN" />

此示例建立在上一個示例的基礎上，展示瞭如何將影像轉換為連結。為此，將<img>標籤巢狀在<a>中。您應該使替代文字描述連結指向的資源，就像使用文字連結一樣。

<a href="https://mdn.club.tw">
  <img src="favicon144.png" alt="Visit the MDN site" />
</a>

在此示例中，我們包含一個srcset屬性，其中包含對徽標的高解析度版本的引用；這將在高解析度裝置上載入，而不是src影像。在支援srcset的使用者代理中，src屬性中引用的影像被計為1x候選。

<img src="favicon72.png" alt="MDN" srcset="favicon144.png 2x" />

當包含w描述符時，在支援srcset的使用者代理中，src屬性將被忽略。當(max-width: 600px)媒體條件匹配時，將載入寬度為 200 畫素的影像（它是與200px最接近匹配的影像），否則將載入另一個影像。

<img
  src="clock-demo-200px.png"
  alt="The time is 12:45."
  srcset="clock-demo-200px.png 200w, clock-demo-400px.png 400w"
  sizes="(max-width: 600px) 200px, 50vw" />

儘管<img>元素具有無害的用途，但它們可能會對使用者安全和隱私造成不良後果。有關更多資訊和緩解措施，請參閱Referer 標頭：隱私和安全問題。

• <picture>、<object>和<embed>元素
• object-fit、object-position、image-orientation、image-rendering和image-resolution：與影像相關的 CSS 屬性。
• HTMLImageElement此元素的介面
• HTML 中的影像
• 影像檔案型別和格式指南
• 響應式影像