ACFのギャラリーフィールドを使うと、投稿ごとに複数の画像を選んで並べ替え、テーマ側で自由なレイアウトのギャラリーとして表示できます。ただしギャラリーフィールドは有料のACF PROの機能です。この記事では、フィールドの作成から、get_field() で画像を取得してエスケープしながら出力するテンプレートのコード、CSSでのグリッド表示、ブロックテーマでの使い方、表示されないときの確認ポイントまでを順に説明します。
無料版ACFとACF PROの違いを確認する
ACF（Advanced Custom Fields）には無料版とACF PROがあり、ギャラリーフィールドはPRO版でのみ使えます。同じくPRO版の機能には、繰り返しフィールド（Repeater）や柔軟コンテンツ（Flexible Content）、オプションページなどがあります（2026年10月現在）。
無料版を使っている場合、フィールドの種類を選ぶ一覧にギャラリーが表示されません。無料版のまま複数画像を扱いたいなら、次のような方法があります。
- 投稿本文で、本体のギャラリーブロックを使う
- 画像フィールドを必要な枚数分（例：最大5枚）用意する
- PRO版の導入を検討する
なお、WordPress.org で配布されている Secure Custom Fields（ACFから派生したプラグイン）は、提供している機能の範囲がACFと異なる場合があります。どちらを使っているかを「プラグイン」画面で確認し、そのプラグインの説明に沿って読み替えてください。
作業前の準備
- 子テーマで作業する：テンプレートやCSSの変更は子テーマに置き、親テーマの更新で消えないようにします。
- バックアップとステージング：テンプレートの記述ミスで記事ページが表示されなくなることがあるため、変更前にバックアップを取り、ステージング環境で確認してから本番に反映します。
- ACFが無効でも壊れないようにする：ACFを停止した状態で
get_field()を呼ぶと、関数が存在しないため致命的なエラーになります。後述のコードではfunction_exists()で確認しています。
ギャラリーフィールドを作成する
管理画面のACFメニューからフィールドグループを新規作成し、ギャラリーフィールドを追加します。設定項目の名前はバージョンによって表記が少し異なることがありますが、主に次の項目を決めます。
- フィールド名：テンプレートから呼び出すときの名前です。この記事では
gallery_imagesとします。ラベル（画面上の表示名）とは別物なので注意してください。 - 返り値の形式：画像配列・画像URL・画像IDから選べます。この記事では 画像ID をおすすめします。IDがあれば、WordPress本体の関数で
srcsetやalt、遅延読み込みを含む適切なimgタグを出力できるからです。 - 選択数の最小・最大：大量の画像が登録されるとページが重くなるため、用途に合わせて上限を決めておきます。
- ライブラリの範囲：メディアライブラリ全体から選べるか、その投稿にアップロードした画像に限るかを選べます。
- 表示条件（ロケーション）：「投稿タイプが投稿と等しい」など、どの編集画面にフィールドを出すかを指定します。
保存したら、対象の投稿の編集画面にギャラリーの入力欄が表示されるので、画像を追加して並べ替え、投稿を更新します。
テンプレートで画像を表示する
返り値を画像IDにした場合のコードです。子テーマの single.php や、テンプレートパーツの中など、表示したい場所に書きます。
<?php
if ( function_exists( 'get_field' ) ) :
$image_ids = get_field( 'gallery_images' );
if ( $image_ids ) : ?>
<div class="acf-gallery">
<?php foreach ( $image_ids as $image_id ) :
$image_html = wp_get_attachment_image( $image_id, 'medium_large' );
if ( ! $image_html ) {
continue; // メディアから削除された画像などは飛ばす
}
$full_url = wp_get_attachment_image_url( $image_id, 'full' );
$caption = wp_get_attachment_caption( $image_id );
?>
<figure class="acf-gallery__item">
<a href="<?php echo esc_url( $full_url ); ?>">
<?php echo $image_html; // wp_get_attachment_image() は属性をエスケープ済み ?>
</a>
<?php if ( $caption ) : ?>
<figcaption><?php echo esc_html( $caption ); ?></figcaption>
<?php endif; ?>
</figure>
<?php endforeach; ?>
</div>
<?php endif;
endif;get_field() はループの中では現在の投稿の値を返します。ループの外や別の投稿の値を取得したい場合は、get_field( 'gallery_images', $post_id ) のように投稿IDを2番目の引数に渡します。
wp_get_attachment_image() は、画像に設定した代替テキストや、登録済みの画像サイズから作る srcset・sizes 属性、遅延読み込みの属性を含むタグを返します。自分で img タグを組み立てるより、レスポンシブ対応や表示速度の面で有利です。キャプションや代替テキストは編集者が入力する値なので、自分で出力する部分は esc_html() や esc_url() でエスケープします。
返り値を「画像配列」にした場合
既存のフィールドが画像配列になっていて変えにくい場合は、配列のキーから値を取り出します。
<?php
$images = function_exists( 'get_field' ) ? get_field( 'gallery_images' ) : array();
if ( $images ) : ?>
<div class="acf-gallery">
<?php foreach ( $images as $image ) : ?>
<figure class="acf-gallery__item">
<a href="<?php echo esc_url( $image['url'] ); ?>">
<img src="<?php echo esc_url( $image['sizes']['medium_large'] ); ?>"
alt="<?php echo esc_attr( $image['alt'] ); ?>"
width="<?php echo (int) $image['sizes']['medium_large-width']; ?>"
height="<?php echo (int) $image['sizes']['medium_large-height']; ?>"
loading="lazy">
</a>
</figure>
<?php endforeach; ?>
</div>
<?php endif; ?>この書き方では srcset が付かないため、可能なら返り値を画像IDに切り替えて前のコードを使うほうが扱いやすくなります。返り値の形式を後から変えた場合は、テンプレートのコードも合わせて変える必要があります。形式とコードが食い違うと、画像が表示されない原因になります。
CSSでグリッド状に並べる
子テーマの style.css に次のようなスタイルを追加すると、画面幅に応じて列数が変わるギャラリーになります。
.acf-gallery {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: 12px;
}
.acf-gallery__item {
margin: 0;
}
.acf-gallery__item img {
display: block;
width: 100%;
height: auto;
aspect-ratio: 4 / 3;
object-fit: cover;
}
.acf-gallery__item figcaption {
font-size: 0.85em;
margin-top: 4px;
}aspect-ratio と object-fit: cover で縦横比をそろえると、縦長・横長の画像が混ざっても整った見た目になります。画像の一部が切り取られて困る場合は object-fit: contain に変えてください。
クリックで拡大表示（ライトボックス）したい場合は、ライトボックス用のJavaScriptライブラリを wp_enqueue_script() で読み込み、a 要素を対象に初期化します。外部のライブラリを使う場合は、更新が続いているものを選び、配布元の導入手順に従ってください。
ブロックテーマで使う
ブロックテーマ（フルサイト編集）では、PHPのテンプレートファイルを直接編集しない構成が一般的です。その場合は、表示用のコードをショートコードにして、サイトエディターのテンプレートに「ショートコード」ブロックで配置する方法が手軽です。
<?php
// [acf_gallery] で現在の投稿のギャラリーを表示する（子テーマの functions.php などに置く）
add_shortcode( 'acf_gallery', function () {
if ( ! function_exists( 'get_field' ) ) {
return '';
}
$image_ids = get_field( 'gallery_images', get_the_ID() );
if ( ! $image_ids ) {
return '';
}
$html = '<div class="acf-gallery">';
foreach ( $image_ids as $image_id ) {
$image_html = wp_get_attachment_image( $image_id, 'medium_large' );
if ( ! $image_html ) {
continue;
}
$html .= '<figure class="acf-gallery__item"><a href="' . esc_url( wp_get_attachment_image_url( $image_id, 'full' ) ) . '">' . $image_html . '</a></figure>';
}
return $html . '</div>';
} );より本格的に組み込みたい場合は、ACF PROの「ACFブロック」機能で独自のブロックを作る方法もあります。ブロックの登録方法はACFのバージョンで変わってきた経緯があるため、ACFの公式ドキュメントで現在の手順を確認してください。
画像サイズと表示速度
ギャラリーは画像が多くなりがちなので、表示に使うサイズを用途に合わせることが大切です。サムネイル一覧なら medium や medium_large、独自の比率が必要なら add_image_size() で専用のサイズを登録します。サイズを追加した場合、既にアップロード済みの画像には新しいサイズが作られていないため、WP-CLIの wp media regenerate や再生成用のプラグインでサムネイルを作り直します。再生成はサーバーに負荷がかかるため、アクセスの少ない時間帯に、バックアップを取ってから行ってください。
表示されないときの確認ポイント
- 何も表示されない：フィールド名（ラベルではなく名前）が一致しているか、その投稿で画像を保存したか、ループの外で投稿IDを渡し忘れていないかを確認します。
var_dump( get_field( 'gallery_images' ) );を一時的に入れて中身を確かめる方法も有効です。確認後は削除します。 - 画像の代わりに数字や「Array」と出る：返り値の形式とコードが合っていません。フィールドの設定を見直します。
- 一部の画像だけ表示されない：メディアライブラリから画像が削除されている可能性があります。この記事のコードでは、該当する画像を飛ばすようにしています。
- サイト全体が真っ白になる：ACFが無効になっているのに
function_exists()の確認なしでget_field()を呼んでいる可能性があります。FTPなどでテンプレートを元に戻すか、ACFを有効にします。
まとめ
- ギャラリーフィールドはACF PROの機能。無料版では本体のギャラリーブロックや複数の画像フィールドで代用する。
- 返り値は画像IDにし、
wp_get_attachment_image()で出力するとsrcsetや代替テキストが自動で付く。 - 自分で出力する値は
esc_url()・esc_html()・esc_attr()でエスケープし、function_exists()でACF停止時のエラーを防ぐ。 - 見た目はCSSグリッドで整え、ブロックテーマではショートコードやACFブロックで配置する。
- 表示サイズを用途に合わせ、必要なら専用サイズを登録してサムネイルを再生成する。