WP_Query 用語WP_Query

WP_Query は、WordPress で「どの投稿を、どんな条件で、何件、どの順番で取得するか」を決めるための中心的な仕組みです。通常投稿の一覧だけでなく、カスタム投稿タイプ、カテゴリー別一覧、タグ別一覧、関連記事、カスタムフィールド条件付きの一覧などでも使われます。

初心者が最初に押さえるべきなのは、WP_Query は「表示そのもの」ではなく「取得条件を指定して投稿を取り出す仕組み」だという点です。実際に画面へ出すには、取得した投稿をループで処理します。

WP_Query は何をするものか

WP_Query は、投稿を検索・取得するための WordPress のクラスです。どの投稿タイプから取得するか、何件取得するか、どの順番にするか、どのカテゴリーやタグに属する投稿にするか、といった条件を指定できます。

WP_Query を使うと、WordPress が持っている投稿データを条件に合わせて取り出せます。たとえば「最新記事を3件だけ表示する」「カスタム投稿タイプの商品を10件表示する」「特定カテゴリーの記事だけ出す」といった実装ができます。

WP_Query は、記事一覧を作るための道具です。ただし、すべての一覧で必ず新しい WP_Query を作ればよいわけではありません。テーマがすでに表示しているメインクエリと、独自に作るサブクエリを分けて考える必要があります。

そのため、まずは「独自一覧を追加したい時に WP_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();

メインクエリと独自クエリの違い

WordPress には、ページを表示するために最初から用意されるメインクエリがあります。トップページ、カテゴリーアーカイブ、検索結果、投稿詳細などは、WordPress が表示内容に応じてメインクエリを作っています。

一方、new WP_Query() で自分で作るクエリは独自クエリです。たとえば、記事本文の下に関連記事を出したり、トップページの一部に最新記事を出したりする時に使います。

独自クエリを使った後に wp_reset_postdata() を忘れると、その後のテンプレートで意図しない投稿データを参照する原因になります。特にサイドバー、関連記事、カード一覧などを追加する時は注意します。

WP_Query を学ぶ時は、まず独自一覧の作り方を理解し、その後でメインクエリとの違いを確認する流れが分かりやすいです。

Builder での扱い

WP Query Builder では、WP_Query は生成されるコード全体の土台として扱う想定です。ユーザーが選んだ投稿タイプ、件数、並び順、分類条件、カスタムフィールド条件、日付条件を $args に変換し、最終的に new WP_Query( $args ) の形にします。

初心者向けには、いきなり WP_Query の全引数を見せるより、「何を取得するか」「何件取得するか」「どう並べるか」「何で絞り込むか」の順番で入力させると理解しやすくなります。

Builder で重要なのは、条件を増やしすぎた時に原因を切り分けられるようにすることです。生成コードでも、基本条件、分類条件、カスタムフィールド条件、日付条件を読み分けやすくすると、初心者が修正しやすくなります。

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

WordPressの投稿を条件付きで取得し、結果件数やページ情報を持つ専用のクエリオブジェクトが必要な時に使います。

メインクエリをテンプレート内で置き換える目的や、単純な1件取得まで常に新しい WP_Query オブジェクトを作るのは避けます。

取得条件だけでなく、ループ中のグローバル状態と終了後のリセットまでを一連の実装として扱います。

独自一覧を足すなら WP_Query、既存の一覧条件を変えるならメインクエリの調整、という切り分けが出発点です。

最小構成の $args で取得できた投稿ID、post_count、found_posts を確認し、ループ前後の現在の投稿IDも記録します。

実践記事で確認WP_Queryとは？初心者向けに役割と使い方を解説

WP_Query の役割、メインクエリとの違い、基本的な利用場面を全体像から確認できます。

記事を読む →

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

公式資料では、WP_Query Class のリファレンスで、投稿タイプ、ステータス、件数、並び順、タクソノミー、カスタムフィールド、日付などの引数を確認できます。

また、独自クエリ後に投稿データを戻す wp_reset_postdata()、テーマで投稿を表示する The Loop も合わせて確認すると、WP_Query の使いどころを理解しやすくなります。

WP_Query は、WordPress で投稿を取得するための中心的なクラスです。$args に条件を書き、取得した投稿をループで表示し、独自クエリ後は wp_reset_postdata() で戻します。

迷った時は、まず最小構成で1件だけ取得できるかを確認します。取得できたら、投稿タイプ、件数、並び順、分類条件、カスタムフィールド条件、日付条件の順に少しずつ広げます。