ACFのリピーターフィールドで「繰り返し要素」を効率的に管理する｜現場で使える実践テクニック

こんにちは！

今日は「ACFのリピーターフィールドで繰り返し要素を効率的に管理する方法」について解説します。

リピーターフィールドが活躍する現場あるあると僕の失敗談

まず、僕がリピーターフィールドでやらかした失敗から話させてもらいます。
以前、クライアントから「製品の仕様書を管理したいんや」という要件をもらったんですよ。
最初は「あ、これはカスタム投稿タイプで十分やろ」くらいに思ってました。
ところがですね、クライアントが実際に使ってみると「いや待ってよ、1つの製品ページの中に複数の仕様項目を自由に追加・削除したいんやけど」という話になったんです。

そこでようやく気づきました。
「あ、これ完全にリピーターフィールドの出番やん」ってね。
僕はその時点で急いで設定し直したんですが、ほんま焦りました。

現場でよく見るのは、こういったシーン使いどころです。

• スタッフ紹介ページで「スタッフA、スタッフB、スタッフC…」と何人でも追加したい
• サービス一覧で「項目1、項目2、項目3…」と柔軟に増減させたい
• 実績・ギャラリーで複数の画像と説明文をセットで管理したい
• 料金表で複数の料金プランを1ページ内で管理したい

こういった「同じ構造のデータを何個でも繰り返したい」という場面が、リピーターフィールドの得意な領域なんですよ。
固定ページ内に複数行のデータを自由に追加・削除できるので、クライアント側もめっちゃ運用しやすくなります。

リピーターフィールドの基本設定とクライアント運用を意識した構築方法

では、実際にどうやって設定するか説明しますね。
ACFを使う前提で進めます。

ACFプラグインをインストール・有効化した後、カスタムフィールド管理画面から新しいフィールドグループを作成します。
ここで大事なのは、「どの投稿タイプに紐付けるか」を明確にすることです。
僕の経験上、この設定を後から変更するのはめっちゃ面倒なので、事前にクライアントとしっかり打ち合わせしておくといいですよ。

次に、フィールドグループ内に「リピーター」タイプのフィールドを追加します。
例えば「staff_profiles」という名前で作ったら、その中に子フィールドとして以下のように構成すると運用が楽になります。

• staff_name（テキスト）→ スタッフ名
• staff_position（テキスト）→ 役職
• staff_image（画像）→ プロフィール画像
• staff_bio（テキストエリア）→ 自己紹介文

ここで気をつけたいのが、クライアント側の使いやすさです。
各フィールドに「ラベル」をわかりやすく付けるのはもちろん、「説明文」も書くといいですよ。
例えば staff_image の説明に「推奨サイズ: 400x400px、形式: JPGまたはPNG」と書いておくと、クライアントが誤った画像を上げることが減ります。

実装の際は、リピーターフィールドの「最大行数」や「最小行数」を設定するのも効果的です。
例えば、スタッフ紹介を最低2名、最大10名に制限したい場合は、そこを指定しておくんです。
そうするとクライアントが「あれ、追加ボタンが押せない？」ってなったときに「あ、上限に達したんだな」と気づきやすくなります。

実装時に気をつけたいテンプレート側の書き方と注意点

では次に、テンプレートファイル（PHPコード）でリピーターデータを取得して表示する方法を説明します。
これが意外とハマりやすいポイントなので、慎重に行きましょう。

基本的な書き方は have_rows() 関数を使った ループ構文になります。
例えば、上記のスタッフ情報を表示するなら、こんな感じですよ。

<?php
if ( have_rows( 'staff_profiles' ) ) {
  echo '<div class="staff-list">';
  while ( have_rows( 'staff_profiles' ) ) {
    the_row();
    $name = get_sub_field( 'staff_name' );
    $position = get_sub_field( 'staff_position' );
    $image = get_sub_field( 'staff_image' );
    $bio = get_sub_field( 'staff_bio' );
    echo '<div class="staff-item">';
    echo '<img src="' . esc_url( $image['url'] ) . '" alt="' . esc_attr( $name ) . '">';
    echo '<h3>' . esc_html( $name ) . '</h3>';
    echo '<p class="position">' . esc_html( $position ) . '</p>';
    echo '<p class="bio">' . wp_kses_post( $bio ) . '</p>';
    echo '</div>';
  }
  echo '</div>';
}
?>

注目してほしいのが、the_row() という関数です。
これを忘れると後続の get_sub_field() が正常に動作しないんですよ。
僕も最初、この関数をつけ忘れて「あれ、データが取得できん…」ってなったことがあります。
ほんまよくある初心者の落とし穴です。

もう一つ気をつけたい点が、セキュリティです。
上記のコードで esc_url() や esc_html() を使ってるのは、出力値をエスケープするためです。
クライアントが誤ってスクリプトを含めてしまう可能性を考慮して、必ず適切なサニタイズを行うといいですよ。
特に、テキストエリアで改行や HTML タグを許可する場合は wp_kses_post() を使うと安全です。