Advanced Custom Fields フィールドタイプの取得・出力まとめ

Advanced Custom Fields （ACF）は機能豊富なカスタムフィールド作成プラグインです。さまざまな入力方法や複雑な条件にも対応できます。

Advanced Custom Fields を使った時にフィールドタイプごとにどのような出力方法があるのか忘れがちなので、フィールドタイプ別の詳細メモとしてまとめています。

作成しようとしているカスタムフィールドに合ったフィールドタイプを選んで使いやすい投稿になるようご参考ください。

基本の取得・出力コード

入力したデータを取得・出力するためにACFには専用のコードがあります。いくつかのコードを覚えておくと表示設定が楽になるのでACFを使用するならおさえておきましょう。

the_field()

the_field() は、ACFフィールドの値を取得して出力するコードです。引数にフィールド名や投稿のIDをつけます。

the_field($selector, $post_id, $format_value);

$post_id や $format_value を省略できます。個別ページや投稿一覧表示の際にその投稿のフィールドの値を出力したい場合は $field_name だけでよく、この書き方が一番多く使います。

<?php the_field('field_name'); ?>

$post_id には投稿ページのみならずカテゴリーやタグ、ユーザーなどさまざまなIDを指定することもできます。

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

【参照】 ACF | the_field()

get_field()

get_field() は、ACFフィールドの値の取得だけを行うコードです。引数は the_field() と同じです。

get_field($selector, $post_id, $format_value);

この関数だけでは出力はされないため echo をつけてフィールドの値を表示させます。
条件分岐を使ったり、何度もフィールドの値を使いたい時はこちらを使用します。 変数に入れておくと使い回しができて便利です。

<?php
  $field = get_field('field_name');
  if($field) {
    echo $field;
  }
?>

【参照】 ACF | get_field()

get_fields()

get_fields() は特定の投稿にあるフィールド全てを一括で取得できます。

get_fields($post_id, $format_value);

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

<?php
  $fields = get_fields();
  foreach($fields as $key => $val):
?>
  <p><?php echo $key.' : '.$val; ?></p>
<?php endforeach; ?>

【参照】ACF | get_fields()

get_field_object()

ACFで作成する各フィールドにはラベルや名前、タイプなどの設定情報が含まれています。

特定の投稿かつ特定のフィールドの設定を値とともに取得できるのが get_field_object() です。

get_field_object($selector, $post_id, $format_value, $load_value);

get_field_object() は指定したフィールドの情報が、連想配列で返されます。取り出したい情報のあるキーを指定します。

$field = get_field_object("field_name");
echo $field['label'];
echo $field['value'];

どんなキーがあるのかはこちらのページで参照できます → ACF | get_field_object()
もしくは var_dump() を使って確認できます。

$field = get_field_object("field_name");
var_dump($field);

【参照】ACF | get_field_object()

get_field_objects()

特定の投稿に保存されているすべてのフィールドの設定を取得したい場合は get_field_objects() を使用します。

get_field_objects($post_id, $format_value, $load_value);

以下のようなコードで、現在の投稿のラベルと値を出力できます。

$fields = get_field_objects();
foreach($fields as $field) {
  echo $field['label'].' : '.$field['value'];
}

【参照】ACF | get_field_objects()

【PR】

フィールドに条件分岐をつける

入力項目が必須でない場合や何かしらの条件によって表示・非表示をしたい場合などは条件分岐を使いましょう。

以下のコードは「'field_name' の値があれば出力させる」という処理のコードです。必須項目になっていないフィールドの場合はこのようなコードを書くようにしましょう。

<?php
  // フィールドを取得して変数に入れる
  $custom_field = get_field('field_name');
  // $custom_field の値があれば出力させる
  if($custom_field) {
    echo $custom_field;
  }
?>

返り値が複数（Array）の場合の出力

チェックボックスなど複数の値が返される項目の場合、the_field() など一つの値を返すコードで出力しようとしても 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']; // 値

ACFのフィールドタイプ別　出力方法

ACFにはさまざまなフィールドタイプが用意されています。各フィールドタイプの出力方法を紹介します。

テキスト

テキストフィールドは the_field() や get_field() でそのまま出力できます。

<?php the_field('field_name'); ?>

<?php echo get_field('field_name'); ?>

テキストエリア

テキストエリアは改行の表示方法が3パターン用意されています。

• 自動的に段落追加する
• 自動的に＜br＞を追加
• 書式設定なし

設定できるのは1つだけですが、表示させる場所によっては書式を変えたいこともあるかもしれません。出力する際に書式を変更する方法があります。

「自動的に段落・＜br＞を追加」で設定したフィールドで書式を無しにする

段落や＜br＞を追加する設定した場合でも、「詳細ページでは改行させたいけど一覧で表示させる時には改行をなくしたい」ということもあるかと思います。

このような場合、引数 $format_value の部分を「false」にすると改行せずに表示させることができます。

the_field($selector, $post_id, $format_value);

