Gatsby Imageメモ

gatsby-plugin-imageの仕様に関するメモ。 公式ドキュメントを参照してまとめたもの。 旧仕様のgatsby-imageについては、移行などを含めて一切触れない。

コンポーネント

StaticImage

表示されるたびに常に同じ画像を出すような静的な画像の場合に使用。

props

後述の画像オプションと共通propsの他に、以下を受け取る。

Prop初期値説明
srcStringビルド時に読み込む画像ソース (必須)。相対パスか絶対パスで指定

制約

  • ローカル画像、URLから取得、どちらでも可能。
  • いずれにせよビルド時に画像を取得するため、後から変更してもビルドするまでは更新されない。
  • propsには静的な値かローカルスコープ内の変数を使用するのみ。
    • StaticImageを使うコンポーネントの外側からpropsで渡すことはできない。
    • 同様の理由で関数呼び出しの結果なども不可。

CSS-in-JSでの使用

  • HOC1はサポートしない。
  • 従って、Emotionやstyled-componentsなどのstyled関数も使用できない。
    • Emotionの場合は代わりにcssを使う。
    • styled-componentsではcssは内部でstyled関数に変換されるので使用不可。
  • propsで普通にスタイルを定義することは可能。共通props参照。

GatsbyImage

CMSから渡されるとか、表示されるたびに異なる画像を出すような動的な画像の場合に使用。

props

後述の共通propsと以下を受け取る。

Prop初期値説明
imageGatsbyImageDatagatsbyImageDataで返される画像オブジェクト

画像オプションはGraphQLResolverに渡されるので扱いが異なる。

その他

以下はgatsby-source-*系のプラグインでそれぞれのCDNから取得する方法をネイティブにサポートしてる。 これ以外はgatsby-transformer-sharpで頑張る。

画像CDNとしてimgixも使える。画像処理が色々あって便利らしい。

どれも使ったことはないので詳細は割愛。

共通props

GatsbyImageとStaticImage両方で使えるもの。 これに加えて<img>タグの属性も使えて、使った場合は生成される<img>要素に転送される。

Prop初期値説明
altString<img>の代替テキスト (必須)
asElementType"div"外側のラッパーに使う要素
loading"eager" | "lazy""lazy"画像の読み込みを遅延読み込みにするか否か。above-the-fold2に画像があるなら、ハイドレーション3前にロードするために"eager"にする
classNameString外側のラッパーに適用するCSSクラス
imgClassNameString<img>に適用するCSSクラス
styleCSSProperties外側のラッパーに適用するインラインスタイル
imgStyleCSSProperties<img>に適用するインラインスタイル
backgroundColorStringtransparentラッパーに適用する背景色
objectFitobject-fitcoverコンテナ内の画像のリサイズ動作
objectPositionobject-position50% 50%コンテナ内の画像の位置

オプション

画像のオプション。StaticImageとGatsbyImageとで指定方法が異なる。

コンポーネント渡し方
StaticImageコンポーネントのprops文字列
GatsbyImagegatsbyImageData (GraphQL)GraphQL enum (大文字/引用符なし)

動的な画像の場合、オプションはgatsby-transformer-sharpで作られる ImageSharpノードのgatsbyImageDataResolverで使う。 CMSや画像ホスト等の別のプラグインからgatsbyImageDataを使う場合、オプションはそれぞれのプラグインに準拠する。 静的な画像の場合も内部ではImageSharpノードを使っているため、StaticImageでもオプションは適用される。

オプション一覧

