ACF（Advanced Custom Fields）は、投稿や固定ページに独自の入力欄を追加し、その値をテーマのテンプレートで表示するためのプラグインです。基本の流れは「フィールドグループを作る → 表示先（ロケーション）を決める → 投稿画面で入力する → テンプレートで get_field() を使って出力する」の4段階です。この記事では、初めて ACF を使う方向けに、テキスト・画像・リピーターの3種類を例に、値を安全に表示するところまでを解説します。
機能の全体像（オプションページ、ACF ブロック、ローカル JSON、REST API、無料版と PRO の違いなど）は別記事「ACF総合ガイド」にまとめています。この記事は「まず1つのフィールドを作って表示できる」ことに絞っています。
始める前に確認しておくこと
ACF は管理画面の「プラグイン」→「新規プラグインを追加」から検索してインストールできます。ただし 2024年10月以降、WordPress.org のプラグインディレクトリには ACF とは別に、ACF から派生した「Secure Custom Fields（SCF）」も存在します。どちらも同じ関数名（get_field() など）で動くため、この記事のコードはどちらでも動作しますが、プラグイン一覧で自分のサイトにどちらが入っているか、作者名とプラグイン名を確認しておくと後の更新管理で迷いません（2026年10月現在）。
テンプレートを編集するので、配布テーマを使っている場合は子テーマを作ってから作業します。親テーマのファイルを直接書き換えると、テーマ更新時に変更が消えてしまいます。
フィールドグループを作成する
ACF では、入力欄（フィールド）を「フィールドグループ」という単位でまとめて管理します。たとえば「会社情報」というグループの中に「会社名」「設立年」「ロゴ画像」のフィールドを入れる、という形です。
フィールドを追加する
管理画面の「ACF」メニューから「フィールドグループ」→「新規追加」を開き、グループ名を入力します。続いてフィールドを追加し、次の3項目を設定します。
- フィールドタイプ: テキスト、画像、セレクトなど入力欄の種類
- フィールドラベル: 投稿画面に表示される見出し（日本語で構いません）
- フィールド名: テンプレートから値を呼び出すときのキー。半角英小文字とアンダースコアで付けます
つまずきやすいのはフィールド名です。ラベルを入力すると自動で名前が生成されますが、日本語ラベルからは意図しない名前になることがあるため、company_name のように自分で付け直します。また、一度投稿で値を保存した後にフィールド名を変えると、既存の値はデータベース上で古い名前のまま残り、新しい名前では取得できなくなります。名前は運用前に決めておくのが安全です。
ロケーションルールで表示先を決める
同じ画面の「設定」にあるロケーションルールで、このフィールドグループをどの編集画面に出すかを決めます。「投稿タイプ」が「投稿」と等しい、のように条件を組み立てます。特定の固定ページだけに出したい場合は「ページ」を条件にし、複数条件は AND / OR で組み合わせられます。
保存したら、対象の投稿を開いて入力欄が表示されているかを確認します。表示されない場合は、ロケーションルールの条件と、ブロックエディターの設定（右上のメニューから開く環境設定のパネル項目）で該当のメタボックスが非表示になっていないかを見直します。
テンプレートで値を表示する
入力した値はテーマのテンプレート（投稿なら single.php やテンプレートパーツ）に PHP で書き足して表示します。
get_field() と the_field() の違い
get_field( 'フィールド名' ) は値を返す関数、the_field( 'フィールド名' ) はその値をそのまま出力する関数です。ループ内では現在の投稿の値が対象になり、別の投稿の値が欲しいときは第2引数に投稿 ID を渡します（例: get_field( 'company_name', 123 )）。
実務では get_field() で受け取り、出力する場所に合ったエスケープ関数を通す書き方をおすすめします。
<?php
$company = get_field( 'company_name' );
if ( $company ) :
?>
<p class="company-name"><?php echo esc_html( $company ); ?></p>
<?php
endif;
$site_url = get_field( 'company_url' );
if ( $site_url ) {
printf(
'<a href="%s">%s</a>',
esc_url( $site_url ),
esc_html__( '公式サイトを見る', 'your-textdomain' )
);
}なぜエスケープが必要か
カスタムフィールドの値は投稿者が自由に入力できるため、HTML やスクリプトが混ざる可能性があります。ACF 6.2.7（2024年）以降、the_field() は安全でない HTML を取り除いてから出力するようになりましたが、これは「本文として HTML を出す」前提の処理です。href 属性の中に URL を入れる、alt 属性に文字列を入れるといった場面では、それぞれ esc_url()、esc_attr() が必要になります。出力先の文脈に合わせて関数を選ぶには、get_field() で受け取って自分でエスケープする形が分かりやすいのです。
リッチエディター（WYSIWYG）フィールドのように HTML を含む値を出すときは、echo wp_kses_post( get_field( 'company_profile' ) ); のように許可されたタグだけを残します。
値が空のときの扱い
未入力のフィールドを出力すると、空の <p> タグや見出しだけが残ってレイアウトが崩れます。上の例のように if ( $company ) で値の有無を確認してから HTML を組み立てると、未入力の投稿でも表示が乱れません。
画像フィールドを表示する
画像フィールドには「返り値のフォーマット」という設定があり、画像配列・画像 URL・画像 ID から選べます。初心者の方には 画像 ID をおすすめします。ID を wp_get_attachment_image() に渡すと、メディアライブラリの代替テキスト（alt）、srcset によるレスポンシブ画像、遅延読み込み属性を WordPress がまとめて出力してくれるからです。
<?php
$logo_id = get_field( 'company_logo' ); // 返り値のフォーマット: 画像ID
if ( $logo_id ) {
echo wp_get_attachment_image( $logo_id, 'medium', false, array( 'class' => 'company-logo' ) );
}返り値を「画像 URL」にすると <img> タグを自分で書くことになり、alt や画像サイズの指定を忘れがちです。「画像配列」の場合は $image['url'] や $image['alt']、$image['sizes']['medium'] のようにキーで取り出せます。どの形式で返ってくるか分からなくなったら、開発環境で var_dump( get_field( 'company_logo' ) ); を一時的に書いて中身を確認すると早く解決します。
リピーターフィールドの基本
スタッフ一覧や料金表のように「同じ項目の組を何行でも追加したい」場合はリピーターフィールドを使います。リピーターは ACF PRO の機能です（2026年10月現在）。リピーターの中に「サブフィールド」として「名前」「役職」などを作り、テンプレートでは have_rows() と the_row() でループします。
<?php if ( have_rows( 'staff_list' ) ) : ?>
<ul class="staff-list">
<?php
while ( have_rows( 'staff_list' ) ) :
the_row();
?>
<li>
<span class="staff-name"><?php echo esc_html( get_sub_field( 'staff_name' ) ); ?></span>
<span class="staff-role"><?php echo esc_html( get_sub_field( 'staff_role' ) ); ?></span>
</li>
<?php endwhile; ?>
</ul>
<?php endif; ?>ループの中では get_field() ではなく get_sub_field() を使う点に注意してください。get_field( 'staff_list' ) で受け取ると、行ごとの連想配列の配列が返るので、foreach で回す書き方もできます。
うまく表示されないときの確認ポイント
値が表示されないときは、次の順で切り分けると原因を絞り込めます。
- 値が保存されているか: 投稿画面を開き直して入力値が残っているかを見ます。残っていなければ保存側の問題です。
- フィールド名が一致しているか: テンプレートの
get_field( 'company_name' )と、フィールドグループで設定したフィールド名を一文字ずつ照合します。ラベルではなく名前で呼び出す点もよくある見落としです。 - 対象の投稿 ID が正しいか: ループの外（ヘッダーやサイドバー）では現在の投稿が特定できないことがあります。
get_field( 'company_name', get_queried_object_id() )のように ID を明示します。 - 編集しているテンプレートが使われているか: 子テーマのファイル名や、ブロックテーマのテンプレートで PHP が使えない点を確認します。ブロックテーマでは、PHP テンプレートの代わりに ACF ブロックなどで表示する方法を検討します。
なお、ACF の値は wp_postmeta テーブルにフィールド名をキーとして保存され、別に先頭へアンダースコアを付けたキーでフィールドの識別子も保存されます。get_post_meta() でも値は読めますが、画像フィールドなら ID の数値がそのまま返るなど、ACF の整形処理を通らない点が異なります。
まとめ
- ACF は「フィールドグループ作成 → ロケーション設定 → 入力 → テンプレートで出力」の流れで使います。
- フィールド名はコードから呼び出すキーなので、半角英字で自分で付け、運用開始後は変えないようにします。
- 出力は
get_field()で受け取り、esc_html()・esc_url()・wp_kses_post()など文脈に合ったエスケープを通します。 - 画像フィールドは返り値を画像 ID にして
wp_get_attachment_image()で出すと、alt やレスポンシブ画像を自動で扱えます。 - リピーターは PRO の機能で、
have_rows()・the_row()・get_sub_field()の組み合わせでループします。