<Image> (舊版)

從 Next.js 13 開始，next/image 元件已改寫，以提升效能和開發者體驗。為了提供向後相容的升級方案，舊的 next/image 已重新命名為 next/legacy/image。

檢視**新的** next/image API 參考

比較

與 next/legacy/image 相比，新的 next/image 元件有以下變更：

• 移除 <img> 周圍的 <span> 包裝器，改用 原生計算的長寬比
• 新增支援標準 style 屬性
  • 移除 layout 屬性，改用 style 或 className
  • 移除 objectFit 屬性，改用 style 或 className
  • 移除 objectPosition 屬性，改用 style 或 className
• 移除 IntersectionObserver 的實作，改用 原生延遲載入
  • 移除 lazyBoundary 屬性，因為沒有原生對應項
  • 移除 lazyRoot 屬性，因為沒有原生對應項
• 移除 loader 設定，改用 loader 屬性
• 將 alt 屬性從選用改為必填
• 更改 onLoadingComplete 回呼，使其接收 <img> 元素的參考

必填屬性

<Image /> 元件需要以下屬性。

src

必須為下列其中一項

• 一個靜態匯入的圖片檔案
• 一個路徑字串。可以是絕對的外部網址，或是根據 loader 屬性或 loader 設定 的內部路徑。

當使用預設的 loader 時，來源圖片也需考慮以下事項

• 當 src 為外部網址時，您也必須設定 remotePatterns
• 當 src 為動態圖片或非已知格式 (JPEG, PNG, WebP, AVIF, GIF, TIFF) 時，圖片將會以原始格式提供。
• 當 src 為 SVG 格式時，除非啟用 unoptimized 或 dangerouslyAllowSVG，否則將會被阻擋。

widthlayout 和 sizes 屬性。

當使用 layout="intrinsic" 或 layout="fixed" 時，width 屬性表示以像素為單位的 _渲染_ 寬度，因此它會影響圖片顯示的大小。

當使用 layout="responsive"、layout="fill" 時，width 屬性表示以像素為單位的 _原始_ 寬度，因此它只會影響長寬比。

除了 靜態匯入的圖片 或 layout="fill" 的圖片之外，width 屬性是必需的。

height

height 屬性可以表示以像素為單位的 _渲染_ 高度或 _原始_ 高度，取決於 layout 和 sizes 屬性。

當使用 layout="intrinsic" 或 layout="fixed" 時，height 屬性表示以像素為單位的 _渲染_ 高度，因此它會影響圖片顯示的大小。

當使用 layout="responsive"、layout="fill" 時，height 屬性表示以像素為單位的 _原始_ 高度，因此它只會影響長寬比。

除了 靜態匯入的圖片 或 layout="fill" 的圖片之外，height 屬性是必需的。

選用屬性

<Image /> 元件除了必要的屬性外，還接受許多額外的屬性。本節說明 Image 元件最常用的屬性。有關較少使用的屬性的詳細資訊，請參閱進階屬性一節。

配置

影像在視埠大小變更時的配置行為。

• 示範 intrinsic 配置（預設）
  • 當使用 intrinsic 時，影像會在較小的視埠中縮小尺寸，但在較大的視埠中維持原始尺寸。
• 示範 fixed 配置
  • 當使用 fixed 時，影像尺寸不會隨著視埠變化而改變（無響應式），類似於原生 img 元素。
• 示範 responsive 配置
  • 當使用 responsive 時，影像會在較小的視埠中縮小尺寸，在較大的視埠中放大尺寸。
  • 請確保父元素在其樣式表中使用 display: block。
• 示範 fill 配置
  • 當使用 fill 時，影像會將寬度和高度都拉伸到父元素的尺寸，前提是父元素是相對定位的。
  • 這通常會與 objectFit 屬性搭配使用。
  • 請確保父元素在其樣式表中使用 position: relative。
• 示範背景圖片

載入器

一個用於解析網址的客製化函式。在 Image 元件上將載入器設定為 prop 會覆寫在 next.config.js 的 images 區段 中定義的預設載入器。

loader 是一個函式，根據以下參數返回圖片的網址字串

• 來源 (src)
• 寬度 (width)
• 品質 (quality)

以下是一個使用客製化載入器的範例

import Image from 'next/legacy/image'
 
const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
 
const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

尺寸

一個字串，提供關於圖片在不同斷點寬度的資訊。sizes 的值會極大地影響使用 layout="responsive" 或 layout="fill" 的圖片效能。對於使用 layout="intrinsic" 或 layout="fixed" 的圖片，它將被忽略。

sizes 屬性有兩個與圖片效能相關的重要用途

首先，瀏覽器使用 sizes 的值來決定要從 next/legacy/image 自動產生的來源集中下載哪個尺寸的圖片。當瀏覽器進行選擇時，它還不知道頁面上圖片的尺寸，因此它會選擇與螢幕顯示區大小相同或更大的圖片。sizes 屬性允許您告知瀏覽器圖片實際上會小於全螢幕。如果您未指定 sizes 值，則會使用預設值 100vw（全螢幕寬度）。

其次，會解析 sizes 值並用於修剪自動建立的來源集中的值。如果 sizes 屬性包含例如 50vw 等表示螢幕顯示區寬度百分比的尺寸，則會修剪來源集以不包含任何永遠不需要的太小的值。

