| バージョン | 変更点 |
|---|---|
v12.0.9 | lazyRoot prop 追加。 |
v12.0.0 | formats 設定追加。AVIF サポート追加。 ラッパー <div> が <span> に変更。 |
v11.1.0 | onLoadingComplete と lazyBoundary props 追加。 |
v11.0.0 | src prop の静的インポートサポート。placeholder prop 追加。blurDataURL prop 追加。 |
v10.0.5 | loader prop 追加。 |
v10.0.1 | layout prop 追加。 |
v10.0.0 | next/image 導入。 |
備考: これは Image コンポーネントと画像最適化に関する API ドキュメントです。 Next.js における画像の概要や利用方法については、Images をご覧ください。
<Image /> コンポーネントは以下のプロパティを必要とします。
以下のいずれか 1 つが必須です:
外部 URL を使用する場合は next.config.js の domains に追加する必要があります。
画像の幅 (ピクセル単位) を表します。単位のない整数である必要があります。
静的にインポートされた画像、または layout="fill" の場合を除いて必須です。
画像の高さ (ピクセル単位) を表します。単位のない整数である必要があります。
静的にインポートされた画像、または layout="fill" の場合を除いて必須です。
<Image /> コンポーネントは必要なプロパティ以外にも追加で多くのプロパティを受け入れます。
このセクションでは、Image コンポーネントで最も一般的に利用されるプロパティについて説明します。
使用頻度の低いプロパティの詳細については、高度なProps セクションをご覧ください。
ビューポートのサイズが変更されたときの画像のレイアウト動作。
layout | 動作 | srcSet | sizes |
|---|---|---|---|
intrinsic (デフォルト) | 画像サイズまで、コンテナの幅に合わせて縮小 | 1x,2x(imageSizes に基づく) | N/A |
fixed | width と height に正確にサイズ調整 | 1x,2x (imageSizes に基づく) | N/A |
responsive | コンテナの幅に合わせて拡大縮小 | 640w,750w, ...2048w,3840w (imageSizes と deviceSizes に基づく) | 100vw |
fill | X 軸と Y 軸の両方で拡大し、コンテナを埋める | 640w,750w, ...2048w,3840w (imageSizes と deviceSizes に基づく) | 100vw |
intrinsic layout のデモ (デフォルト)intrinsic を使う場合、画像は小さいビューポートの場合は寸法を縮小しますが、大きいビューポートの場合は元の寸法を維持します。fixed layout のデモfixed を使う場合、ネイティブの img 要素と同様に、ビューポートが変更されても (応答性がない場合) 、画像のサイズは変更されません。responsive layout のデモresponsive を使う場合、画像は小さいビューポートの場合は寸法を縮小し、大きいビューポートの場合は拡大します。display: block を使用していることを確認します。fill layout のデモfill を使う場合、親要素が相対的である場合、画像は幅と高さの両方を親要素の寸法に合わせて拡大します。objectFit プロパティとペアになっています。position: relative を使用していることを確認します。URL を解決するために使用されるカスタム関数です。 loader を Image コンポーネントの prop として設定すると、next.config.js の images オプション で定義されているデフォルトのローダーがオーバーライドされます。
loader は次のパラメータを指定して、画像の URL 文字列を返す関数です。
以下が next/image でカスタムローダーを使用した例です:
import Image from 'next/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}
/>
)
}
様々なブレークポイントでの画像の幅に関する情報を提供する文字列です。layout="response" または layout="fill" を使用する場合、デフォルトは 100vw (画面の全幅) です。
layout="fill" または layout="response" を使用している場合は、ビューポートの全幅よりも小さい画像に sizes を割り当てることが重要です。
例えば、親要素が画像を常にビューポート幅の半分未満に制限する場合は、sizes="50vw" を使用します。
sizes がないと、画像は本来必要とされる解像度の 2 倍の解像度で送信され、パフォーマンスが低下します。
layout="intrinsic" または layout="fixed" を使用している場合、上限幅はすでに制限されているため、sizes は必要ありません。
最適化された画像の品質です。 1 から 100 までの整数で、100 が最高の品質です。デフォルトは 75 です。
true の場合、画像は優先度が高く preload すると見なされます。
priority を使用する画像の遅延読み込みは自動的に無効になります。
Largest Contentful Paint (LCP) 要素として検出された画像には priority プロパティを使用する必要があります。異なる画像は異なるビューポートサイズの LCP 要素である可能性があるため、複数の優先度のある画像を使用することが適切な場合もあります。
画像が above the fold 内に表示されている場合にのみ使用してください。デフォルトは false です。
placeholder は画像の読み込み中に使用します。可能な値は blur または empty です。デフォルトは empty です。
blur の場合、blurDataURL プロパティがプレースホルダーとして使用されます。src が 静的インポート のオブジェクトであり、インポートされた画像が .jpg 、.png 、.webp 、または .avif の場合、blurDataURL は自動的に入力されます。
動的画像の場合、blurDataURL プロパティを指定する必要があります。 Plaiceholder などのソリューションは、base64 の生成に役立ちます。
empty の場合、画像の読み込み中にプレースホルダーはなく、空のスペースのみが表示されます。
試してみてください:
場合によっては、より高度な使用法が必要になることがあります。 <Image /> コンポーネントは、以下の高度なプロパティをオプションで設定できます。
layout="fill" を使用するときに、画像が親コンテナにどう収まるかを定義します。
この値は、src イメージの object-fit CSS property に渡されます。
layout="fill" を使用するときに、画像が親要素内にどう配置されるかを定義します。
この値は、object-position CSS property に渡され、画像に適用されます。
画像が完全に読み込まれ、プレースホルダー が削除されると呼び出されるコールバック関数です。
onLoadingComplete 関数は、次のプロパティを持つオブジェクトを 1 つのパラメータとして受け入れます。
注意: このプロパティは、高度な使用のみを目的としています。
eagerで画像をロードするように切り替えると、通常、パフォーマンスが低下します。代わりに
priorityプロパティを使用することをお勧めします。 これにより、ほぼすべてのユースケースで画像がすぐに読み込まれます。
画像の読み込み動作。デフォルトは lazy です。
lazy の場合、ビューポートから計算された距離に達するまで画像の読み込みを延期します。
eager の場合、即座に画像を読み込みます。
src 画像の正常読み込み前にプレースホルダー画像として使用される Data URLです。
placeholder="blur" と組み合わせた場合にのみ有効になります。
base64 でエンコードされた画像である必要があります。拡大してぼやけるので、非常に小さい画像 (10px 以下) をお勧めします。 プレースホルダーとして大きな画像を含めると、アプリケーションのパフォーマンスを低下させる可能性があります。
試してみてください:
画像に一致する 単色のデータ URL を生成する こともできます。
ビューポートと画像の交差を検出し、遅延 読み込み をトリガーするために使用される境界ボックスとして機能する文字列 (margin プロパティと同様の構文) です。デフォルトは "200px" です。
画像がルートドキュメント以外のスクロール可能な親要素にネストされている場合は、lazyRoot prop も割り当てる必要があります。
React Ref はスクロール可能な親要素を指します。
デフォルトは null (ドキュメントビューポート) です。
Ref は、基礎となる DOM 要素に Ref を転送する DOM 要素または React コンポーネントを指している必要があります。
DOM 要素を指している例
import Image from 'next/image'
import React from 'react'
const lazyRoot = React.useRef(null)
const Example = () => (
<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/image'
import React from 'react'
const Container = React.forwardRef((props, ref) =>
<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>)
}
true の場合、品質、サイズ、形式を変更する代わりに、ソース画像がそのまま提供されます。デフォルトは false です。
<Image /> コンポーネントの他のプロパティは、以下を除いて、基となる img 要素に渡されます:
style 。 代わりに className を使いましょう。srcSet 。 代わりに Device Sizes を使いましょう。ref 。 代わりに onLoadingComplete を使いましょう。decoding 。 常に "async" です。悪意のあるユーザーからアプリケーションを保護するには、Next.js Image Optimization API から提供されるイメージプロバイダードメインのリストを定義する必要があります。これは、次に示すように、next.config.js ファイルの domains プロパティで構成されます:
module.exports = {
images: {
domains: ['assets.acme.com'],
},
}
Next.js に組み込まれている Image Optimization API を使用する代わりに、クラウドプロバイダーを使用して画像を最適化する場合は、next.config.js ファイルで loader と path プレフィックスを設定できます。これにより、Image src に相対 URL を使用し、プロバイダーの正しい絶対 URL を自動的に生成できます。
module.exports = {
images: {
loader: 'imgix',
path: 'https://example.com/myaccount/',
},
}
次の画像最適化クラウドプロバイダーが含まれています:
next dev、next start、またはカスタムサーバーで自動的に起動します。loader: 'imgix'loader: 'cloudinary'loader: 'akamai'loader: 'custom' は next/image コンポーネントに loader prop を実装して、カスタムクラウドプロバイダーを使用します別のプロバイダーが必要な場合は、next/image で loader prop を使用できます。
next exportを使用してビルド時にイメージを最適化することはできず、オンデマンドでのみ最適化できます。next exportでnext/imageを使用するには、デフォルトとは異なるローダーを使用する必要があります。詳細についてはディスカッションをご覧ください。
next/imageコンポーネントのデフォルトのローダーは、インストールが迅速で開発環境に適しているため、squooshを使用します。本番環境でnext startを使用する場合、プロジェクトディレクトリでyarn add sharpを実行してsharpをインストールすることを強くお勧めします。sharpは自動的にインストールされるため、これはVercelのデプロイには必要ありません。
以降は高度なユースケース用であり、通常は必要ありません。以下のプロパティを利用した場合、今後のアップデートで Next.js のデフォルトへの変更を上書きすることになるでしょう。
ユーザーのデバイス幅を予想できる場合は、next.config.js の deviceSizes プロパティを使用して、デバイス幅のブレークポイントのリストを指定できます。これらの幅は、next/image コンポーネントが layout="response" または layout="fill" を使用して、ユーザーのデバイスに正しい画像を提供する場合に使用されます。
設定されていない場合は、以下のデフォルトが使用されます。
module.exports = {
images: {
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
},
}
next.config.js ファイルの images.imageSizes プロパティを使用して、画像の幅のリストを指定できます。これらの幅は、device sizes の配列と連結されて、イメージ srcsets の生成に使用されるサイズの完全な配列を形成します。
2 つの別々のリストがある理由は、imageSizes が sizes の prop を提供する画像にのみ使用されるためです。これは、画像が画面の全幅よりも小さいことを示します。したがって、imageSizes のサイズはすべて、deviceSizes の最小サイズよりも小さくする必要があります。
設定されていない場合は、以下のデフォルトが使用されます。
module.exports = {
images: {
imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
},
}
デフォルトの 画像最適化API は、リクエストの Accept ヘッダーを介して、ブラウザでサポートされている画像形式を自動的に検出します。
Accept ヘッダーが複数の設定済み形式と一致する場合、配列内の最初の一致が使用されます。したがって、配列の順序が重要になります。一致するものがない場合、Image Optimization API は元の画像の形式にフォールバックします。
設定されていない場合は、以下のデフォルトが使用されます。
module.exports = {
images: {
formats: ['image/webp'],
},
}
次のようにすれば AVIF サポートを有効にできます。
module.exports = {
images: {
formats: ['image/avif', 'image/webp'],
},
}
備考: AVIF は通常、エンコードに 20％ 長くかかりますが、WebP と比較して圧縮率は 20％ 小さくなります。これは、最初に画像がリクエストされたときは通常遅くなり、その後キャッシュされるリクエストは速くなることを意味します。
次に、デフォルト ローダー のキャッシュアルゴリズムについて説明します。他のすべてのローダーについては、クラウドプロバイダーのドキュメントを参照してください。
画像はリクエストに応じて動的に最適化され、<distDir>/cache/images ディレクトリに保存されます。最適化された画像ファイルは、有効期限に達するまで、後続のリクエストに提供されます。キャッシュされているが期限切れのファイルと一致するリクエストが行われると、キャッシュされたファイルは削除されてから、新しい最適化されたイメージが生成されて新しいファイルがキャッシュされます。
有効期限 (または最大経過時間) は、minimumCacheTTL 構成またはアップストリームサーバーの Cache-Control ヘッダーのいずれか大きい方によって定義されます。具体的には、Cache-Control ヘッダーの max-age 値が使用されます。 s-maxage と max-age の両方が見つかった場合は、s-maxage が優先されます。
Cache-Control ヘッダーが含まれていない場合、または値が非常に低い場合に、キャッシュ期間を長くするように minimumCacheTTL を設定できます。deviceSizes と imageSizes を構成して、生成される可能性のある画像の総数を減らすことができます。キャッシュされた最適化画像の存続時間 (TTL) を秒単位で設定できます。多くの場合 静的画像のインポート の利用をお勧めします。これにより、ファイルの内容が自動的にハッシュ化され、immutable に設定された Cache-Control ヘッダーを使用して画像が永久にキャッシュされます。
module.exports = {
images: {
minimumCacheTTL: 60,
},
}
ブラウザの Cache-Control ヘッダーを追加する必要がある場合 (非推奨) 、アップストリームイメージに headers を設定できます。 /some-asset.jpg は /_next/image 自体ではありません。
デフォルトの動作では、import icon from './icon.png のようにして静的ファイルをインポートし、それを src プロパティに渡すことができます。
いくつかのケースにおいて、インポートの動作が異なることを期待する他のプラグインと競合する場合は、この機能を無効にすることをお勧めします。
next.config.js 内で静的画像のインポートを無効にできます。
module.exports = {
images: {
disableStaticImages: true,
},
}
デフォルトの ローダー はいくつかの理由で SVG 画像を最適化しません。まず最初の理由として、SVG はベクトル形式であるため、サイズを変更しても劣化しません。次に、SVG は HTML/CSS と同じ特徴を多く持っており、適切な コンテンツセキュリティポリシー (CSP) ヘッダー が無いと脆弱性につながる可能性があります。
デフォルトの画像最適化 API で SVG 画像を提供する必要がある場合、next.config.js で dangerouslyAllowSVG と contentSecurityPolicy を設定できます:
module.exports = {
images: {
dangerouslyAllowSVG: true,
contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
},
}
Image コンポーネントの機能と使用ガイドラインの概要については、以下を参照してください: