画像変換

コンテンツ編集者に実サイズの画像アップロードを要求する代わりに、Craft では必要に応じて自動的に画像を操作するための「画像変換」を定義できます。トランスフォームは 非破壊的 で、アップロードされた元画像には影響しません。

トランスフォームは、コントロールパネルで定義することも、テンプレートや GraphQL クエリから直接定義することもできます。

# コントロールパネルからトランスフォームの定義

「設定 > アセット > 画像変換」に移動し、「新しい画像変換」ボタンをクリックすることで、コントロールパネルからトランスフォームを定義できます。

トランスフォームには、次の設定があります。

名前 – ユーザーに対する画像変換の名前
ハンドル – テンプレートに対する画像変換のハンドル
モード – 変換モード
幅 – 変換結果の幅
高さ – 変換結果の高さ
品質 - 変換結果の画像品質（0 から 100）
画像フォーマット – 変換結果の画像フォーマット

モードには、次の値をセットできます。

切り抜き – 指定された幅と高さに画像を切り抜き、必要であれば画像を拡大します。（これがデフォルトのモードです。）
フィット – すべての寸法が指定された幅と高さに収まる範囲で、可能な限り大きいサイズになるよう画像を拡大・縮小します。
ストレッチ – 指定された幅と高さに画像を伸張します。

モードで「切り抜き」がセットされた場合、焦点が設定されていない画像に対して Craft がどのエリアを切り抜きの中心にすべきかを決定する「デフォルトの焦点」プルダウンが表示されます。オプションには、次のものが含まれます。

上左
上中
上右
中央 - 左
中央 - 中央
中央 - 右
下部左
下部中央
下部右

幅または高さのいずれかを空白のままにすると、その寸法は画像の縦横比を維持するようセットされます。例えば、600 x 400 ピクセルの画像があり、変形の幅を 60 に設定し、高さを空白のままにした場合、変形した画像の高さは 40 になります。

品質を空白のままにすると、Craft はコンフィグ設定 defaultImageQuality にセットされた品質を使用します

画像フォーマットには、次の値をセットできます。

画像フォーマットを空欄のままにすると、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) を参照してください。

← ユーザーフィールドエレメントクエリ →

画像変換

# コントロールパネルからトランスフォームの定義

# コントロールパネルで定義された画像変換を適用する

# テンプレート内でトランスフォームを定義する

# 利用可能な値

# 名前付けされた画像変換の上書き

# srcset サイズの生成

Was this page helpful?

# `srcset` サイズの生成