例如，如果您知道您的樣式會導致圖片在行動裝置上為全寬，在平板電腦上為兩欄配置，在桌上型顯示器上為三欄配置，則應包含如下所示的 sizes 屬性

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

這個 sizes 範例可能會對效能指標產生顯著影響。如果沒有 33vw 尺寸，則從伺服器選擇的圖片寬度將是所需寬度的 3 倍。由於檔案大小與寬度的平方成正比，因此如果沒有 sizes，使用者將下載比所需大小大 9 倍的圖片。

深入瞭解 srcset 和 sizes

• web.dev
• mdn

品質

最佳化圖片的品質，一個介於 1 和 100 之間的整數，其中 100 代表最佳品質。預設值為 75。

優先順序

當設為 true 時，圖片將被視為高優先順序並預先載入。使用 priority 的圖片會自動停用延遲載入。

您應該在任何被偵測為最大內容繪製 (LCP)元素的圖片上使用 priority 屬性。設定多個優先順序圖片可能是適當的，因為不同圖片可能在不同的視窗大小下成為 LCP 元素。

僅應在圖片顯示在首屏時使用。預設值為 false。

佔位符

圖片載入時使用的佔位符。可能的值為 blur 或 empty。預設值為 empty。

當設為 blur 時，blurDataURL 屬性將被用作佔位符。如果 src 是一個來自靜態匯入的物件，且匯入的圖片是 .jpg、.png、.webp 或 .avif，則 blurDataURL 將會自動填入。

對於動態圖片，您必須提供 blurDataURL 屬性。諸如 Plaiceholder 之類的解決方案可以協助產生 base64 編碼。

當設為 empty 時，圖片載入時將沒有佔位符，只有空白。

試用看看

• 示範 blur 佔位符
• 使用 blurDataURL 屬性示範 shimmering 效果
• 使用 blurDataURL 屬性示範顏色效果

進階屬性

在某些情況下，您可能需要更進階的用法。<Image /> 元件可選用以下進階屬性。

style 樣式

允許將 CSS 樣式傳遞到底層的圖片元素。

請注意，所有 layout 模式都會將其自身的樣式套用至圖片元素，而這些自動樣式會優先於 style 屬性。

同時請記住，必要的 width 和 height 屬性可能會與您的樣式產生交互作用。如果您使用樣式修改圖片的 width，您也必須設定 height="auto" 樣式，否則您的圖片會失真。

objectFit 物件擬合

定義當使用 layout="fill" 時，圖片將如何適配其父容器。

此值會傳遞至 src 圖片的 object-fit CSS 屬性。

objectPosition 物件位置

定義當使用 layout="fill" 時，圖片在其父元素內的定位方式。

這個值會傳遞給套用至圖片的 object-position CSS 屬性。

onLoadingComplete

在圖片完全載入且預留位置被移除後會呼叫的回呼函式。

onLoadingComplete 函式接受一個參數，該參數是一個物件，具有以下屬性：

• naturalWidth
• naturalHeight

loading

圖片的載入行為。預設為 lazy（延遲載入）。

當設為 lazy 時，會延遲載入圖片，直到它到達計算出的與視埠的距離。

當設為 eager 時，會立即載入圖片。

了解更多

blurDataURL

一個資料網址（Data URL），在 src 圖片成功載入之前用作預留位置圖片。僅在與 placeholder="blur" 結合使用時才會生效。

必須是 base64 編碼的圖片。它會被放大和模糊化，因此建議使用非常小的圖片（10px 或更小）。包含較大的圖片作為預留位置可能會損害應用程式效能。

試用看看

• 預設 blurDataURL 屬性示範
• 使用 blurDataURL 屬性示範 shimmering 效果
• 使用 blurDataURL 屬性示範顏色效果

您也可以產生純色資料網址來匹配圖片。

lazyBoundary

一個字串（語法類似於 margin 屬性），作為邊界框用於檢測 viewport 與圖片的相交，並觸發延遲載入。預設值為 "200px"。

如果圖片嵌套在根文件以外的可滾動父元素中，您還需要指定 lazyRoot 屬性。

了解更多

lazyRoot

一個指向可滾動父元素的 React Ref。預設值為 null（文件 viewport）。

Ref 必須指向一個 DOM 元素或一個將 Ref 轉發到底層 DOM 元素的 React 組件。

指向 DOM 元素的範例

import Image from 'next/legacy/image'
import React from 'react'
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

指向 React 組件的範例

import Image from 'next/legacy/image'
import React from 'react'
 
const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

了解更多

unoptimized

當值為 true 時，來源圖片將按原樣提供，而不是更改品質、大小或格式。預設值為 false。

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

從 Next.js 12.3.0 版開始，可以透過使用以下配置更新 next.config.js 來將此屬性指定給所有圖片

module.exports = {
  images: {
    unoptimized: true,
  },
}

其他屬性

<Image /> 元件上的其他屬性將會傳遞到底層的 img 元素，但以下例外：

• srcSet。請改用裝置尺寸。
• ref。請改用onLoadingComplete。
• decoding。它永遠是 "async"。

設定選項

遠端模式

next.config.js

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}