WP_Query 実装用語wp_reset_postdata()

WordPress の The Loop では、the_post() によって現在の投稿データが切り替わります。独自 WP_Query で別の投稿一覧を表示すると、そのループ中は現在の投稿が custom query の投稿になります。

そのまま戻さないと、後続のテンプレートタグが意図しない投稿を参照することがあります。wp_reset_postdata() は、その状態をメインクエリの投稿データへ戻すために使います。

wp_reset_postdata() は何をする関数か

wp_reset_postdata() は、独自 WP_Query のループで変更されたグローバルな投稿データを、メインクエリの現在投稿へ戻す関数です。custom query のループ後に使います。

WP_Query のループでは、$query->the_post() を呼ぶたびに現在の投稿データが切り替わります。これにより、the_title() や the_permalink() などのテンプレートタグが、その custom query の投稿を表示できるようになります。

ここで大事なのは、wp_reset_postdata() は投稿の取得条件を戻す関数ではなく、投稿データの参照状態を戻す関数だという点です。独自クエリの結果そのものを消すためのものではありません。

つまり、custom query のループを終えた後に「この後のテンプレートタグが元の投稿を見られるようにする」ための後片付けとして使います。

$args = [   'post_type'      => 'post',   'post_status'    => 'publish',   'posts_per_page' => 3,]; $query = new WP_Query( $args ); if ( $query->have_posts() ) {   while ( $query->have_posts() ) {      $query->the_post();       the_title( '<h2>', '</h2>' );   }} wp_reset_postdata();

wp_reset_query() との違い

wp_reset_postdata() と混同しやすい関数に wp_reset_query() があります。通常の独自 WP_Query を使った後に必要になるのは、基本的に wp_reset_postdata() です。

wp_reset_query() は、グローバルな $wp_query などを戻す文脈で使われる関数です。古い実装や query_posts() と一緒に語られることがありますが、通常の custom query では wp_reset_postdata() を使うと整理しやすくなります。

初心者向けには、まず new WP_Query() で独自一覧を作ったら、ループ後に wp_reset_postdata() を入れる、と覚えるのが安全です。

query_posts() のような別の仕組みを使う場合は話が変わりますが、WP Query Lab の通常の実装例では、独自 WP_Query と wp_reset_postdata() の組み合わせを基本にします。

Builder での扱い

WP Query Builder では、独自 WP_Query を生成する場合、wp_reset_postdata() を自動で含める想定が安全です。ユーザーが意識しなくても、custom query の後処理が入るようにします。

特に、関連記事や最新記事のような追加一覧を生成するコードでは、ループ後の wp_reset_postdata() を省略しない方針が向いています。

一方、main query の通常ループだけを表示する場合は、独自 WP_Query ではないため、常に wp_reset_postdata() が必要というわけではありません。custom query か main query かを分けて扱います。

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

the_post() を使った独自の WP_Query ループの後で、グローバル $post を元のページ文脈へ戻す時に使います。

投稿IDだけを配列処理してグローバル $post を変更していない場合や、メインクエリ自体を初期化する目的では使いません。

呼ぶ位置が独自ループの途中や遅すぎる場所だと、後続のタイトル・URL・本文が別投稿を参照します。

独自ループの直後に戻す処理を置くと、その後のタイトルやリンクが別投稿へずれる事故を防げます。

独自ループ前、中、直後、リセット後の get_the_ID() を出し、元のページIDへ戻ることを確認します。

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

必要なケース、不要なケース、書く位置を実際の独自ループで確認できます。

記事を読む →

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

公式資料では、wp_reset_postdata() のリファレンスで、独自 WP_Query 後に投稿データを戻す処理を確認できます。WP_Query のリファレンスでは、独自クエリとループの基本構造を確認できます。

The Loop の資料も合わせて見ると、the_post() によって現在の投稿データが準備される流れを理解しやすくなります。

wp_reset_postdata() は、独自 WP_Query のループ後に投稿データを戻すための関数です。custom query を表示した後、後続のテンプレートタグが元の投稿を参照できるようにします。

迷った時は、new WP_Query() を使っているか、$query->the_post() を使っているか、ループ後に wp_reset_postdata() があるかを確認します。