WP_QUERY RECIPES

WP_Query 実装例

「どこに書くか」を決めてから、よく使う取得パターンを最小構成で確認します。

このコードはどこに書く？

取得方法だけでなく、機能の寿命と影響範囲に合わせて置き場所を選びます。

サイト全体の機能

site-specific plugin

テーマを変更しても残したい取得条件や機能を置きます。

その画面だけの表示

page template / template part

テンプレート固有の副次的な一覧を組み立てます。

メイン一覧の条件変更

pre_get_posts

WordPressが作るmain queryをhookで調整します。

実装例を選ぶ

目的に近い例から、置き場所・最小構成・注意点をまとめて確認します。

page template

固定ページに新着記事を3件表示する

固定ページの本文とは別に「新着記事」「関連記事」などの小さな一覧を足したいときに使います。画面内へ追加する副次的な一覧なので、新しいWP_Queryを作り、表示後に投稿データを戻します。

PHPpage-example.php

$recent = new WP_Query([    'post_type'      => 'post',    'post_status'    => 'publish',    'posts_per_page' => 3,]); if ($recent->have_posts()) {    while ($recent->have_posts()) {        $recent->the_post();        get_template_part('template-parts/card');    }} wp_reset_postdata();

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

if ($recent->have_posts()) {
    while ($recent->have_posts()) {
        $recent->the_post();
        get_template_part('template-parts/card');
    }
}

wp_reset_postdata();

site-specific plugin

カテゴリー一覧を12件表示にする

カテゴリーアーカイブそのものの件数を変えたいときに使います。テンプレート内でmain queryを作り直さず、pre_get_postsで対象画面だけを安全に調整します。

PHPsite-specific-plugin.php

add_action('pre_get_posts', function (WP_Query $query): void {    if (is_admin() || ! $query->is_main_query()) {        return;    }     if ($query->is_category()) {        $query->set('posts_per_page', 12);    }});

add_action('pre_get_posts', function (WP_Query $query): void {
    if (is_admin() || ! $query->is_main_query()) {
        return;
    }

    if ($query->is_category()) {
        $query->set('posts_per_page', 12);
    }
});

query service

カテゴリーと価格条件を組み合わせる

商品一覧などで「特定カテゴリーかつ価格以内」のように条件を重ねたいときに使います。tax_queryとmeta_queryを分け、数値比較では値の型まで明示します。

PHPquery-service.php

$products = new WP_Query([    'post_type' => 'product',    'tax_query' => [[        'taxonomy' => 'product_category',        'field'    => 'slug',        'terms'    => ['featured'],    ]],    'meta_query' => [[        'key'     => 'price',        'value'   => 5000,        'compare' => '<=',        'type'    => 'NUMERIC',    ]],]);

$products = new WP_Query([
    'post_type' => 'product',
    'tax_query' => [[
        'taxonomy' => 'product_category',
        'field'    => 'slug',
        'terms'    => ['featured'],
    ]],
    'meta_query' => [[
        'key'     => 'price',
        'value'   => 5000,
        'compare' => '<=',
        'type'    => 'NUMERIC',
    ]],
]);

実装前の3点確認

コードを貼る前に、変更する一覧の種類と影響範囲を切り分けておくと、表示崩れや意図しない取得を防げます。

main queryかsecondary queryかを区別する
ループ後にwp_reset_postdata()が必要か確認する
本番データ量で速度と件数を確認する

次に確認すること

使えそうなコードが見つかったら、解説記事で背景を補い、パラメーターの役割やトラブル時の確認先もあわせて押さえておくと、実装後の迷いを減らせます。