WP_Queryの基本構文と$argsの書き方

この記事で作るものと4つの基本部分

作るのは、最新の通常投稿を取得して、タイトルとリンクを表示する小さな一覧です。まず取得条件を少なくしたコードで動作を確認し、その後に件数と並び順を足します。

基本構文を最初から丸暗記する必要はありません。それぞれのまとまりが何をしているかを日本語で言えるようにすると、サンプルコードを読み替えやすくなります。

そもそもWP_Queryが何をする仕組みなのか曖昧な場合は、先にWP_Queryの役割と使いどころを確認してから戻ると、ここで扱う4つのまとまりを追いやすくなります。

特に $args は、WP_Queryを学び始めた人が最初につまずきやすい場所です。$args は特別な魔法の名前ではなく、取得条件をまとめた配列です。名前は変えられますが、WordPressのサンプルでは $args という名前がよく使われるため、最初はそのまま覚えると読みやすいです。

この表の中で、最初に意識したいのは $args とループの境目です。$args は「どの投稿を取るか」を決める部分で、ループは「取ってきた投稿をどう表示するか」を決める部分です。ここを混同すると、表示件数を変えたいのにループ側を直そうとしたり、見た目を変えたいのに $args を触ってしまったりします。

コードはどこに書くのか

完成例は、クラシックテーマのテンプレートまたはテンプレートパーツで、一覧を表示したい位置に置きます。投稿本文やfunctions.phpの直下へ貼るコードではありません。functions.phpから呼ぶ場合は、関数・ショートコード・フックへ組み込み、実行条件と出力位置を決めます。

例では通常投稿を取得するためpost_typeをpostにしています。カスタム投稿で使う場合は、実際に登録されている投稿タイプスラッグへ変更してください。

設置場所ごとの違いは、専用記事が公開された後に次の案内から確認できます。

$argsの書き方は「対象・件数・順番」に分ける

$args に書ける条件はとても多いですが、最初から全部を覚える必要はありません。初心者がまず使うことが多いのは、取得対象、取得件数、並び順の3つです。

この3つに分けて考えると、実装時の迷いがかなり減ります。たとえば「イベントの一覧を5件出したい」なら、対象はイベントのカスタム投稿、件数は5件、順番は日付順、というように日本語で整理してから $args に落とし込めます。

event は説明用の例です。カスタム投稿で使うときは、実際に登録されている投稿タイプスラッグへ置き換えてください。

次に学ぶなら、post_typeの指定方法で取得対象を変えられるようにするのがおすすめです。

あわせて読みたいWP_Queryのorderbyとorderの違い記事を読む

基本構文を1つのコードで確認する

次の例は、通常投稿を新しい順に3件取得し、タイトルリンクをリスト表示します。最初はこのまま検証環境で動かし、表示できてから値を変えてください。

$args = [   'post_type'      => 'post',   'posts_per_page' => 3,   'orderby'        => 'date',   'order'          => 'DESC',]; $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();

コード全体を一度に読まず、次の3か所に分けて見ます。

$argsとnew WP_Query()

$argsには、通常投稿を3件、新しい順に取得する条件があります。new WP_Query( $args )はその条件で投稿を取得し、結果を$latest_postsへ入れます。変数名は任意ですが、取得内容が分かる名前にすると後のループを追いやすくなります。

have_posts()とthe_post()

$latest_posts->have_posts()で次の投稿があるかを確認し、$latest_posts->the_post()で1件分の投稿データを準備します。タイトルリンクはwhileの中にあるため、取得した投稿ごとに1行ずつ出力されます。

表示件数を変えるなら$argsのposts_per_page、日付や抜粋を追加するならループ内を変更します。取得条件と表示内容を分ければ、どこを直すべきか迷いにくくなります。

wp_reset_postdata()を最後に書く理由

独自WP_Queryで the_post() を呼ぶと、グローバルな現在の投稿データが独自クエリ側へ切り替わります。そのままにすると、ループ後の the_title() や the_content() が別投稿を参照する可能性があります。

そこで独自ループの末尾に wp_reset_postdata() を置き、メインクエリの投稿データへ戻します。最小例のように該当投稿がない場合は the_post() が呼ばれないため、投稿データも切り替わりません。

あわせて読みたいwp_reset_postdata()が必要な理由記事を読む

基本構文でよくあるつまずき

WP_Queryの基本構文で起きるミスは、複雑な条件よりも、基本の流れが少し崩れていることが原因になりやすいです。特に、$args の書き方、変数名の不一致、リセット忘れはよく確認したいポイントです。

エラーが出たときにすぐ全体を書き直すのではなく、まずは最小例に戻すのがおすすめです。1件だけ取得するコードに戻して動くか確認し、その後で条件を1つずつ足していくと、どの条件で崩れたかを見つけやすくなります。

確認する場所は4つです。

– 最初はpost_typeとposts_per_pageだけで試す
– new WP_Query()、have_posts()、the_post()で同じ変数名を使う
– the_post()を使った独自ループの後にwp_reset_postdata()を書く
– 取得条件と表示内容を同時に変更しない

また、$args の配列ではカンマの抜けにも注意が必要です。PHPの配列では、各行の区切りとしてカンマを使います。コードを貼り付けたあとに白い画面や構文エラーになる場合は、条件名のスペル、クォート、カンマを落ち着いて確認してください。

基本構文が動いたら、目的に必要な条件を1つずつ足します。取得対象なら post_type、件数なら posts_per_page、並び順なら orderby と order のように、変更する役割を分けると原因を追いやすくなります。

公式資料で確認するポイント

WP_Queryの構文や引数は、公式リファレンスを基準に確認します。$args に指定できる条件は多いため、記事やサンプルコードだけで覚えるのではなく、必要な引数の仕様と使用例を公式資料で照合してください。

ループの動きで迷ったときはThe Loop、the_post() のあとに戻す理由を確認したいときは wp_reset_postdata() の資料を見ると、役割を分けて理解できます。

基本構文は4つに分けて覚える

WP_Queryの基本構文は、長いコードとして覚えるよりも、4つのまとまりに分けて理解するほうが実装しやすくなります。$args は取得条件、new WP_Query() は取得、have_posts() と the_post() は表示のためのループ、wp_reset_postdata() は後片付けです。

まずは完成例をそのまま検証環境で試し、表示できたら件数や投稿タイプを1つずつ変えます。変更箇所を分ければ、表示されなくなった時も直前に足した条件から確認できます。