WP_Query 用語The Loop

The Loop は、WordPress のテンプレートで投稿を表示する時に必ず理解しておきたい基本です。投稿一覧でも、投稿詳細でも、検索結果でも、取得された投稿を順番に処理して画面へ出す流れとして使われます。

WP_Query が「どの投稿を取得するか」を担当するのに対して、The Loop は「取得した投稿をどう1件ずつ表示するか」を担当します。この2つを分けて考えると、WordPress の一覧表示がかなり読みやすくなります。

The Loop は何をするものか

The Loop は、取得済みの投稿を1件ずつ取り出して表示する処理です。投稿があるかを確認し、投稿データを現在の投稿としてセットし、その中でタイトル、本文、リンク、抜粋、アイキャッチなどを表示します。

WordPress のテンプレートタグの多くは、現在の投稿データを前提に動きます。the_title() や the_content() などは、ループの中で使うことで、今処理している投稿の情報を表示できます。

ここで大事なのは、The Loop は投稿を取得する条件そのものではないことです。取得条件は WP_Query やメインクエリが担当し、The Loop は取得済みの投稿を表示します。

つまり、投稿が表示されない時は、ループの書き方だけでなく、そもそも投稿が取得されているかも確認する必要があります。

if ( have_posts() ) {   while ( have_posts() ) {      the_post();       the_title( '<h2>', '</h2>' );   }}

have_posts() と the_post() の違い

have_posts() と the_post() は名前が似ていますが、役割は違います。have_posts() は投稿が残っているかを確認するためのものです。the_post() は次の投稿を現在の投稿としてセットするためのものです。

この違いを理解すると、ループの構造が読みやすくなります。while ( have_posts() ) で繰り返し条件を確認し、その中で the_post() を呼び出して投稿データを準備します。

the_post() を呼ばないままテンプレートタグを使うと、今どの投稿を表示しているのかが正しく準備されません。ループの中で表示する前に the_post() が必要です。

一方で、the_post() は投稿を表示するたびに次へ進める処理でもあります。むやみに複数回呼ぶと、意図しない投稿へ進んでしまうため注意します。

Builder での扱い

WP Query Builder では、The Loop は生成コードの表示部分として扱う想定です。ユーザーが選んだ取得条件を $args にまとめ、取得結果をループで表示するコードとして出力します。

初心者向けには、Builder の画面で The Loop を細かく入力させるより、「取得条件」と「表示する項目」を分けると分かりやすくなります。取得条件は WP_Query、表示項目はループ内のテンプレートタグへ変換します。

独自クエリを生成する場合は、wp_reset_postdata() をセットで出すことも重要です。後続のテンプレートへの影響を避けるため、生成コードに含める前提で扱います。

使いどころ・避けどころと実践確認

WP_Queryの結果を順に現在投稿へ設定し、テンプレートタグで表示する標準の反復処理を説明する時に使います。

have_posts() だけで投稿が進むと考えたり、独自ループ後の状態を放置したりしません。

the_post() がグローバル $post を更新するため、入れ子の独自ループではどの投稿が現在値かを見失いやすくなります。

have_posts() は次があるかを確かめ、the_post() が現在の投稿を進める、という役割の違いが要点です。

ループ回数、各回のID、終了後のIDを出力し、独自ループならリセット後に元のIDへ戻るか確認します。

実践記事で確認wp_reset_postdata()が必要な理由

ループが $post を動かす仕組みと、wp_reset_postdata() を置く理由を実例で確認できます。

記事を読む →

WordPressの仕様で確認するポイント

公式資料では、Theme Handbook の The Loop で、WordPress テンプレートにおけるループの基本を確認できます。WP_Query のリファレンスも、独自クエリの構造を確認する時に役立ちます。

独自クエリ後の投稿データを戻す処理は、wp_reset_postdata() の公式リファレンスで確認できます。The Loop と WP_Query をセットで使う時は、この関数も合わせて覚えると安全です。

The Loop は、取得された投稿を1件ずつ表示するための基本的な流れです。have_posts() で投稿の有無を確認し、the_post() で投稿データを準備し、テンプレートタグで表示します。

迷った時は、タイトルだけを表示する最小構成で確認します。独自 WP_Query を使う場合は、$query->have_posts()、$query->the_post()、wp_reset_postdata() の3点を確認します。