オプション初期値/enum説明
layout"constrained" / CONSTRAINED画像サイズとリサイズの動作
aspectRatioソース画像のアスペクト比画像の幅(width)と高さ(height)の比率を強制的に指定
width/heightソース画像のwidth/height画像サイズの変更
placeholder"dominantColor"/DOMINANT_COLORフル画像のロード中に表示されるプレースホルダ画像のスタイル
formats["auto","webp"]/[AUTO,WEBP]生成される画像のファイルフォーマット
transformOptions{fit: "cover", cropFocus: "attention"}/{fit: COVER, cropFocus: ATTENTION}ImageSharpノードに渡すオプション。切り抜きなどの画像操作
sizes自動的に生成<img>タグのsizes属性。画像の表示サイズを指定するだけなので、生成される画像には影響しない。変更するのは画面の横幅いっぱいに表示しないfull-widthな画像を使用する場合のみ
quality50生成される画像のデフォルト画質。フォーマット固有のオプションによって上書きされる
outputPixelDensitiesfixedの場合: [1, 2]
constrainedの場合: [0.25, 0.5, 1, 2]
生成する画像のピクセル密度のリスト。ソース画像よりも大きな画像を生成することはなく、常に等倍(1x)画像を含む。この値と画像のwidthの積によって生成される画像サイズが決まる。full-widthな画像では無視され、代わりにbreakpointsが使用される
breakpoints[750, 1080, 1366, 1920]full-widthな画像の幅を指定。デフォルトでは一般的なデバイスの解像度に準じた値になっており、ブラウザが自動的に最適なものを選択する。ソース画像より大きな画像を生成することはない
blurredOptionsNoneblurredプレースホルダ画像に使用するオプション。placeholderblurredでない場合は無視される
tracedSVGOptionsNonetracedSVGプレースホルダ画像に使用するオプション。placeholdertracedSVGでない場合は無視される。potrace optionsを参照
jpgOptionsNoneJPG画像を生成する際にImageSharpノードに渡すオプション
pngOptionsNonePNG画像を生成する際にImageSharpノードに渡すオプション
webpOptionsNoneWebP画像を生成する際にImageSharpノードに渡すオプション
avifOptionsNoneAVIF画像を生成する際にImageSharpノードに渡すオプション

オプションごとの詳細

layout

生成される画像サイズとブラウザ上でのサイズ変更の動作を指定$$する。

レイアウトコンポーネントのpropResolverのprop説明
Constrained"constrained"CONSTRAINEDデフォルト。ソース画像のサイズで画像を表示する (width/heightを指定して最大サイズを指定することも可能)。スクリーンやコンテナのサイズが画像の幅より小さい場合は、アスペクト比を維持したまま縮小する。モバイル端末での容量削減のため縮小版の画像を生成
Fixed"fixed"FIXED固定サイズの画像。コンテナに合わせて縮小することはなく、常に同じサイズで表示される。サイズはソース画像のままか、もしくはwidth/heightで指定する。コンテナが画像よりも小さい状態にならない場合のみ使用すること
Full width"fullWidth"FULL_WIDTH画面横幅いっぱいに表示する画像に使用 (バナーやヒーロー画像等)。Constrainedと同じくコンテナに合わせてサイズが変更されるが、最大サイズの制限はないため、アスペクト比を維持したままコンテナの大きさに合わせて拡大する。breakpointsごとに画像が生成され、画面に必要な大きさの画像をブラウザがロードする。breakpointsは指定可能だが、大体の場合デフォルトサイズで事足りる

aspectRatio

layout: 全て (constrained/fixed/fullWidth)

画像のアスペクト比を強制的に変更し、必要に応じてトリミングする。 数値で指定するが、aspectRatio={16/9}のような形で指定する方が直感的にわかりやすいため推奨される。

Fixed、Constrainedの場合は、以下のような動きになる。

  • width/heightのどちらかを指定すると、aspectRatioに従ってもう一方が自動的に計算される。
    • 例えばwidth={800} aspectRatio={4/3}の場合、heightは600になる。
  • aspectRatioを1にすると、正方形にトリミングされる。
  • width/heightを指定しない場合、ソース画像のwidthが使用される。

