WP_Queryとは？初心者向けに役割と使い方を解説

WP_Queryが担当すること

WordPressは、トップページ、カテゴリー一覧、検索結果などを開くと、URLや設定に合う投稿を先に取得します。このページ本来の表示に使うものがメインクエリです。通常の一覧テンプレートでは、すでに用意されたメインクエリをループで表示します。

一方、記事下の関連記事やトップページのイベント一覧など、本来の表示とは別の投稿が必要な場合は、自分でnew WP_Query()を使って独自のクエリを作れます。

見た目を整えるのはテンプレートとCSS、投稿を選ぶのはWP_Queryです。取得と表示を分けて考えると、直す場所も判断しやすくなります。

WP_Queryを使う場面

WP_Queryは、WordPressの通常の表示だけでは足りないときに使います。何でもWP_Queryで書き直すものではなく、「今のページとは別条件の記事一覧を作りたい」ときに使う、と考えると判断しやすいです。

たとえば、記事下に同じカテゴリーの関連記事を3件出す、トップページで新着情報とイベント情報を分ける、といった場面です。この場合はposts_per_pageで件数、post_typeで投稿タイプ、カテゴリーやタクソノミーの引数で絞り込みを指定します。

ただし、すでにWordPressが用意しているメインクエリの一覧を変えたい場合は、WP_Queryを新しく作るのではなく、pre_get_postsで対象を限定して調整する方法があります。最初は、サイドバーや記事下などに「追加の一覧」を作る場面から試すと、メインクエリとの役割を分けて理解できます。

WP_Queryの基本構造

ここでは、WP_Queryの全体の流れと、それぞれの処理が担当する役割を確認します。

WP_Queryの基本は、条件を配列で用意し、その条件を new WP_Query() に渡す形です。その後、取得した投稿があるかを have_posts() で確認し、投稿がある間だけ the_post() で1件ずつ取り出します。

$argsで条件を作るだけでは画面には何も出ません。取得結果をループで回し、タイトルやリンクをテンプレートタグで出力して、はじめて一覧になります。

実際の$argsとループを1行ずつ確認する段階では、WP_Queryの基本構文へ進んでください。コードを書いても何も出ない時は、条件を減らす投稿が表示されない時のチェックリストが切り分けの入口になります。

最新記事を3件だけ取得する最小例

次のコードは、通常の投稿を最新順で3件取得し、タイトルを一覧として表示する最小例です。まずはカテゴリーやカスタムフィールドなどの条件を足さず、少ない件数で動きを確認するのがおすすめです。

この例をfunctions.phpから呼ぶ場合は、関数・ショートコード・フックへ組み込み、実行条件と出力位置を決めます。

$args = [   'post_type'      => 'post',   'posts_per_page' => 3,]; $latest_posts = new WP_Query( $args ); if ( $latest_posts->have_posts() ) {   echo '<ul>';    while ( $latest_posts->have_posts() ) {      $latest_posts->the_post();       echo '<li>';      echo '<a href="' . esc_url( get_permalink() ) . '">';      echo esc_html( get_the_title() );      echo '</a>';      echo '</li>';   }    echo '</ul>';} wp_reset_postdata();

このコードの読みどころは、まず $args に条件を集めている点です。post_type は取得対象、posts_per_page は取得件数です。この2つだけでも、WP_Queryの基本的な考え方はつかめます。

もうひとつ大事なのは、最後の wp_reset_postdata() です。この例のように独自のWP_Queryで the_post() を使うと、テンプレートタグが参照する投稿データがそのクエリ側に切り替わります。ループが終わったあとにメインクエリの現在の投稿データへ戻し、後続のタイトルやURLが別投稿を参照するのを防ぎます。

$argsは取得条件をまとめる場所

WP_Queryを使うときによく出てくる $args は、取得条件をまとめた配列です。名前は $args でなくても動きますが、WordPressのサンプルや解説では $args という名前がよく使われます。

最初に覚えるべきなのは、すべての引数を一度に覚えようとしないことです。WP_Queryには多くの条件がありますが、初心者が最初に使うものは限られています。まずは「何を」「何件」「どの順番で」取得するのかに分けて考えると、コードを読みやすくなります。

このように分けると、複雑なWP_Queryも少しずつ読めるようになります。最初から tax_query や meta_query を組み合わせるより、post_type と posts_per_page だけの小さな例で動作確認すると、どの条件で結果が変わったかを追いやすくなります。

初心者がよくつまずくポイント

WP_Queryで最初につまずきやすいのは、コードの書き方そのものよりも、どの部分が何を担当しているかが分からなくなることです。特に、条件、ループ、リセット処理が混ざって見えると、エラーが起きたときにどこを直せばよいか判断しにくくなります。

よくあるつまずきは、次の3つです。1つ目は、posts_per_page などの条件を変えても期待した件数にならないこと。2つ目は、the_post() を使ったあとに wp_reset_postdata() を忘れて、後続のタイトルやリンクが意図しない投稿を参照してしまうこと。3つ目は、メインクエリを変えたい場面と、別の一覧を追加したい場面を混同することです。

いきなり複雑な条件を足すと、どこで間違っているのか分かりにくくなります。最新記事3件のような最小構成で表示できることを確認し、その後でカテゴリー、カスタム投稿、並び順などを1つずつ足すと、原因を切り分けられます。

公式資料で確認したいポイント

WP_Queryは使える引数が多いため、すべてを暗記する必要はありません。むしろ、必要な場面で公式リファレンスを開き、対象の引数だけ確認できるようになることが大切です。

特に初心者のうちは、WP_Query全体、The Loop、wp_reset_postdata() の3つを分けて確認すると理解しやすいです。取得条件で迷ったらWP_Query、表示の流れで迷ったらThe Loop、ループ後の戻し処理で迷ったらwp_reset_postdata()を確認します。

WP_Queryは小さく試すと理解しやすい

WP_Queryは難しそうに見えますが、最初に理解することは多くありません。まずは「条件を作る」「取得する」「ループで表示する」「最後に投稿データを戻す」という流れを押さえれば、基本的な読み方はできるようになります。

最初から複雑な条件を組む必要はありません。最新記事を3件だけ表示するような小さな例から始め、そこに post_type、カテゴリー条件、並び順などを少しずつ足していくと、どの引数が何を変えているのかを確認しながら学べます。