Gatsby Imageメモ
2021-10-09 06:08
2021-11-14 11:31
gatsby-plugin-imageの仕様に関するメモ。
公式ドキュメントを参照してまとめたもの。
旧仕様のgatsby-imageについては、移行などを含めて一切触れない。
コンポーネント
StaticImage
表示されるたびに常に同じ画像を出すような静的な画像の場合に使用。
props
後述の画像オプションと共通propsの他に、以下を受け取る。
| Prop | 型 | 初期値 | 説明 |
|---|---|---|---|
src | String | ビルド時に読み込む画像ソース (必須)。相対パスか絶対パスで指定 |
制約
- ローカル画像、URLから取得、どちらでも可能。
- いずれにせよビルド時に画像を取得するため、後から変更してもビルドするまでは更新されない。
- propsには静的な値かローカルスコープ内の変数を使用するのみ。
- StaticImageを使うコンポーネントの外側からpropsで渡すことはできない。
- 同様の理由で関数呼び出しの結果なども不可。
CSS-in-JSでの使用
- HOC1はサポートしない。
- 従って、Emotionやstyled-componentsなどのstyled関数も使用できない。
- Emotionの場合は代わりに
cssを使う。 - styled-componentsでは
cssは内部でstyled関数に変換されるので使用不可。
- Emotionの場合は代わりに
- propsで普通にスタイルを定義することは可能。共通props参照。
GatsbyImage
CMSから渡されるとか、表示されるたびに異なる画像を出すような動的な画像の場合に使用。
props
後述の共通propsと以下を受け取る。
| Prop | 型 | 初期値 | 説明 |
|---|---|---|---|
image | GatsbyImageData | gatsbyImageDataで返される画像オブジェクト |
画像オプションはGraphQLResolverに渡されるので扱いが異なる。
その他
以下はgatsby-source-*系のプラグインでそれぞれのCDNから取得する方法をネイティブにサポートしてる。
これ以外はgatsby-transformer-sharpで頑張る。
画像CDNとしてimgixも使える。画像処理が色々あって便利らしい。
どれも使ったことはないので詳細は割愛。
共通props
GatsbyImageとStaticImage両方で使えるもの。
これに加えて<img>タグの属性も使えて、使った場合は生成される<img>要素に転送される。
| Prop | 型 | 初期値 | 説明 |
|---|---|---|---|
alt | String | <img>の代替テキスト (必須) | |
as | ElementType | "div" | 外側のラッパーに使う要素 |
loading | "eager" | "lazy" | "lazy" | 画像の読み込みを遅延読み込みにするか否か。above-the-fold2に画像があるなら、ハイドレーション3前にロードするために"eager"にする |
className | String | 外側のラッパーに適用するCSSクラス | |
imgClassName | String | <img>に適用するCSSクラス | |
style | CSSProperties | 外側のラッパーに適用するインラインスタイル | |
imgStyle | CSSProperties | <img>に適用するインラインスタイル | |
backgroundColor | String | transparent | ラッパーに適用する背景色 |
objectFit | object-fit | cover | コンテナ内の画像のリサイズ動作 |
objectPosition | object-position | 50% 50% | コンテナ内の画像の位置 |
オプション
画像のオプション。StaticImageとGatsbyImageとで指定方法が異なる。
| コンポーネント | 渡し方 | 値 |
|---|---|---|
| StaticImage | コンポーネントのprops | 文字列 |
| GatsbyImage | gatsbyImageData (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な画像を使用する場合のみ |
quality | 50 | 生成される画像のデフォルト画質。フォーマット固有のオプションによって上書きされる |
outputPixelDensities | fixedの場合: [1, 2]constrainedの場合: [0.25, 0.5, 1, 2] | 生成する画像のピクセル密度のリスト。ソース画像よりも大きな画像を生成することはなく、常に等倍(1x)画像を含む。この値と画像のwidthの積によって生成される画像サイズが決まる。full-widthな画像では無視され、代わりにbreakpointsが使用される |
breakpoints | [750, 1080, 1366, 1920] | full-widthな画像の幅を指定。デフォルトでは一般的なデバイスの解像度に準じた値になっており、ブラウザが自動的に最適なものを選択する。ソース画像より大きな画像を生成することはない |
blurredOptions | None | blurredプレースホルダ画像に使用するオプション。placeholderがblurredでない場合は無視される |
tracedSVGOptions | None | tracedSVGプレースホルダ画像に使用するオプション。placeholderがtracedSVGでない場合は無視される。potrace optionsを参照 |
jpgOptions | None | JPG画像を生成する際にImageSharpノードに渡すオプション |
pngOptions | None | PNG画像を生成する際にImageSharpノードに渡すオプション |
webpOptions | None | WebP画像を生成する際にImageSharpノードに渡すオプション |
avifOptions | None | AVIF画像を生成する際にImageSharpノードに渡すオプション |
オプションごとの詳細
layout
生成される画像サイズとブラウザ上でのサイズ変更の動作を指定$$する。
| レイアウト | コンポーネントのprop | Resolverの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種類のパターンまたは使用しないのいずれかで指定する。
| プレースホルダ | コンポーネントのprop | Resolverの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に渡す。
ほとんどの場合は変更する必要がない特殊な設定。
渡したオブジェクトはデフォルト設定とマージされる。
| オプション名 | デフォルト | 説明 |
|---|---|---|
grayscale | false | 画像をグレースケールに変換する |
duotone | false | デュオトーン(2色の組み合わせの画像効果)を追加する。falseまたは{highlight: string, shadow: string, opacity: number}の形式でオブジェクトを指定 |
rotate | 0 | 画像を回転させる。度数で指定 |
trim | false | 不要な部分のトリミングを行う。sharpのドキュメント参照 |
cropFocus | "attention" / ATTENTION | クロップ動作の調整。strategy/position/gravityはsharpのドキュメント)を参照 |
fit | "cover" / COVER | 画像のリサイズ時とwidth/height指定時の動作を調整。sharpのドキュメント)を参照 |
ヘルパー関数
そのうち書く。