ACFフィールド別・表示の書き方早見表

ACF（SCF）はフィールドの種類によって返ってくる形が違うため、書き方も変わります。この記事は「このフィールド、どう出すんだった？」を1画面で解決するための早見表です。上から探して、必要な行だけコピーしてください。

ぜんぶ一覧（返ってくる形と最短のコード）

以下、つまずきやすいものだけ実コードで補足します。

画像

返り値の設定（ID・URL・配列）で書き方が変わります。IDにしておけば1行で、alt・srcset付きのタグが出ます。

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

ファイル

返り値を配列にしておくと、ファイル名やサイズも出せます。

<?php if ($file = get_field('pdf')) : ?>
  <a href="<?php echo esc_url($file['url']); ?>" download>
    <?php echo esc_html($file['filename']); ?>（<?php echo esc_html(size_format($file['filesize'])); ?>）
  </a>
<?php endif; ?>

size_format()はWordPressの関数で、バイト数を「1.2 MB」のような表記に変換してくれます。

リンク

リンクフィールドはurl・title・targetの3つが入った配列です。別タブ設定まで拾えます。

<?php $link = get_field('button'); ?>
<?php if ($link) : ?>
  <a class="button" href="<?php echo esc_url($link['url']); ?>"
     target="<?php echo esc_attr($link['target'] ?: '_self'); ?>">
    <?php echo esc_html($link['title']); ?>
  </a>
<?php endif; ?>

?:は「左が空なら右を使う」という短い書き方です（target未設定のときに_selfを入れています）。

選択・ラジオ・チェックボックス

• 選択・ラジオ——ふつうは文字列。設定の「返り値」をラベルにすると表示用の文言が返ります
• チェックボックス——必ず配列。そのまま出すと「Array」になります

<?php $tags = get_field('features'); ?>
<?php if ($tags) : ?>
  <ul>
    <?php foreach ($tags as $t) : ?>
      <li><?php echo esc_html($t); ?></li>
    <?php endforeach; ?>
  </ul>
<?php endif; ?>

返り値を「値とラベル（配列）」にした場合は、$t['label']で表示名を取り出します。

真偽値（true / false）

「新着マークを出すかどうか」のようなスイッチです。出力するのではなく分岐に使うのがふつうです。

<?php if (get_field('is_new')) : ?>
  <span class="badge">NEW</span>
<?php endif; ?>

日付

日付フィールドは文字列で保存されています（既定はYmd＝20260725のような形）。日本語表記にするには整形します。

<?php if ($ymd = get_field('event_date')) : ?>
  <?php $d = DateTime::createFromFormat('Ymd', $ymd); ?>
  <time datetime="<?php echo esc_attr($d->format('Y-m-d')); ?>">
    <?php echo esc_html($d->format('Y年n月j日')); ?>
  </time>
<?php endif; ?>

投稿オブジェクト・関連

「この商品に関連する記事」のように別の投稿を選ばせるフィールドです。返ってくるのは投稿オブジェクト（WP_Post）なので、get_permalink()などに渡せます。

<?php $post_obj = get_field('related_post'); ?>
<?php if ($post_obj) : ?>
  <a href="<?php echo esc_url(get_permalink($post_obj)); ?>">
    <?php echo esc_html(get_the_title($post_obj)); ?>
  </a>
<?php endif; ?>

関連（relationship）は複数選べるので、返ってくるのは配列です。

<?php $items = get_field('related_items'); ?>
<?php if ($items) : ?>
  <ul>
    <?php foreach ($items as $item) : ?>
      <li>
        <a href="<?php echo esc_url(get_permalink($item)); ?>"><?php echo esc_html(get_the_title($item)); ?></a>
      </li>
    <?php endforeach; ?>
  </ul>
<?php endif; ?>

タクソノミー

タームオブジェクト（WP_Term）が返ります。複数選択の設定なら配列になるので、まずis_array()で見分けるか、設定を確認します。

<?php $term = get_field('genre'); ?>
<?php if ($term) : ?>
  <a href="<?php echo esc_url(get_term_link($term)); ?>"><?php echo esc_html($term->name); ?></a>
<?php endif; ?>

出力するときのエスケープ早見

the_field()はエスケープしないので、自分でechoするときは上の表に合わせるのが安全側の習慣です。

まとめ

1. フィールドの種類ごとに返ってくる形が違う——文字列・配列・オブジェクトの3系統を意識する
2. 表示だけならthe_field()、判定や取り出しがあるならget_field()
3. 配列をthe_field()で出すと「Array」。チェックボックス・リンク・グループなどが該当
4. 日付は文字列なのでDateTimeで整形。エスケープは出す場所に合わせて使い分ける

形が分かればあとは同じ書き方の繰り返しです。困ったらvar_dump()で1回のぞいてみると、迷いがすぐ消えます。