add_image_size() - テーマ専用画像サイズの登録・カスタマイズ | KoMariCote

add_image_size()

画像サイズを登録する(サムネイル)

WordPress では「メディア」から画像をアップロードすると、元画像とは別にいくつかの画像サイズを自動生成する機能があります。この自動生成される画像サイズを任意のサイズで作成したい場合に、add_image_size() を使用します。

使い方

【構文】

add_image_size( $name, $width, $height, $crop = false )
add_image_size('画像サイズの登録名', 横幅(px), 縦幅(px), 画像のトリミングを行うか(どの位置でトリミングするか));

【返り値】null(何も返さない)

パラメーター

  • $name (string)必須

    登録する画像サイズの名称

  • $width (int)オプション

    登録する画像サイズの横幅(px)

    【初期値】 0

  • $height (int)オプション

    登録する画像サイズの縦幅(px)

    【初期値】 0

  • $crop (bool | array)オプション

    画像のトリミング動作を指定

    【初期値】 false

    • true : 画像の中心に合わせて、指定された寸法にトリミング

    • false : スケーリングされた画像を表示

    • 配列の場合 : トリミングする位置を指定。配列の値は( x_crop_position, y_crop_position )
      x_crop_position(横)は、’left’ 、’center’ 、’right’
      y_crop_position(縦)は、’top’、’center’、’bottom’ の値を設定する。

縦横のサイズはpxで指定しますが、記述する際に「px」という単位は不要です。

詳細・注意事項

WordPressのメディアに画像をアップロードすると自動的にいくつかのサムネイルが作られます。

設定サイズの大きさに満たない画像は、サイズ以上の画像は作られません。大きいサイズの画像であればあるほど、たくさんのリサイズ画像が自動生成されます。

full
フルサイズ
オリジナルの画像サイズ
thumbnail
サムネイル
150 × 150
medium
中サイズ
300 × 300
large
大サイズ
1024 × 1024
medium_large
ミディアムラージ
768 × 0
名称なし
(WordPress 5.3から生成)
1536 × 1536
名称なし
(WordPress 5.3から生成)
2048 × 2048
image-scaled
2561px以上の画像の場合
2560px

サイトで表示するサムネイルにこの中のサイズが合えばこのまま利用できますが、そうでない場合はcssなどで調整が必要になります。しかし画像サイズを新たに登録することで、その手間をなくすことができます。使いやすいサイトのためにも覚えておきたいのが add_image_size() です。

画像サイズ登録名の付け方

WordPressに予約済みの画像サイズ名があるので、これら以外の画像名を設定します。

【予約済み画像サイズ名】 「thumb」、「thumbnail」、「medium」、「medium_large」、「large」、「post-thumbnail」

これらの画像サイズを変更したい場合は、画像名を利用してサイズを変更するという使い方ができますが、元々設定されているものをそのままにしておきたい場合は名前の付け方には注意しましょう。

すでに存在する画像サイズを上書きすることも可能

‘thumbnail’ や ‘medium’ など初期設定で画像サイズ登録されているものは、管理画面からの変更もできますが add_image_size() で上書きすることもできます。

add_image_size('thumbnail', 100, 100, true);
add_image_size('medium', 200, 200);
add_image_size('large', 300, 300);

管理画面で設定したメディアサイズより、functions.php などで書かれている内容が優先されます。設定を変更されると困る場合にもこちらに記載しておくと安心です。

トリミング指定の書き方($cropの指定方法)

add_image_size() ではトリミング位置を調整することができますが、初期値は false となっています。画像のトリミングはしないなら、 false を指定するか省略すればトリミングはせず、縦横の比率に合わせて拡大・縮小されて表示されます。

トリミングをする際は $crop のところに true を記述する必要があります。初期値は中央(center)になっていて、トリミング位置がここで問題なければ true の記載のみでOK。

中心以外を基点としてトリミングしたい場合には配列で位置を指定します。この時には array('X軸', 'Y軸') で指定します。X軸は ‘left’、’right’、’center’、Y軸は ‘top’、’bottom’、’center’ のいずれかを指定できます。

// 縦横サイズを指定して設定(画像を歪めず設定したサイズに比例したものが表示される)
add_image_size( 'new_image_size_name', 200, 180 );

// 画像の中心を基点としてトリミングして表示(はみ出た部分は表示されない)
add_image_size( 'new_image_size_name', 200, 180, true);

// トリミング位置を定義して設定する(下記コードは左上を基準としてトリミング)
add_image_size( 'new_image_size_name', 200, 180, array('left', 'top'));
左上を基点→array(‘left’, ’top’)、上部中心を基点→array(‘center’, ’top’)、右下を基点→array(‘right’, ’bottom’)、下部中心を基点→array(‘center’, ’bottom’)

設定をする前にアップロードされている画像には適用されない

add_image_size() で設定する内容は「画像アップロード時に生成される画像サイズ」です。設定した時に、すでにアップロードしている画像がある場合、それらがリサイズされることはありません。
アップロード済みのものもリサイズしたい場合は、再度アップロード&設定をし直すか、アップロードした画像をリサイズできるプラグインを使用します。

追加した画像サイズで表示させる

追加した画像サイズで表示させる場合は、画像出力コードの引数に画像サイズ名を指定します。

<?php 
  // 記事のアイキャッチを画像サイズを指定して出力
  the_post_thumbnail('new_thumbnail');
  // メディアに登録している特定の画像を画像サイズ指定で出力
  echo wp_get_attachment_image($thumbnail_id, 'new_thumbnail');
?>

投稿の画像サイズ選択肢に含める

投稿画面で新しく登録したサイズをしたい場合、 add_image_size() で登録しただけでは選択ができないため、以下のようなコードを追加します。

function my_images_size($sizes) {
  $image_sizes = array(
    'new_thumbnail' => __('新しいサムネイル'),
  );
  return array_merge($sizes, $image_sizes);
}
add_filter('image_size_names_choose', 'my_images_size');

画像サイズの増やし過ぎには注意

便利な画像サイズ追加設定ですが、増やし過ぎには注意が必要です。
画像サイズを追加すると、メディアにアップロードした際に追加したサイズ分の画像が増えることになります。

数が増えてくるほどサーバーを圧迫していくため、画像サイズを追加する際は気を付けておきたいところです。
使わない画像サイズは自動生成をしないようにする、画像1つ1つの容量を抑えるようにするなど対策しておきましょう。

公式コードファイルとドキュメントはこちら

/wp-includes/media.php

add_image_size() - WordPress.org

コード Reference 一覧へ