ACF総合ガイド：フィールドタイプ・オプションページ・ACFブロック・REST API

ACF（Advanced Custom Fields）は、投稿への入力欄の追加にとどまらず、サイト共通設定ページ、独自ブロック、フィールド定義のファイル管理、REST API 経由の値の公開まで扱える、WordPress のデータ設計ツールです。この記事では、フィールドタイプの全体像、無料版と PRO の違い、オプションページ、ACF ブロック、ローカル JSON、REST API を順に解説し、2024年以降の ACF と Secure Custom Fields（SCF）の関係も整理します。読み終えると、案件ごとに「どの機能を使い、どこにデータを置くか」を判断できるようになります。

フィールドグループの作り方や get_field() での表示といった最初の一歩は「ACFの基本的な使い方」で解説しているので、初めての方はそちらから読むと理解しやすいはずです。

ACF と Secure Custom Fields の関係

ACF は現在 WP Engine が開発しています。2024年9月に WordPress.org と WP Engine の対立が表面化し、2024年10月12日、WordPress.org は ACF をフォークした「Secure Custom Fields（SCF）」を公開して、プラグインディレクトリの ACF の掲載枠を SCF に置き換えました。この間、WP Engine は公式サイトから ACF を配布し、独自の更新経路を用意しています。

その後 2024年12月、WP Engine の申し立てによる裁判所の仮差止命令を受けて、ディレクトリ上の ACF の掲載と管理権は WP Engine に戻りました。SCF は別のプラグイン（スラッグ secure-custom-fields）として掲載が続いており、PRO 相当の機能も取り込まれています。両者は同じ関数名を使うため、同時に有効化しないでください。訴訟は本案判決に向けて継続していると報じられており、各プラグインの方針は今後も変わり得ます（2026年10月現在）。

運用面で大事なのは、自分のサイトに入っているのがどちらか、どこから更新を受け取っているかを把握することです。プラグイン一覧で名前と作者を確認し、乗り換える場合はステージング環境で表示とデータを確認してから本番に反映します。

無料版と ACF PRO の違い

比較が必要な場面なので表にまとめます。

価格やライセンス体系は改定されることがあるため、購入前に公式サイトで確認してください。判断の目安として、「行数が変わるデータ（料金表・FAQ など）」「サイト全体で使う設定値」「独自ブロック」のいずれかが必要なら PRO が候補になります。

フィールドタイプの全体像

フィールドタイプは管理画面で分類ごとに選べます。主なものは次のとおりです。

• 基本: テキスト、テキストエリア、数値、範囲、メール、URL、パスワード
• コンテンツ: 画像、ファイル、WYSIWYG エディター、oEmbed、ギャラリー（PRO）
• 選択肢: セレクト、チェックボックス、ラジオボタン、ボタングループ、真/偽
• 関連: リンク、投稿オブジェクト、ページリンク、関連（Relationship）、タクソノミー、ユーザー
• 高度: Google マップ、日付選択、日付時間選択、時間選択、カラーピッカー
• レイアウト: メッセージ、アコーディオン、タブ、グループ、リピーター（PRO）、フレキシブルコンテンツ（PRO）、クローン（PRO）

選び方のポイントは「後で検索・並び替えに使うかどうか」です。日付や数値を投稿の並び替えに使うなら、テキストではなく日付選択や数値フィールドを選び、保存形式を揃えておくと meta_query での比較が素直に書けます。関連フィールドや投稿オブジェクトは返り値を「投稿 ID」にしておくと、必要な情報だけを取得でき、ループ内での setup_postdata() の扱いにも迷いません。

オプションページ（PRO）

会社の電話番号やフッターの告知文のように、投稿ではなくサイト全体に属する値は、オプションページに置きます。PRO ではオプションページを管理画面から作成できるほか、コードでも登録できます。

add_action( 'acf/init', function () {
	if ( ! function_exists( 'acf_add_options_page' ) ) {
		return;
	}
	acf_add_options_page( array(
		'page_title' => 'サイト共通設定',
		'menu_title' => 'サイト共通設定',
		'menu_slug'  => 'site-settings',
		'capability' => 'manage_options',
		'redirect'   => false,
	) );
} );

フィールドグループのロケーションルールで「オプションページ」がこのページと等しい、と指定すると入力欄が表示されます。値の取得は第2引数に 'option' を渡します。

$tel = get_field( 'company_tel', 'option' );
if ( $tel ) {
	echo '<p class="footer-tel">' . esc_html( $tel ) . '</p>';
}

値は wp_options テーブルに options_ で始まるキーで保存されます。capability は誰が編集できるかを決めるので、編集者にも触らせたいのか、管理者だけにするのかを決めてから設定します。

ACF ブロック（PRO）

ACF ブロックを使うと、React を書かずに PHP テンプレートだけで独自ブロックを作れます。ブロックの定義は WordPress 標準の block.json に acf キーを加える形です。

{
	"name": "acf/testimonial",
	"title": "お客様の声",
	"category": "formatting",
	"icon": "format-quote",
	"apiVersion": 2,
	"acf": {
		"mode": "preview",
		"renderTemplate": "render.php"
	},
	"supports": {
		"align": false
	}
}

