【WordPress】add_image_size() でカスタム画像サイズを追加する方法

WordPress は画像をアップロードすると、サムネイル・中・大といった複数のサイズを自動で作ってくれます。ですが「記事一覧のカードは横長で表示したい」「特定の場所だけ正方形で揃えたい」といった場面では、テーマ独自の画像サイズを用意したくなります。これを実現するのが add_image_size() です。この記事では、add_image_size() でカスタム画像サイズを定義し、the_post_thumbnail() や wp_get_attachment_image_src() で呼び出すまでの流れと、つまずきやすいポイントを解説します。

add_image_size() でできること

add_image_size() は、テーマやプラグインから「この幅・高さの画像サイズも作ってほしい」と WordPress に登録する関数です。登録しておくと、画像をアップロードしたタイミングで WordPress がそのサイズの画像ファイルを自動生成します。あとはサイズ名を指定して呼び出すだけで、用途にぴったり合った大きさの画像を出力できます。

WordPress には標準で thumbnail・medium・large といったサイズが用意されていますが、デザインに合わせてもっと細かく指定したいときに add_image_size() が役立ちます。たとえば「記事カード用に 600×400 の横長」「著者アイコン用に 80×80 の正方形」といった専用サイズを作れます。

前提：アイキャッチ機能を有効にする

add_image_size() をアイキャッチ画像（投稿サムネイル）に使う場合は、まずテーマでアイキャッチ機能そのものを有効にしておく必要があります。これを忘れると、そもそもアイキャッチを設定する欄が編集画面に表示されません。after_setup_theme フックの中で add_theme_support() を呼び出します。

