🚀

【Next.js和訳】API Reference/ next/image

2021.10.02に公開

Next.js

tech

この記事について

株式会社 UnReact はプロジェクトの一環としてNext.js ドキュメントの和訳を行っています。

この記事は、next/imageの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

next/image

Examples

Image Component

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

注意
このプロパティは、高度な使い方を想定しています。画像をイーガーで読み込むように切り替えると、通常はパフォーマンスが低下します。
代わりに priority プロパティを使用することをお勧めします。priority プロパティは、ほぼすべてのユースケースで適切に画像をイーガーでロードします。

画像の読み込み動作を指定します。デフォルトでは 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 が使用されていることを確認してください。

【Next.js和訳】API Reference/ next/image

この記事について

next/image

使用方法

必要なプロパティ

src

width

height

オプションの小道具

レイアウト

loader

sizes

quality

priority

placeholder

高度な Props

objectFit

objectPosition

onLoadingComplete

loading

blurDataURL

lazyBoundary

unoptimized

Other Props

スタイリング

関連項目

Discussion