ACFで画像を表示する方法

ACF（SCF）の画像フィールドは、フィールド設定の「返り値」（ID・URL・配列）でテンプレートの書き方が変わります。ここを知らずにコピペすると「Array」と表示されたり、alt属性が空になったりします。結論——返り値は「画像ID」にしてwp_get_attachment_image()に渡すのがいちばん楽で、altとレスポンシブ対応まで自動です。

まず確認：画像フィールドの「返り値」3種

フィールドの編集画面（「フィールドグループ」→対象のフィールド）に「返り値」という設定があります。ここで選んだ形式によって、get_field('photo')が返してくるものが変わります。

どれが正解ということはなく、「これから書くコードに合う形式を選ぶ」のがコツです。既存サイトを引き継いだときは、まず設定画面でどれになっているかを確認します。

おすすめ：IDで受け取ってwp_get_attachment_image()に渡す

返り値を画像IDにしておくと、テンプレートは実質1行です。

<?php echo wp_get_attachment_image(get_field('photo'), 'large'); ?>

これだけで、こんなimgタグが出力されます。

<img width="1024" height="683" src="…-1024x683.jpg" class="attachment-large size-large"
     alt="雪の枝にとまるシマエナガ" loading="lazy" decoding="async"
     srcset="…-300x200.jpg 300w, …-768x512.jpg 768w, …-1024x683.jpg 1024w" sizes="…">

• alt属性——メディアライブラリの「代替テキスト」が自動で入る
• srcset / sizes——画面幅に合う大きさを自動で選ぶ（レスポンシブ対応）
• loading=“lazy”——表示領域に来るまで読みこみを遅らせる

自分で<img>を組み立てると、これらを全部手で書くことになります。IDで受け取るのは「WordPressに任せる」ための選択です。

クラスを足したいときは第3引数に配列を渡します。

<?php echo wp_get_attachment_image(get_field('photo'), 'large', false, ['class' => 'product-photo']); ?>

URLで受け取る場合

返り値が画像URLなら、the_field()でそのまま出せます。いちばん短い書き方です。

<img src="<?php the_field('photo'); ?>" alt="">

ただしaltは自分で書くことになるので、内容が決まっているならフィールドをもう1つ用意するか、下のように投稿タイトルを使います。

<img src="<?php echo esc_url(get_field('photo')); ?>" alt="<?php the_title_attribute(); ?>">

CSSの背景画像として使いたいときは、URL形式が便利です。

<div class="hero" style="background-image: url('<?php echo esc_url(get_field('hero')); ?>');">

配列で受け取る場合

返り値が画像配列なら、get_field()で変数に受けてからキーを取り出します。幅・高さ・キャプションまで使えるのが強みです。

<?php $img = get_field('photo'); ?>
<?php if ($img) : ?>
  <figure>
    <img src="<?php echo esc_url($img['sizes']['medium']); ?>"
         width="<?php echo esc_attr($img['sizes']['medium-width']); ?>"
         height="<?php echo esc_attr($img['sizes']['medium-height']); ?>"
         alt="<?php echo esc_attr($img['alt']); ?>">
    <?php if ($img['caption']) : ?>
      <figcaption><?php echo esc_html($img['caption']); ?></figcaption>
    <?php endif; ?>
  </figure>
<?php endif; ?>

よく使うキーはこの4つです。

• $img['url']——元サイズのURL
• $img['alt']——代替テキスト
• $img['caption']——キャプション
• $img['sizes']['medium']——中サイズのURL（thumbnail largeなども同じ形）

配列で受け取っていても、$img['ID']をwp_get_attachment_image()に渡せばsrcset付きのタグを作れます。「細かい情報は配列から、タグ生成は関数に」という合わせ技も便利です。

画像が未登録でも崩れないようにする

画像フィールドは空のこともある——ここを想定していないテンプレートは、画像を入れ忘れた投稿でレイアウトが崩れます。ifで囲むだけで防げます。

<?php if ($id = get_field('photo')) : ?>
  <?php echo wp_get_attachment_image($id, 'large'); ?>
<?php else : ?>
  <img src="<?php echo esc_url(get_template_directory_uri() . '/images/no-image.png'); ?>" alt="">
<?php endif; ?>

$id = get_field('photo')は「代入しつつ、その値が空かどうかを判定する」書き方です。1行で済むのでよく使われます。

繰り返しフィールドの中の画像

くり返しの中ではget_field()ではなくget_sub_field()を使います。ここは間違えやすいポイントです。

<?php if (have_rows('gallery')) : ?>
  <ul class="gallery">
    <?php while (have_rows('gallery')) : the_row(); ?>
      <li><?php echo wp_get_attachment_image(get_sub_field('image'), 'medium'); ?></li>
    <?php endwhile; ?>
  </ul>
<?php endif; ?>

まとめ

1. 画像フィールドは返り値の設定（ID・URL・配列）で書き方が変わる。まず設定画面を確認する
2. IDで受け取ってwp_get_attachment_image()が最短。alt・srcset・遅延読みこみまで自動で付く
3. URLはsrcや背景画像向き、配列はキャプションや幅・高さを使いたいとき向き
4. 空のときのifを必ず入れる。くり返しの中ではget_sub_field()を使う

画像は見た目のインパクトが大きいぶん、altやサイズの手ぬきがそのまま品質差になります。関数に任せられるところは任せてしまいましょう。