<?php
function mytheme_setup() {
    // アイキャッチ画像（投稿サムネイル）を有効にする
    add_theme_support( 'post-thumbnails' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

これで投稿編集画面に「アイキャッチ画像」のパネルが表示され、画像を設定できるようになります。なお、メディアライブラリにアップロードした画像（添付ファイル）を wp_get_attachment_image_src() で直接扱うだけなら、この add_theme_support() は必須ではありません。ただし投稿のアイキャッチとして使うなら有効化しておきましょう。

基本の使い方

カスタムサイズの登録も after_setup_theme フックの中で行います。先ほどの mytheme_setup() に続けて add_image_size() を呼び出してみましょう。

<?php
function mytheme_setup() {
    add_theme_support( 'post-thumbnails' );

    // 記事カード用：幅600px・高さ400pxにトリミングして切り抜く
    add_image_size( 'card-thumb', 600, 400, true );

    // 著者アイコン用：80×80の正方形に切り抜く
    add_image_size( 'author-avatar', 80, 80, true );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

これで card-thumb と author-avatar という2つのサイズ名が使えるようになります。第1引数のサイズ名は、あとで画像を呼び出すときに指定する識別子なので、用途が分かる名前を付けておくと管理しやすくなります。

引数の意味を整理する

add_image_size() は最大4つの引数を取ります。それぞれの役割は次のとおりです。

幅か高さのどちらかだけを制限したい場合は、もう一方に 0 を渡します。たとえば add_image_size( 'wide', 1200, 0 ) なら、幅は最大1200pxに、高さは元画像の比率のまま自動調整されます。

ソフトクロップとハードクロップの違い

第4引数の $crop は、指定した幅・高さに対して画像をどう収めるかを決める重要な引数です。挙動が大きく変わるので、ここを理解しておきましょう。

ソフトクロップ（false）

$crop を false（または省略）にすると、ソフトクロップになります。これは「指定した幅・高さに収まるように、元画像の縦横比を保ったまま縮小する」動きです。たとえば 600×400 を指定しても、元画像の比率次第で実際の画像は 600×337 のように、どちらか一方が指定値より小さくなることがあります。比率が崩れず、画像の一部が切れることもありません。

ハードクロップ（true）

$crop を true にすると、ハードクロップになります。これは「指定した幅・高さぴったりに切り抜く」動きで、必要に応じて画像の一部がトリミング（切り落とし）されます。600×400 を指定すれば、どんな元画像でも必ず 600×400 の画像が作られます。記事一覧のカードのように、すべての画像を同じ大きさで揃えたいときはハードクロップが向いています。

切り抜く位置を指定する

ハードクロップでは、画像のどの部分を残すかを配列で指定できます。配列は array( 横方向, 縦方向 ) の形で、横方向は 'left' / 'center' / 'right'、縦方向は 'top' / 'center' / 'bottom' を渡します。たとえば人物写真で顔が上のほうにあるなら、上側を優先して残すよう指定すると便利です。

<?php
// 中央上を基準に600×400で切り抜く
add_image_size( 'card-top', 600, 400, array( 'center', 'top' ) );

// 左下を基準に切り抜く
add_image_size( 'card-bottom-left', 600, 400, array( 'left', 'bottom' ) );

単に true を渡した場合は、中央を基準（array( 'center', 'center' ) と同じ）に切り抜かれます。位置を細かく制御したいときだけ配列を使えば十分です。

登録したサイズを呼び出す

サイズを登録しただけでは画面には何も出ません。テンプレートからサイズ名を指定して呼び出します。投稿のアイキャッチ画像なら the_post_thumbnail() にサイズ名を渡すのが基本です。

<?php
// ループの中で、登録した card-thumb サイズのアイキャッチを表示する
if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'card-thumb' );
}

the_post_thumbnail( 'card-thumb' ) は、card-thumb サイズの <img> タグをそのまま出力します。src や width / height 属性も WordPress が自動で付けてくれます。

アイキャッチ以外の画像、たとえばメディアライブラリにある任意の添付ファイルを扱いたいときは、添付ファイルのID（アタッチメントID）を使って wp_get_attachment_image_src() でURLや実寸を取得できます。

<?php
// 添付ファイルIDを指定して、card-thumb サイズの情報を取得する
$image = wp_get_attachment_image_src( $attachment_id, 'card-thumb' );

if ( $image ) {
    // $image[0] = URL, $image[1] = 幅, $image[2] = 高さ
    printf(
        '<img src="%s" width="%d" height="%d" alt="">',
        esc_url( $image[0] ),
        (int) $image[1],
        (int) $image[2]
    );
}

wp_get_attachment_image_src() は、画像URL・幅・高さ・リサイズ済みかどうかを格納した配列を返します。<img> タグごと出力したい場合は、より手軽な wp_get_attachment_image( $attachment_id, 'card-thumb' ) を使う方法もあります。

既存の画像に新サイズが反映されないとき

add_image_size() でいちばん戸惑いやすいのが、「サイズを追加したのに、前からある画像で新サイズが出てこない」という現象です。これは不具合ではなく、WordPress の仕様によるものです。

サイズ画像は「アップロード時」に生成される

WordPress が各サイズの画像ファイルを実際に作るのは、画像をアップロードしたタイミングです。そのため、add_image_size() でサイズを登録した時点より前にアップロードした画像には、新しいサイズのファイルが存在しません。新サイズを呼び出しても、もっとも近いサイズや元画像にフォールバックして表示されることがあり、思った大きさにならない原因になります。サイズを追加した後に新しくアップロードした画像については、ちゃんと新サイズが生成されます。

既存画像は Regenerate Thumbnails で作り直す

すでにアップロード済みの画像にも新サイズを適用したいときは、画像を再生成（リサイズし直す）必要があります。手軽なのが Regenerate Thumbnails というプラグインで、これを使うとメディアライブラリ内のすべての画像について、現在登録されているサイズの画像をまとめて作り直してくれます。サイズの幅や高さを途中で変更したときも、古いサイズのままになっている画像を作り直すのに役立ちます。

プラグインを使わずに進めたい場合は、WP-CLI が使える環境であれば wp media regenerate コマンドでも同じことができます。いずれにせよ、「サイズを追加・変更したら、既存画像は再生成が必要」という点を覚えておくと混乱せずに済みます。

まとめ

add_image_size() を使えば、テーマのデザインに合わせた専用の画像サイズを定義できます。要点を整理しておきます。

• アイキャッチに使うなら、先に add_theme_support( 'post-thumbnails' ) を有効にする
• add_image_size( 名前, 幅, 高さ, crop ) でサイズを登録する
• crop は false でソフトクロップ（比率維持）、true や配列でハードクロップ（切り抜き）
• 呼び出しは the_post_thumbnail( 'サイズ名' ) や wp_get_attachment_image_src()
• 既存画像に新サイズを反映するには Regenerate Thumbnails などで再生成する

まずは記事一覧用のカードサイズを1つ登録し、新しい画像をアップロードして表示を確認するところから試してみてください。

参考リンク

• add_image_size() – Function | WordPress Developer Resources
• the_post_thumbnail() – Function | WordPress Developer Resources
• wp_get_attachment_image_src() – Function | WordPress Developer Resources