2026年5月20日

ACFのカスタムフィールドをテンプレートで表示する方法

プラグイン関連

はじめに

ACFで登録したカスタムフィールドは get_field() / the_field() でテンプレートに出力できます。画像・繰り返しフィールド・関係フィールドなどタイプごとに取得方法が異なります。表示方法を網羅的に解説します。

症状・原因

ACFで入力した値がページに表示されない
画像フィールドのURLをどう取得すればよいか分からない
繰り返しフィールドのループ処理が分からない
ショートコードやGutenbergブロックでACFの値を表示したい

解決手順

ステップ1：基本的な値の取得と表示

// テキスト・数値・テキストエリアの表示
$value = get_field('field_name');         // 値を取得（変数に入れる）
the_field('field_name');                  // 直接エコー（エスケープなし）
echo esc_html(get_field('field_name'));   // 安全な出力（推奨）

// 投稿IDを指定して取得（ループ外・ウィジェット内）
$value = get_field('field_name', 42);

// オプションページのフィールドを取得（ACF Pro）
$site_name = get_field('site_name', 'option');

ステップ2：画像フィールドの表示

// 戻り値の形式: 「画像配列」の場合
$image = get_field('main_image');
if ($image) {
    printf(
        '<img src="%s" alt="%s" width="%d" height="%d">',
        esc_url($image['url']),
        esc_attr($image['alt']),
        (int) $image['width'],
        (int) $image['height']
    );
}

// 特定サイズで表示
$image_url = $image['sizes']['medium_large'] ?? $image['url'];

// 戻り値の形式: 「画像ID」の場合
$image_id = get_field('main_image');
echo wp_get_attachment_image($image_id, 'large');

ステップ3：繰り返しフィールドの表示（ACF Pro）

// スタッフ一覧の繰り返しフィールド
if (have_rows('staff_list')) {
    echo '<ul class="staff-list">';
    while (have_rows('staff_list')) {
        the_row();
        $name   = get_sub_field('staff_name');
        $role   = get_sub_field('staff_role');
        $photo  = get_sub_field('staff_photo'); // 画像配列
        printf(
            '<li><img src="%s" alt="%s"><strong>%s</strong>（%s）</li>',
            esc_url($photo['url'] ?? ''),
            esc_attr($photo['alt'] ?? ''),
            esc_html($name),
            esc_html($role)
        );
    }
    echo '</ul>';
}

ステップ4：関係フィールドの表示

// 関係フィールド（戻り値: 投稿オブジェクト配列）
$related_posts = get_field('related_articles');
if ($related_posts) {
    echo '<ul>';
    foreach ($related_posts as $post) {
        setup_postdata($post);
        printf('<li><a href="%s">%s</a></li>',
            esc_url(get_permalink($post)),
            esc_html(get_the_title($post))
        );
    }
    wp_reset_postdata();
    echo '</ul>';
}

ステップ5：ショートコードでACFの値を表示する

// functions.php — ACFフィールドをショートコードで出力
add_shortcode('acf', function(array $atts): string {
    $atts = shortcode_atts([
        'field'   => '',
        'post_id' => get_the_ID(),
        'escape'  => 'true',
    ], $atts);

    if (empty($atts['field'])) {
        return '';
    }

    $value = get_field($atts['field'], (int) $atts['post_id']);
    return $atts['escape'] === 'true' ? esc_html((string) $value) : (string) $value;
});

使用例：

ステップ6：ACF値をREST APIで取得する

// functions.php — ACFフィールドをREST APIに追加
add_action('rest_api_init', function() {
    register_rest_field('post', 'acf_fields', [
        'get_callback' => fn(array $post) => get_fields($post['id']),
        'schema'       => ['type' => 'object'],
    ]);
});

# WP-CLIでREST API経由で確認
wp rest post get 123 --fields=id,title,acf_fields

注意事項

the_field() はエスケープしないためHTML出力には get_field() + esc_html() を使ってください
繰り返しフィールドは必ず wp_reset_postdata() を呼んでポストデータをリセットしてください
関係フィールドで大量の投稿を取得するとパフォーマンスが低下します。表示件数に上限を設けてください

まとめ

ACFの値は get_field('name') で取得し、画像は配列またはIDで受け取ります。繰り返しフィールドは have_rows() + get_sub_field() でループ処理します。ショートコード化するとエディターからも簡単に呼び出せます。

Post Views: 5