Full Widthの場合は、以下のような動きになる。

  • 画面の幅に合わせてリサイズされるためwidth/heightを指定する必要はない。
  • aspectRatioを渡すと必要に応じてトリミングされ、高さは画面の幅に合わせて調整される。
    • 例えばaspectRatio={16/9}を設定した場合、横幅1280pxの画面ではheightが720pxになる。

注: トリミングやリサイズの動作を指定する必要がある場合はtransformOptionsを使用する。

width/height

layout: contrained/fixed

StaticImageとGatsbyImageではビルド時にソース画像のサイズを自動的に取得するため、そこから変更したい時のみwidth/heightを指定する。 Fixedの場合は画面に表示される画像サイズを指定。 Containedの場合はコンテナの大きさに応じて画像が縮小されるため、width/heightは最大サイズとなる。

width/heightどちらか一方だけを設定した場合、ソース画像はアスペクト比を維持したまま指定のwidthまたはheightまでリサイズされる。 両方を設定した場合は、設定されたサイズに応じて切り取られる。

placeholder

デフォルトでは画面上に画像が現れるまで読み込まない遅延ロードをするため、画像のロード前にプレースホルダが表示されることになる。 そのプレースホルダを、3種類のパターンまたは使用しないのいずれかで指定する。

プレースホルダコンポーネントのpropResolverのprop説明
Dominant color"dominantColor"DOMINANT_COLORデフォルト。ソース画像のドミナントカラーを計算して背景色にする
Blurred"blurred"BLURREDソース画像から低解像度画像を生成してボカした背景にする
Traced SVG"tracedSVG"TRACED_SVGソース画像から簡略化・平坦化したSVG画像を生成して使用する。単純な形状の画像や透明度を含む画像に適する
None"none"NONEプレースホルダなし。backgroundColorを使って静的な背景色を指定することが可能

formats

コンポーネントのデフォルト値: ["auto", "webp"]
リゾルバのデフォルト値: [AUTO, WEBP]

画像の出力フォーマットが、JPEG、PNG、WebP、AVIFの4種類サポートされている。 デフォルトでは、ソース画像と同じフォーマットの画像を生成すると同時にWebPを生成する。 例えばPNG画像の場合は、PNGとWebP画像を生成することになる。

ほとんどの場合はこの設定から変更する必要はないが、何らかの理由で必要な場合はフォーマットを設定する。 一例として、AVIF画像4を使いたい場合など。 今の所ブラウザサポートは限られるが、その辺りはGatsby Imageがデフォルトで自動判別して表示するようになっている。

transformOptions

以下の設定値は、オブジェクトとしてtransformOptionsに渡す。 ほとんどの場合は変更する必要がない特殊な設定。 渡したオブジェクトはデフォルト設定とマージされる。

オプション名デフォルト説明
grayscalefalse画像をグレースケールに変換する
duotonefalseデュオトーン(2色の組み合わせの画像効果)を追加する。falseまたは{highlight: string, shadow: string, opacity: number}の形式でオブジェクトを指定
rotate0画像を回転させる。度数で指定
trimfalse不要な部分のトリミングを行う。sharpのドキュメント参照
cropFocus"attention" / ATTENTIONクロップ動作の調整。strategy/position/gravityはsharpのドキュメント)を参照
fit"cover" / COVER画像のリサイズ時とwidth/height指定時の動作を調整。sharpのドキュメント)を参照

ヘルパー関数

そのうち書く。


  1. 高階コンポーネント。コンポーネントを受け取って新しいコンポーネントを返す関数。
  2. 画面表示した時にスクロールしないで見える領域。
  3. プリレンダー時は最低限のJavaScriptのみ生成して、ブラウザロード時にJavaScriptが必要なものを引っ張ってくるやつ。
  4. 圧縮率が高かったりHEIFと比べてライセンス料が要らなかったりする次世代の画像規格

止まらない実行を目指すITエンジニア。

© 2020-2022, Ryz