WP_Query 用語query vars

query vars は、WordPress の「今どんな条件で投稿を探しているか」を表す値です。たとえば検索結果ページなら検索語、2ページ目ならページ番号、カテゴリーアーカイブならカテゴリー情報が、クエリ条件として扱われます。

初心者が迷いやすいのは、query vars と WP_Query の $args の関係です。$args は開発者が WP_Query に渡す条件配列です。query vars は、WordPress が現在のリクエストやクエリの中で持っている条件値として考えると整理しやすくなります。

query vars は何を指す言葉か

query vars は、WordPress がクエリ条件として扱う変数です。どの投稿タイプを見るか、どの検索語で探すか、現在何ページ目か、どのカテゴリーやタグを対象にするか、といった情報が該当します。

WordPress は、アクセスされた URL や内部の処理をもとに query vars を組み立てます。その値を使って main query が作られ、現在のページに表示する投稿が決まります。

ここで大事なのは、query vars は表示そのものではなく、取得条件の材料だということです。実際の表示は、main query や WP_Query の結果を The Loop で処理して行います。

つまり、表示がおかしい時は、テンプレートだけでなく「どんな query vars が入っているか」も確認する必要があります。特にページネーションや検索結果では重要です。

query vars と $args の違い

query vars と $args は関係していますが、同じ言葉ではありません。query vars は WordPress がクエリ条件として持つ変数です。$args は、開発者が WP_Query に渡す条件配列です。

独自 WP_Query を作る場合、開発者は $args に post_type、posts_per_page、paged などを書きます。これらは WP_Query のクエリ条件として使われます。

たとえば、URL や現在のページから得られるページ番号は query vars として扱われます。その値を独自 WP_Query の $args に入れることで、ページネーション付きの独自一覧を作れます。

このように、query vars は現在の状態を知るための材料にもなり、$args は新しくクエリを作るための指定にもなります。

Builder での扱い

WP Query Builder では、query vars は「現在のページ状態やURLから取得される値」として扱う想定です。特に、ページネーションの paged や検索語の s は、生成コードで重要になります。

Builder では、固定値を入れるのか、現在の query var から値を取るのかを分けて見せると分かりやすくなります。たとえば、ページ番号は固定値ではなく get_query_var( ‘paged’ ) から取得することがあります。

特にページネーション付きの独自 WP_Query では、paged を正しく渡さないと、2ページ目以降が期待どおりに表示されません。Builder では、ページ送りの有無に応じて get_query_var( ‘paged’ ) のコードを出す方針が必要です。

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

WordPressがURLやフックから解釈した検索条件を、メインクエリの現在値として確認・変更する時に使います。

自分で作る $args 配列と常に同一のものだと扱ったり、未登録のURL値を無条件に信用したりしません。

書き換える時点と対象クエリを誤ると反映されないか広範囲へ作用するため、フックと条件分岐を記録します。

URLから来た値とフックで変更した値を分けて記録すると、どの時点で条件が変わったか追えます。

対象URLで受け取ったクエリ変数、pre_get_posts 後の値、最終的に表示された投稿IDを並べ、変更経路を追跡します。

実践記事で確認query_postsを使わないほうがいい理由

メインクエリを query_posts() で置き換えず、既存のクエリ変数を安全に調整する考え方を確認できます。

記事を読む →

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

公式資料では、WP_Query Class でクエリ引数の全体を確認できます。現在の query var を取得する場合は、get_query_var() のリファレンスを確認します。

独自の query vars を追加する場合は、query_vars フィルターを確認します。ただし、まずは標準の query vars と WP_Query の基本を理解してから扱うと安全です。

query vars は、WordPress がクエリ条件として扱う値です。検索語、ページ番号、投稿タイプ、カテゴリーなど、どの投稿を取得するかに関係します。

迷った時は、現在のページ状態から取る値なのか、独自 WP_Query の $args に固定で書く値なのかを分けます。特にページネーションでは、paged の取得と指定を確認します。