// functions.php: テーマの blocks/testimonial/ に block.json と render.php を置く
add_action( 'init', function () {
	register_block_type( get_theme_file_path( 'blocks/testimonial' ) );
} );

<?php
// blocks/testimonial/render.php
$quote  = get_field( 'quote' );
$author = get_field( 'author_name' );

$class = 'testimonial';
if ( ! empty( $block['className'] ) ) {
	$class .= ' ' . $block['className'];
}

if ( ! $quote ) {
	if ( $is_preview ) {
		echo '<p>' . esc_html__( 'お客様の声を入力してください。', 'your-textdomain' ) . '</p>';
	}
	return;
}
?>
<figure class="<?php echo esc_attr( $class ); ?>">
	<blockquote><?php echo esc_html( $quote ); ?></blockquote>
	<?php if ( $author ) : ?>
		<figcaption><?php echo esc_html( $author ); ?></figcaption>
	<?php endif; ?>
</figure>

フィールドグループのロケーションルールを「ブロック」が「お客様の声」と等しい、にすると、ブロックの設定パネルに入力欄が出ます。テンプレート内では $block（ブロック設定）や $is_preview（エディター内表示かどうか）が使えます。

注意点として、ACF ブロックの値は投稿メタではなく、本文（post_content）内のブロックの属性として保存されます。そのため meta_query で検索したり、一覧ページで並び替えたりする用途には向きません。検索・集計に使う値は通常のフィールドグループで投稿メタに保存する、と役割を分けると設計が崩れにくくなります。

ローカル JSON でフィールド定義を管理する

フィールドグループの定義は通常データベースに保存されますが、テーマ直下に acf-json フォルダーを作っておくと、保存のたびに定義が JSON ファイルとして書き出されます。これを Git で管理すれば、開発環境で作ったフィールドを本番へ反映する作業が「ファイルを配置して同期する」だけになります。ファイルの方が新しい場合、フィールドグループ一覧に同期を促す表示が出るので、内容を確認して同期します。

テーマを切り替える可能性がある場合や、フィールド定義を機能プラグイン側で持ちたい場合は、保存先と読み込み先をフィルターで変更します。

// 自作の機能プラグイン内で acf-json フォルダーを使う例
add_filter( 'acf/settings/save_json', function ( $path ) {
	return plugin_dir_path( __FILE__ ) . 'acf-json';
} );

add_filter( 'acf/settings/load_json', function ( $paths ) {
	$paths[] = plugin_dir_path( __FILE__ ) . 'acf-json';
	return $paths;
} );

本番環境で管理画面からフィールドを直接編集すると、JSON とデータベースの内容がずれます。「定義の変更は開発環境で行い、JSON をデプロイして同期する」という運用ルールをチーム内で決めておくと事故を防げます。なお、ローカル JSON は投稿タイプ・タクソノミー・オプションページの定義も対象になります。

REST API で値を公開する

フィールドグループの設定で REST API での表示を有効にすると、/wp-json/wp/v2/posts/123 のような標準エンドポイントの応答に acf キーが加わり、フィールドの値が含まれます。カスタム投稿タイプの場合は、投稿タイプ自体が show_in_rest を有効にしている必要があります。

公開投稿の REST 応答は誰でも取得できる点に注意してください。社内メモや個人情報を入れるフィールドを含むグループでは、REST API での表示を有効にしないようにします。認証済みでユーザーに編集権限があれば、同じエンドポイントへの更新リクエストで acf の値を書き込むこともできます。オプションページの値は標準の投稿エンドポイントには含まれないため、外部から使う場合は register_rest_route() で独自エンドポイントを用意し、権限チェックを入れて返します。

運用で気を付けること

• 出力時のエスケープ: ACF 6.2.7（2024年）以降 the_field() は安全でない HTML を除去しますが、属性や URL の文脈には対応しません。get_field() で受け取り、esc_html()・esc_attr()・esc_url()・wp_kses_post() を使い分けます。
• フィールド名の変更: 運用開始後に名前を変えると既存の値を取得できなくなります。
• 一覧ページでの取得回数: 一覧で投稿ごとに多数の get_field() を呼ぶと、メタデータの読み込みが増えます。必要なフィールドだけを取得し、表示しない値はループ内で呼ばないようにします。
• 更新前のバックアップ: メジャーアップデートや ACF と SCF の乗り換えの前には、データベースとファイルのバックアップを取り、ステージングで確認します。

まとめ

• ACF と SCF は 2024年10月以降、別々のプラグインとして存在します。自サイトがどちらを使い、どこから更新を受けているかを把握しておきます。
• リピーター、オプションページ、ACF ブロックが必要なら PRO（または同等機能を持つ代替）を検討します。
• サイト共通の値はオプションページ、ブロック単位の表示は ACF ブロック、検索や並び替えに使う値は投稿メタ、と保存場所を使い分けます。
• フィールド定義はローカル JSON で Git 管理し、本番では同期だけを行う運用にすると環境差分が出にくくなります。
• REST API での表示は公開範囲を意識してグループ単位で有効化します。

• ACFの基本的な使い方：フィールド作成からテンプレート表示まで
• ACFのフィールドグループをJSONで管理する方法