Contentfulにアップロードした画像を取得する方法が分からないかもしれません。この記事では、ContentfulのImages APIでできることを一覧で示しつつ、それぞれの概要と使い方をコードで示します。
本ブログはContentfulを用いていて、Images APIも使っています。このときに調べたことを、備忘録的にまとめたのがこの記事となります。よかったら参考にしてください。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
動作環境
まずはじめに、この記事の内容を検証した環境を示します。この記事はJavaScriptのコードを示しているので、JavaScript用のクライアントのバージョンを示します。
ライブラリ | バージョン | リリース日 |
---|---|---|
contentful | 8.2.1 | 2021-3-29 |
curlなど他のコード例は、公式ドキュメントをご確認ください。
ContentfulのImages APIとは
ContentfulのImages APIとは、「画像ファイルを取得して操作するためのAPI」です。たとえば、次のようなコードがあるとします。
const contentful = require('contentful') const client = contentful.createClient({ space: '<space_id>', accessToken: '<content_delivery_api_key>', }) const asset = client.getAsset('<asset_id>').then((asset) => { // ここで画像を操作すると仮定する })
このgetAsset()
の返り値asset
を用いると、画像の取得は次のようになります。
asset.fields.file.url
この記事で示すすべてのコード例は、上記のようにasset
オブジェクトを元に操作するものとします。
ContentfulのImages APIの操作一覧
それでは、ContentfulのImages APIでできる操作の一覧をまとめていきます。
この記事の内容は、執筆時点のものとなっています。Contentful側のアップデートにより、内容が古くなっている可能性があります。APIを使うときは、公式ドキュメントを確認するようにしてください。
1. フォーマットを変更する
画像のフォーマットを変更します。変更可能なフォーマットは次の通りです。
フォーマット | 値 |
---|---|
JPEG | jpg |
PNG | png |
WEBP | webp |
デフォルトは元の画像のフォーマットです。たとえば、PNGとしてアップロードした画像を取得時にJPEGに変更するには、次のようになります。
`${asset.fields.file.url}?fm=jpg`
2. プログレッシブJPEGに変換する
「プログレッシブJPEGとは何?」によると、プログレッシブJPEGについて次のように説明されています。
コンピューターにダウンロードして表示する際、画像の上辺から下辺に向かって表示するのではなく、はじめに大まかなモザイク状の画像を表示し、次第に鮮明になるため、ダウンロードの途中でもおよその画像内容を把握できる。
つまり、画像を最初に粗く表示し、徐々に鮮明な画像として表示していくフォーマットです。早い段階で画像を表示できるため、レイアウトの崩れなどを防ぐことができます。画像をプログレッシブJPEGに変換するには、次のように取得します。
`${asset.fields.file.url}?fm=jpg&fl=progressive`
3. 8ビットPNGに変換する
8ビットPNGは、PNGとして標準の24ビットよりも軽量なフォーマットです。アイコンやロゴのようなシンプルな画像に適しています。画像を8ビットPNGに変換するには、次のように取得します。
`${asset.fields.file.url}?fm=png&fl=png8`
4. リサイズする
画像のサイズ、つまり幅と高さを変更します。最大値は4,000ピクセルです。画像をリサイズするには、次のように取得します。
`${asset.fields.file.url}?w=100&h=100`
5. リサイズ時の動作を変更する
画像のサイズを変更したときの動作を指定できます。デフォルトではそのまま拡大・縮小しますが、次の値を指定できます。
値 | 内容 |
---|---|
pad | 必要に応じて画像の周りを埋める |
fill | 必要に応じて画像をトリミングする |
scale | 必要に応じてアスペクト比を変更する |
crop | 一部をトリミングしてサイズを合わせる |
thumb | サムネイルを作成する |
pad
を指定すると、画像の周りを単色で埋めることになります。この色は「9. 背景色を指定する」で指定できます。画像をリサイズするには、次のように取得します。
`${asset.fields.file.url}?fit=pad`
6. 焦点を指定する
リサイズ時の動作を変更したときに、値としてpad
またはfill
、crop
、thumb
を指定した場合、どこに焦点を置くかを次の中から指定できます。
値 | 内容 |
---|---|
center, top, right, left, bottom | - |
top_right, top_left, bottom_right, bottom_left | - |
face | 検出された顔の中で一番大きいもの |
faces | 検出されたすべての顔 |
焦点を指定するには、次のように画像を取得します。
`${asset.fields.file.url}?f=face&fit=thumb`
7. 角丸・円を指定する
画像の角を丸くしたり、円や楕円にトリミングできます。デフォルトは指定なしです。設定可能な値は次のとおりです。
値 | 内容 |
---|---|
(角の半径) | ピクセルで指定する |
max | 完全な円もしくは楕円にする |
角の半径を0以外として指定した場合、「9. 背景色を指定する」で背景色を指定できます。デフォルトは白です。画像に角丸や円を指定するには、次のように取得します。
`${asset.fields.file.url}?r=20`
8. 品質を指定する
画像の品質を1〜100で指定できます。画像のフォーマットが8ビットPNGのときは無視されます。画像の品質を指定するには、次のように取得します。
`${asset.fields.file.url}?fm=jpg&q=50`
9. 背景色を指定する
リサイズ時の動作がpad
のとき、あるいは角丸や円を指定したときに背景色を指定できます。値としてはRGB値を受け入れます。デフォルト値は、画像のフォーマットがJPEGのときは白、PNGまたはWEBPのときは透明になります。背景色を指定するには、次のように取得します。
`${asset.fields.file.url}?bg=rgb:ffffff`