画像変換
コンテンツ編集者に実サイズの画像アップロードを要求する代わりに、Craft では必要に応じて自動的に画像を操作するための「画像変換」を定義できます。トランスフォームは 非破壊的 で、アップロードされた元画像には影響しません。
トランスフォームは、コントロールパネルで定義することも、テンプレートや GraphQL クエリから直接定義することもできます。
# コントロールパネルからトランスフォームの定義
「設定 > アセット > 画像変換」に移動し、「新しい画像変換」ボタンをクリックすることで、コントロールパネルからトランスフォームを定義できます。
トランスフォームには、次の設定があります。
- 名前 – ユーザーに対する画像変換の名前
- ハンドル – テンプレートに対する画像変換のハンドル
- モード – 変換モード
- 幅 – 変換結果の幅
- 高さ – 変換結果の高さ
- 品質 - 変換結果の画像品質(0 から 100)
- 画像フォーマット – 変換結果の画像フォーマット
モードには、次の値をセットできます。
- 切り抜き – 指定された幅と高さに画像を切り抜き、必要であれば画像を拡大します。(これがデフォルトのモードです。)
- フィット – すべての寸法が指定された幅と高さに収まる範囲で、可能な限り大きいサイズになるよう画像を拡大・縮小します。
- ストレッチ – 指定された幅と高さに画像を伸張します。
モードで「切り抜き」がセットされた場合、焦点が設定されていない画像に対して Craft がどのエリアを切り抜きの中心にすべきかを決定する「デフォルトの焦点」プルダウンが表示されます。オプションには、次のものが含まれます。
- 上左
- 上中
- 上右
- 中央 - 左
- 中央 - 中央
- 中央 - 右
- 下部左
- 下部中央
- 下部右
幅または高さのいずれかを空白のままにすると、その寸法は画像の縦横比を維持するようセットされます。例えば、600 x 400 ピクセルの画像があり、変形の幅を 60 に設定し、高さを空白のままにした場合、変形した画像の高さは 40 になります。
品質を空白のままにすると、Craft はコンフィグ設定 defaultImageQuality にセットされた品質を使用します
画像フォーマットには、次の値をセットできます。
- jpg
- png
- gif
画像フォーマットを空欄のままにすると、Craft は web-safe(.jpg、 .png、または .gif) なら元画像のフォーマットを使い、そうでなければ、そのジョブに最適な画像フォーマットを見つけようと試みます。(おそらく、ImageMagik がインストールされていないために)それを決定できない場合は、.jpg として処理されます。
# コントロールパネルで定義された画像変換を適用する
トランスフォームを適用した画像を出力するには、トランスフォームのハンドルをアセットの getUrl() (opens new window)、getWidth() (opens new window)、および、getHeight() (opens new window) ファンクションに渡します。
<img src="{{ asset.getUrl('thumb') }}"
width="{{ asset.getWidth('thumb') }}"
height="{{ asset.getHeight('thumb') }}"
>
# テンプレート内でトランスフォームを定義する
テンプレート内で直接トランスフォームを定義することもできます。
はじめに、トランスフォームのパラメータを定義したハッシュを作成する必要があります。
{% set thumb = {
mode: 'crop',
width: 100,
height: 100,
quality: 75,
position: 'top-center'
} %}
次に、そのハッシュをアセットの getUrl()
、getWidth()
、および、getHeight()
ファンクションへ渡します。
<img src="{{ asset.getUrl(thumb) }}"
width="{{ asset.getWidth(thumb) }}"
height="{{ asset.getHeight(thumb) }}"
>
ここでは、最初の例のように「thumb
」の周りに引用符がないことに注意してください。最初の例ではコントロールパネルで定義されたトランスフォームのハンドルを文字列として渡しているのに対して、この例ではテンプレート内で作成した thumb
ハッシュを参照するための変数として渡しているためです。
# 利用可能な値
コントロールパネルで定義されたトランスフォームで利用可能なすべて設定は、同様にテンプレートで定義されたトランスフォームでも利用できます。
mode
プロパティには、'crop'
、'fit'
、または、'stretch'
をセットできます。mode
に'crop'
をセットした場合、position
プロパティに'top-left'
、'top-center'
、'top-right'
、'center-left'
、'center-center'
、'center-right'
、'bottom-left'
、'bottom-center'
、または、'bottom-right'
のいずれかをセットして渡すことができます。width
とheight
は、整数をセットするか、省略できます。quality
は、0 から 100 の間の数値をセットするか、省略できます。format
には'jpg'
、'gif'
、'png'
をセットするか、省略できます。
# 名前付けされた画像変換の上書き
Craft 3.5 から getUrl()
の transform
プロパティで テンプレート内で名前付き画像変換を使用し、必要に応じて他のプロパティを上書きできます。
この例では、myNamedTransform
で定義されたルールを利用していますが、明示的に webp
画像を出力しています。
<source type="image/webp" srcset="{{ asset.getUrl({
transform: 'myNamedTransform',
format: 'webp',
}) }}">
# srcset
サイズの生成
1つの画像サイズだけでなく、srcset
(opens new window) で使用するための様々な画像が必要になるのが一般的です。
これを実現する方法の1つは、テンプレートファンクションの tag
と Craft 3.5 の新しい getSrcSet()
(opens new window) メソッドを組み合わせて、初期の寸法から相対的な srcset
サイズの画像タグを出力することです。
{% do asset.setTransform({ width: 300, height: 300 }) %}
{{ tag('img', {
src: asset.url,
width: asset.width,
height: asset.height,
srcset: asset.getSrcset(['1.5x', '2x', '3x']),
alt: asset.title,
}) }}
getImg()
(opens new window) メソッドに引数 sizes
を渡せば、同じことができます。
{{ asset.getImg({ width: 300, height: 300 }, ['1.5x', '2x', '3x']) }}
Eager-Loading でアセットトランスフォームする際に、相対的な画像サイズを指定することもできます。実例については、クラスリファレンスの AssetQuery::withTransforms()
(opens new window) を参照してください。