WP_Query 用語query args

WordPress で独自の投稿一覧を作る時、多くの場合は $args という配列を作り、new WP_Query( $args ) に渡します。この $args に入れる条件が query args です。

query args は、表示デザインそのものではありません。どの投稿を取得するかを決める条件です。取得した投稿を実際に表示するには、The Loop で1件ずつ処理します。

query args は何を指す言葉か

query args は、WP_Query に渡す引数の配列です。投稿タイプ、投稿ステータス、取得件数、並び順、分類条件、カスタムフィールド条件、日付条件などを指定できます。

たとえば、通常投稿を3件だけ取得したい場合は、post_type、post_status、posts_per_page を $args に書きます。条件が増えるほど、query args は長くなります。

ここで大事なのは、query args は「条件をまとめる入れ物」だということです。1つの引数だけで完結することもあれば、tax_query や meta_query のように、さらに内側に条件配列を持つこともあります。

初心者は、まず post_type、post_status、posts_per_page の3つから確認すると分かりやすくなります。最初からすべての引数を覚える必要はありません。

$args = [   'post_type'      => 'post',   'post_status'    => 'publish',   'posts_per_page' => 3,]; $query = new WP_Query( $args );

query args と query vars の違い

query args と query vars は似ていますが、同じ意味ではありません。query args は、開発者が WP_Query に渡す条件配列です。query vars は、WordPress がクエリ条件として扱う変数です。

たとえば、独自 WP_Query を作る時は $args に paged を指定します。その paged の値を現在の URL から取得する場合、get_query_var( ‘paged’ ) を使うことがあります。

query args は「これから作るクエリに渡す条件」と考えると分かりやすいです。query vars は「現在のクエリやURL状態から得られる条件値」と考えると整理しやすくなります。

ページネーション付きの独自クエリでは、この2つがつながります。現在ページ番号を query var から取得し、それを query args の paged に渡します。

Builder での扱い

WP Query Builder では、query args はユーザーの入力をコード化した最終的な条件配列として扱う想定です。画面上の「投稿タイプ」「件数」「並び順」「カテゴリー」「カスタムフィールド条件」などを $args に変換します。

初心者向けには、生成された $args が何を意味しているかを読みやすくすることが重要です。基本条件、分類条件、カスタムフィールド条件、日付条件を分けて見せると理解しやすくなります。

ページネーション付きのコードを出す場合は、固定値ではなく get_query_var( ‘paged’ ) から現在ページを取る処理も必要になることがあります。Builder では、ページ送りの有無に応じて出力を切り替えると安全です。

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

WP_Queryへ渡す取得条件を連想配列としてまとめ、コードと要件を対応づける時に使います。

未検証の配列を複数箇所で継ぎ足し、どの値が最終的に有効か分からない状態は避けます。

キー名のタイプミスや値の型違いはエラーにならず無視される場合があるため、生成配列の実値を確認します。

$args を実行直前に一度表示すると、別の処理で値が上書きされていないかを確かめられます。

実行直前の $args、取得できた投稿ID、想定条件を同じログへ出し、条件を一つずつ追加して差分を残します。

実践記事で確認WP_Queryの基本構文と$argsの書き方

$args の作成から new WP_Query()、ループ、リセットまでを一続きの基本構文で確認できます。

記事を読む →

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

公式資料では、WP_Query Class のリファレンスで、query args として指定できる多くの引数を確認できます。投稿タイプ、ステータス、件数、並び順、分類条件、メタ条件、日付条件などが整理されています。

現在の query var を取得する場合は、get_query_var() の公式リファレンスを確認します。独自 WP_Query 後に表示まで行う場合は、wp_reset_postdata() も合わせて確認します。

query args は、WP_Query に渡す取得条件の配列です。どの投稿を、何件、どの順番で、どんな条件で取得するかを $args にまとめます。

迷った時は、最小構成の $args から始めます。取得できることを確認してから、並び順、分類条件、カスタムフィールド条件、日付条件を少しずつ追加します。