<img>：圖片嵌入元素

試一試

<img
  class="fit-picture"
  src="/shared-assets/images/examples/grapefruit-slice.jpg"
  alt="Grapefruit slice atop a pile of other slices" />

.fit-picture {
  width: 250px;
}

上述示例展示了 <img> 元素的用法

• src 屬性包含要嵌入影像的路徑。如果 srcset 屬性可用，則它不是強制性的。但是，必須提供 src 或 srcset 屬性中的至少一個。
• 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 或 srcset 屬性為空 ("") 或 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

async

auto

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

elementtiming

標記影像以便由 PerformanceElementTiming API 觀察。給定值成為被觀察影像元素的識別符號。另請參閱 elementtiming 屬性頁面。

fetchpriority

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

high

相對於其他影像，以高優先順序獲取影像。

low

相對於其他影像，以低優先順序獲取影像。

auto

不對獲取優先順序設定偏好。這是預設值。如果未設定值或設定了無效值，則使用此值。

有關更多資訊，請參閱 HTMLImageElement.fetchPriority。

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：將不向沒有 TLS (HTTPS) 的源傳送 Referer 頭。
• 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

一個或多個用逗號分隔的值，可以是源大小或 auto 關鍵字。

源大小由以下部分組成

1. 一個媒體條件，列表中最後一項可省略。
2. 一個源大小值。

媒體條件描述的是視口的屬性，而不是影像的屬性。例如，(height <= 500px) 1000px 建議如果視口高度為 500px 或更小，則使用 1000px 寬的影像源。因為源大小描述符指定了佈局時影像要使用的寬度，所以媒體條件通常（但不一定）基於寬度。

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

源大小值可以是任何非負的長度。它不能使用除數學函式之外的 CSS 函式。單位的解釋方式與媒體查詢相同，這意味著所有相對長度單位都相對於文件根而不是 <img> 元素。例如，em 值相對於根字型大小，而不是影像的字型大小。百分比值不允許。

auto 關鍵字可以替換整個大小列表或列表中的第一個條目。它僅在與 loading="lazy" 結合使用時有效，並解析為影像的具體大小。由於影像的固有大小尚不清楚，因此還應指定 width 和 height 屬性（或等效的 CSS），以防止瀏覽器假定影像的預設寬度為 300px。為了更好地向不支援 auto 的瀏覽器進行向後相容，您可以在 sizes 屬性中的 auto 之後包含備用大小

html

<img
  loading="lazy"
  width="200"
  height="200"
  sizes="auto, (max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
  srcset="
    swing-200.jpg   200w,
    swing-400.jpg   400w,
    swing-800.jpg   800w,
    swing-1600.jpg 1600w
  "
  src="swing-400.jpg"
  alt="Kettlebell Swing" />

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-align CSS 屬性。允許的值

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 已棄用

影像周圍邊框的寬度。請改用 border CSS 屬性。

hspace 已廢棄

影像左右兩側的空白畫素數。請改用 margin CSS 屬性。

longdesc 已廢棄

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

注意：此屬性在 HTML 規範中被視為已過時。它未來不確定；作者應使用 WAI-ARIA 替代方案，例如 aria-describedby 或 aria-details。

name 已廢棄

元素的名稱。請改用 id 屬性。

vspace 已廢棄

影像上方和下方的空白畫素數。請改用 margin CSS 屬性。

使用 CSS 樣式

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

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

您可以使用 object-position 屬性定位元素框內的影像，以及 object-fit 屬性調整框內影像的大小（例如，影像是否應適應框或填充框，即使需要裁剪）。

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

無障礙

編寫有意義的替代描述

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

不要

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

要

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

一項重要的可訪問性測試是，將 alt 屬性內容與前面的文字內容一起閱讀，以檢視它是否傳達與影像相同的含義。例如，如果影像前面是句子“在我的旅行中，我看到了一隻可愛的小動物：”，螢幕閱讀器可能會將“不要”示例讀作“在我的旅行中，我看到了一隻可愛的小動物：影像”，這沒有意義。“要”示例可能會被螢幕閱讀器讀作“在我的旅行中，我看到了一隻可愛的小動物：海灘上的一隻企鵝。”，這就有意義了。

對於用於觸發動作的影像，例如巢狀在 <a> 或 <button> 元素內的影像，請考慮在 alt 屬性值中描述觸發的動作。例如，您可以寫 alt="下一頁" 而不是 alt="右箭頭"。您還可以考慮在 title 屬性中新增可選的進一步描述；如果使用者請求，螢幕閱讀器可能會讀取它。

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

• Alt 決策樹 • 影像 • WAI 網路可訪問性教程
• Alt 文字：終極指南 — Axess Lab
• 如何設計出色的 Alt 文字：簡介 | Deque
• MDN 理解 WCAG，指南 1.1 解釋
• 理解成功標準 1.1.1 | W3C 理解 WCAG 2.0

將 SVG 標識為影像

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

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

title 屬性

title 屬性不能替代 alt 屬性。此外，請避免在同一影像上宣告的 title 屬性中重複 alt 屬性的值。這樣做可能會導致某些螢幕閱讀器重複宣佈相同的文字，從而造成令人困惑的體驗。

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

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

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

示例

替代文字

以下示例將影像嵌入頁面，幷包含用於可訪問性的替代文字。

<img src="/shared-assets/images/examples/favicon144.png" alt="MDN" />

影像連結

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

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

使用 srcset 屬性

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

<img
  src="/shared-assets/images/examples/favicon72.png"
  alt="MDN"
  srcset="/shared-assets/images/examples/favicon144.png 2x" />

使用 srcset 和 sizes 屬性

當包含 w 描述符時，支援 srcset 的使用者代理會忽略 src 屬性。當 (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="(width <= 600px) 200px, 50vw" />

安全和隱私問題

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

技術摘要

規範

瀏覽器相容性

另見

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