Advanced Custom Fields フィールド項目の取得・出力まとめ

更新2022/01/05

いつも迷う Advanced Custom Fields を使った時の出力方法をまとめています。

基本の出力

the_field(‘フィールド名’)

the_field() は、ACFフィールドの値を取得・出力してくれる関数です。
基本的な使い方として、引数にフィールド名をつけます。

<?php the_field('フィールド名'); ?>

「とある投稿のフィールドの値」を表示させたい場合は、フィールド名の後に post id を追加します。

<?php the_field($field_name, $post_id); ?>
$field_name取得・出力するフィールド名。
$post_id出力させたい値のある投稿ページのID(post id)を入力。省略時は現在の投稿ID。

入力項目が必須でないなら、空欄の場合もあるので条件分岐を追加しましょう。
条件分岐が必要だったり、変数に入れて使用する場合は the_field() ではなく get_field() を使います。

get_field(‘フィールド名’)

get_field() は値の取得だけを行います。
出力はしないので、「変数に入れて echo で出力する」という使い方が一般的です。

条件分岐を使ったり、何度もフィールドの値を使いたい時はこちらの方が便利。

フィールド項目に値がある場合のみ出力

$custom_field = get_field('フィールド名');
// $custom_field があれば値を出力させる
if($custom_field) {
  echo $custom_field;
}

出力フォーマットを変える

Wysiwyg エディタやテキストエリアなどを使うと改行がつきますが、それを出力の際になくすこともできます。
get_field() の引数 $format_value の部分を「false」にします。

【関連記事】フィールドタイプ【テキストエリア】の改行設定

$field = get_field($field_name, $post_id, $format_value);
$field1 = get_field('field_name', 110, false);
$field2 = get_field('field_name', false, false);
$post_id投稿を指定する場合は、その投稿ID。
現在のページの値を取得する場合、 $post_id は false にする。(trueだと表示されない)
$format_value改行をそのままつけるかどうかといったフォーマットの指定。
値は true か false。初期値は true。
falseにするとフォーマット無しで値を取得。

ページやカテゴリー、タグを指定して、そのフィールドの値を出力

post_id 以外にもさまざまなIDを指定して出力することができます。

$from_page_field = get_field('フィールド名','ページID');
$from_cat_field = get_field('フィールド名','category_カテゴリID');
$from_tag_field = get_field('フィールド名','post_tag_タグID');
$from_user_field = get_field('フィールド名','user_ユーザーID');
if($from_page_field) {
  echo $from_page_field;
}

返り値の値が一つだけの場合は、そのまま値として出力されますが、複数(Array)の場合は foreach を使って取り出す必要があります。

【参照】 ACF | get_field()

返り値が Array の場合の出力

返り値が複数の値(Array)になる場合、foreach を使います。

foreach($field_array as $val) {
  if(is_array($val)) {
    echo $val['label'];
  } else {
    echo $val;
  }
}

フィールドタイプが「チェックボックス」や「Select」の場合、返り値フォーマットが選べます。
「Value」「ラベル」「Both (Array)」の3種類です。

「返り値のフォーマット」Both というのは「Value」と「ラベル」、どちらも返り値としてあるということです。
一度フィールドを取得して、その中から出力したいものを指定します。

$field_array = get_field('フィールド名');
$field_label = $field_array['label']; // ラベル
$field_value = $field_array['value']; // 値

フィールドタイプ「画像」の出力

画像は「返り値のフォーマット」の選択によって出力方法が変わります。
返り値のフォーマットは「画像 配列」「画像 URL」「画像 ID」の3種類。

単純に画像だけ表示させられればOKな場合、フィールドを作るときに返り値を「画像 URL」にするのが一番簡単です。

返り値が「画像 URL」

画像のURLだけを返します。変数に入れてそのまま echo で出力できます。

$field_img = get_field('フィールド名');
echo '<img src="'.$field_img.'">

返り値が「画像 配列」

「画像 配列」という文字通り配列の値が返されるので、どの情報が必要か指定する必要があります。配列の中に url というキーがあるので、[url]を指定するとURLを返してくれます。

$field_img = get_field('フィールド名');
echo '<img src="'.$field_img[url].'">

返り値が「画像 ID」

まず wp_get_attachment_image_src() で画像情報を取得します。
その情報の中でURLは配列の[0]に入っているので、それを指定します。

$field_img = get_field('フィールド名');
$img_src = wp_get_attachment_image_src($field_img, 'full');
$img_src = $img_src[0];
echo '<img src="'.$img_src[0].'">

【参照】ACF | Image

フィールドタイプ「ラジオボタン」の出力

ラジオボタンの値だけを取りたい場合は、 get_filed()the_field() でそのまま出力すればいいのですが、値とラベル両方設定することもあります。

ACFカスタムフィールド設定画面

選択肢の値とラベルを出力するにはこのように書きます。

<?php
  $field = get_field_object('radio_field');
  $value = $field['value'];
  $label = $field['choices'][$value];
?>
<p>設定されている色は <span><?php echo $value; ?>、<?php echo $label; ?></span>です</p>

チェックがついている内容によって表示内容を変える時にも、ラジオボタンは便利です。

<?php
  $field = get_field_object('radio_field');
  $value = $field['value'];
  $label = $field['choices'][$value];
?>
<?php if($value == "red"): ?>
  <p>赤</p>
<?php elseif($value == "blue"): ?>
  <p>青</p>
<?php endif; ?>

フィールドタイプ「Group」の出力

グループフィールドを取得して、その中にあるフィールドを出力する形です。

$group_field = get_field('グループフィールド名');
echo $group_field['グループ内のサブフィールド名'];

// もしくはこちらでもOK
$group_field = get_field('グループフィールド名')['グループ内のサブフィールド名'];

グループフィールド名が「親」で、サブフィールドが「子」という関係なので、while文でループさせて取得・出力する形でもOK。

if(have_rows('グループフィールド名')) {
  while(have_rows('グループフィールド名')){
    the_row();
    the_sub_field('サブフィールド名');
  }
}

get_fields() で一括取得

個別に取得するのではなく、一括で取得する場合は get_fields() で読み込む。

参照 : Advance Custom fields(ACF)の出力方法まとめ【個別・一括】

$fields = get_fields();

// 指定ページのフィールド
get_fields('ページID');

// 指定カテゴリーのフィールド
get_fields('category_カテゴリID');

// 指定タグのフィールド
get_fields('post_tag_タグID');

// 指定ユーザーのフィールド
get_fields('user_ユーザーID');

データは配列なので foreach で個別に出力。

$fields = get_fields();
foreach($fields as $val) {
  echo $val;
}

ACFはドキュメントが充実しているので本家サイトはとても参考になります。
ACF | Resources, Documentation, API, How to & Tutorial Articles

ACF以外のカスタムフィールドプラグイン

ACF以外で使うカスタムフィールドのプラグインに Smart Custom Fields があります。
こちらは機能はACFほどありませんが、シンプルなカスタムフィールドを作るならおすすめです。
smart custom fieldsでカスタムフィールド作成

ACF関連記事

【Advanced Custom Fields のフィールド設定】
Advanced Custom Fields(無料版)をマスターする!ACFの詳しい使い方

【カスタムフィールドについて詳しく】
カスタムフィールドとは?WordPressで必要な入力項目を追加する

動作確認

  • WordPressバージョン:5.8.2
  • プラグインバージョン:5.11.4
  • 動作確認日:2022/01/05
TOPへ