【Next.js和訳】API Reference/ next/image
この記事について
この記事は、next/imageの記事を和訳したものです。
記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。
next/image
Examples
Version History
Version | Changes |
---|---|
バージョン | 変更点 |
v11.1.0 |
onLoadingComplete プロップと lazyBoundary プロップを追加しました。 |
v11.0.0 |
src プロップがスタティックインポートに対応しました。placeholder プロップが追加されました。blurDataURL プロップが追加されました。 |
v10.0.5 |
loader プロップが追加されました。 |
v10.0.1 |
layout プロップが追加されました。 |
v10.0.0 |
next/image が導入されました。 |
画像の最適化は、next/image
でエクスポートされる<Image />
コンポーネントで有効になります。
使用方法
例として、次のようなファイルを持つプロジェクトを考えてみましょう。
pages/index.js
public/me.png
最適化された画像を表示するには、次のようにします。
import Image from "next/image"
import profilePic from "../public/me.png"
function Home() {
return (
<>
<h1>My Homepage</h1>
<Image src={profilePic} alt="Picture of the author" />
<p>Welcome to my homepage!</p>
</>
)
}
export default Home
必要なプロパティ
<Image />
コンポーネントには、以下のプロパティが必要です。
src
必須で、以下のいずれかでなければなりません。
- 上記のサンプルコードのように、静的にインポートされたイメージファイル、または
- パス文字列。loaderによって、絶対的な外部 URL または内部パスのいずれかになります。
外部の URL を使用する場合は、next.config.js
の domains に追加する必要があります。
width
画像の幅をピクセル単位で指定します。単位のない整数でなければなりません。
必須です。ただし、静的にインポートされた画像や、layout="fill"
が指定された画像は除きます。
height
画像の高さをピクセル単位で指定します。単位のない整数である必要があります。
静的にインポートされた画像や layout="fill"
が指定されている画像を除き、必須です。
オプションの小道具
<Image />
コンポーネントは、オプションで次のプロパティを受け入れます。
レイアウト
ビューポートのサイズが変更されたときの画像のレイアウトの動作を指定します。
レイアウト | 動作 | srcSet | サイズ |
---|---|---|---|
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
レイアウトのデモ(デフォルト)-
intrinsic
レイアウトでは、画像は小さなビューポートに対しては寸法を縮小しますが、大きなビューポートに対しては元の寸法を維持します。
-
-
fixed
レイアウトのデモ-
fixid
レイアウトでは、ネイティブのimg
要素と同様に、ビューポートが変化しても画像の寸法は変更されません(レスポンシブではありません)。
-
-
responsive
レイアウトのデモ-
responsive
レイアウトでは、画像は小さいビューポートでは縮小され、大きいビューポートでは拡大されます。 - 親要素のスタイルシートで
display: block
が使用されていることを確認してください。
-
-
fill
レイアウトのデモ-
fill
では、親要素が相対的であれば、画像は幅と高さの両方を親要素の寸法に合わせて伸ばします。 - これは通常、
objectFit
プロパティと組み合わせて使用します。 - 親要素のスタイルシートで
position: relative
が指定されていることを確認してください。
-
- デモの背景画像
loader
URL の解決に使用されるカスタム関数です。デフォルトでは、next.config.js
の images
オブジェクトが使用されます。
loader
は、以下のパラメータを指定して文字列を返す関数です。
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} />
)
}
sizes
メディアクエリをデバイスサイズにマッピングする文字列。デフォルトでは 100vw
に設定されています。
layout="responsive"
または layout="fill"
を使用して、画像がビューポートと同じ幅にならない場合は、size
を設定することをお勧めします。
詳しくはこちらをご覧ください。
quality
最適化された画像の品質。1
~ 100
の整数で、100
が最高の品質です。デフォルトは 75
です。
priority
true の場合、画像は優先度が高いとみなされ、プリロードされます。
画像がフォールドの上に表示される場合にのみ使用する必要があります。デフォルトは false
です。
placeholder
画像のロード中に使用されるプレースホルダー。可能な値は blur
または empty
です。既定値は empty
です。
blur
の場合は、blurDataURL
プロパティがプレースホルダーとして使用されます。src
が静的インポートのオブジェクトで、インポートされた画像が jpg、png、webp の場合は、blurDataURL
が自動的に入力されます。
動的な画像の場合は、blurDataURL
プロパティを指定する必要があります。base64
の生成には Plaiceholder のようなソリューションが役立ちます。
empty
の場合、画像の読み込み中にはプレースホルダーは存在せず、空のスペースのみが存在します。
試しに使ってみてください。
高度な Props
場合によっては、より高度な使い方が必要になるかもしれません。<Image />
コンポーネントは、オプションで以下の高度なプロパティを受け入れることができます。
objectFit
layout="fill"
を使用した場合の画像のフィット感。
objectPosition
layout="fill"
を使用した場合の画像の位置。
onLoadingComplete
画像の読み込みが完了し、プレースホルダーが削除されると呼び出されるコールバック関数です。
onLoadingComplete
関数は、以下のプロパティを持つオブジェクトを 1 つのパラメータとして受け取ります。
loading
画像の読み込み動作を指定します。デフォルトでは lazy
に設定されています。
lazy
の場合、ビューポートから計算された距離に達するまで、画像の読み込みを延期します。
eager
の場合は、画像を直ちに読み込みます。
blurDataURL
src
画像が正常にロードされる前に、プレースホルダー画像として使用されるデータ URL です。placeholder="blur"
と組み合わせた場合のみ有効です。
base64 エンコードされた画像である必要があります。画像は拡大されてぼかされるので、非常に小さい画像(10px 以下)を推奨します。大きな画像をプレースホルダーとして含めると、アプリケーションのパフォーマンスが低下する可能性があります。
実際に試してみてください。
画像に合わせてソリッドカラーの DataURL を生成することもできます。
lazyBoundary
ビューポートと画像の交点を検出し、遅延読み込みをトリガするために使用されるバウンディングボックスとして機能する文字列(margin プロパティと同様の構文)です。デフォルトは "200px"
です。
unoptimized
true の場合、ソースイメージは、品質、サイズ、またはフォーマットを変更せずに、そのまま提供されます。デフォルトでは false
に設定されています。
Other Props
<Image />
コンポーネントのその他のプロパティは、以下の例外を除き、基礎となる img
要素に渡されます。
-
style
代わりにclassName
を使用します。 -
srcSet
代わりにDevice Sizesを使用してください。 -
ref
代わりにonLoadingComplete
を使用する。 -
decoding
常にasync
です。
スタイリング
next/image
は、画像のアスペクト比を維持し、累積レイアウトシフトを防ぐために、img
要素を他の div
要素でラップします。
基本となる img
要素にスタイルを追加するには、<Image />
コンポーネントに className
プロップを渡します。そして、Next.js のビルドイン CSS サポートを使って、そのクラスにルールを追加します。
注意:layout="fill"
を使用する場合は、親要素で position: relative
が使用されていることを確認してください。
関連項目
次に行うべきことの詳細については、以下のセクションをお勧めします。
画像の最適化
ドメインとローダーの設定方法をご覧ください。
Discussion