the_field('field_name', false, false);

「書式設定なし」で設定したフィールドで改行をつける

書式なしにしたフィールドで、入力した通りに改行をつけたい場合は nl2br 関数を使用します。

the_field() だと nl2br を使っても改行されないので、get_field() で一度取得した後に nl2br を使って出力させます。

$textarea_normal = get_field('textarea_normal');
echo nl2br($textarea_normal);

PHP: nl2br – Manual

番号

「番号」フィールドでは全角文字や英字が入力できないようになっています。「.」ドット, 「+」プラス, 「-」マイナスは入力可能ですが、「,」コンマは使用できません。
そのため大きい数字を取り扱う場合など、区切りが欲しい場合は number_format 関数を利用します。

$field_num = get_field('number_sample');
echo number_format($field_num);

PHP: number_format – Manual

パスワード

基本的に入力しても表示されず黒丸で隠されてしまいますが、入力値を確認したい場合は the_field で確認できます。

画像

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

返り値が「画像 URL」

「画像URL」を設定した場合は画像のURLだけを返します。
単純に画像だけ表示させられればOKな場合、返り値を「画像URL」にするのが一番出力方法が簡単です。

// get_field() を使用
<?php
  $field_img = get_field('フィールド名');
?>
<img src="<?php echo $field_img; ?>">

// the_field() を使用
<img src="<?php the_field('フィールド名'); ?>">

返り値が「画像配列」

「画像配列」は文字通り画像の情報を配列で返されます。どの情報が必要か指定する必要があります。配列の中に [url] というキーがあるので、こちらを指定すると画像のパスが返されます。

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

オブジェクトの中にはさまざまな情報があるので、URL以外にも取得したい情報があるときや色々と情報を利用してカスタマイズしたい場合は「画像配列」の返り値を使用します。

返り値が「画像 ID」

「画像 ID」も文字通り画像に付けられる id が返されますがidの数字だけを出力しても画像は表示されません。そこで wp_get_attachment_image() を使って画像情報に変換して出力します。

$field_img = get_field('フィールド名');
$img_src = wp_get_attachment_image($field_img, 'full');
echo $img_src;

上記のコードからは以下のようなHTMLが出力されます。URLだけではなく、さまざまな画像情報が出力されるのがこの返り値にするメリットです。

<img width="800" height="800" 
src="画像までのパス.png" 
class="attachment-full size-full" alt="" 
decoding="async" fetchpriority="high" 
srcset="画像までのパス.png 800w, 
画像までのパス-300x300.png 300w, 
画像までのパス-150x150.png 150w, 
画像までのパス-768x768.png 768w" 
sizes="(max-width: 800px) 100vw, 800px">

この返り値を指定した場合でもURLだけ取り出したい、というときは 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.'">'

ACF | Image

ファイル

ファイルも返り値を「配列・URL・ID」の3種類から選べます。以下は「配列」を選択した際の使用例です。

<?php $file = get_field('file'); ?>
<p><?php echo $file['title']; ?>をダウンロード</p>
<a href="<?php echo $file['url']; ?>"><?php echo $file['filename']; ?></a>

チェックボックス

チェックボックスは通常複数の選択肢の中から1つだけでなくいくつでも選択ができるようにするためのフォーム項目です。そのため、例え一つしか値がなかったとしても get_filed() や the_field() でそのまま出力することはできず、foreach を使って一つずつの値を取り出していく必要があります。

$check = get_field('フィールド名')
foreach($check as $val) {
  if(is_array($val)) {
    echo $val['label'];
  } else {
    echo $val;
  }
}

ラジオボタン

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

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

<?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; ?>

真 ／ 偽

「真/偽」はこの項目のチェックの有無によって何かしらの動作や処理をさせたい時に使用します。

コードで使用する際はこのフィールド項目にチェックがあるかないか、条件分岐で使用されることになるかと思います。

<?php if(get_field('フィールド名')): ?>
  trueの場合に表示させること
<?php else: ?>
  falseの場合に表示させること
<?php endif; ?>

関係

関係フィールドは一度 get_field() でオブジェクトを取得し、foreach で回します。
setup_postdata を使って the_title などの出力関数を使用することができます。

<?php
  $relation = get_field('relation_sample');
  if($relation):
    foreach($relation as $post):
      setup_postdata($post);
?>
  <p><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></p>
<?php endforeach; wp_reset_postdata(); ?>
<?php endif; ?>

グループ

get_field() でグループフィールドを取得して、さらにその中にある特定のフィールドを出力させるようにします。

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

以下のような書き方でも取得できます。

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

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

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

ACF | have_rows()

ACF | have_rows()

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

ACF以外で使うカスタムフィールドのプラグインに Smart Custom Fields があります。
こちらは機能はACFほどありませんが、シンプルなカスタムフィールドを作るならおすすめです。また繰り返しフィールドを無料でも使えるというメリットもあります。

smart custom fieldsでカスタムフィールド作成

ACF関連・参考記事

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

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

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