WP_Query - WordPress リファレンス

Q: WP_Queryとget_posts()の違いは何ですか？

WP_Queryは、より詳細なクエリを構築できますが、get_posts()は単純なクエリ用の簡易版です。

Q: WP_Queryでカスタムタクソノミーを使うには？

tax_queryを使います。 $args = array( 'post_type' => 'book', 'tax_query' => array( array( 'taxonomy' => 'genre', 'field' => 'slug', 'terms' => 'fiction', ), ),);$query = new WP_Query( $args );

WP_Queryは、WordPress内で投稿、カスタム投稿、ページなどのデータを柔軟に取得するためのクラスです。標準の投稿取得関数（例：get_posts()）よりも詳細な条件でクエリを構築でき、テンプレートやプラグインでよく利用されます。

機能の説明

WP_Queryを使うことで、指定した投稿タイプやカテゴリ、カスタムタクソノミー、メタ情報に基づいた投稿を取得するクエリを作成できます。アーカイブページやウィジェット、ループ内での投稿表示に適しています。

シンプルなコード例

$query = new WP_Query( array( 'post_type' => 'post', 'posts_per_page' => 5 ) );
if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title();
    }
    wp_reset_postdata();
}

このコードでは、最新の投稿5件を取得し、タイトルを表示します。wp_reset_postdata()を呼び出すことで、メインクエリに戻しています。

使い方の解説

引数

$args

投稿を取得するための条件を配列で指定します。主な例は以下の通りです。

post_type: 投稿タイプ（例：post、page、custom_post_type）。
posts_per_page: 取得する投稿数。-1にするとすべての投稿を取得します。
category_name: カテゴリスラッグで指定（例：news）。
tag: タグを指定。
meta_query: メタキーの条件でフィルタリングします。

戻り値

WP_Query オブジェクト: クエリ結果が含まれたオブジェクトです。メソッドで投稿にアクセスできます。

オプション

have_posts(): クエリに投稿が含まれている場合にtrueを返します。
the_post(): 次の投稿データを取得し、テンプレート内で利用できる状態にします。

使用例

WP_Queryの幅広い使い方を学ぶことができます。カテゴリやタクソノミー、メタデータの条件を組み合わせた高度なフィルタリングから、ページネーションや検索キーワードによる抽出まで、WP_Queryは柔軟で強力なツールです。

カスタムフィールドの値を絞って抽出する

$args = array(
    'post_type'      => 'product',
    'posts_per_page' => 3,
    'meta_query'     => array(
        array(
            'key'   => '_price',
            'value' => '1000',
            'compare' => '>',
            'type'   => 'NUMERIC'
        )
    )
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title();
        echo get_post_meta( get_the_ID(), '_price', true );
    }
    wp_reset_postdata();
}

この例では、カスタム投稿タイプproductから価格（_price）が1000より大きい商品を3件取得し、商品名と価格を表示します。

特定のカスタム投稿タイプの記事を抽出する

$args = array(
    'post_type' => 'portfolio', // カスタム投稿タイプ「portfolio」
    'posts_per_page' => 5, // 5件まで取得
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
        the_content();
    }
    wp_reset_postdata();
}

この例では、portfolioというカスタム投稿タイプから5件の投稿を取得しています。wp_reset_postdata()でクエリ終了後にメインクエリへ戻します。

特定カテゴリーの記事を取得する

$args = array(
    'category_name' => 'news', // カテゴリ「news」を指定
    'posts_per_page' => 10, // 最大10件取得
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
        echo get_the_date();
    }
    wp_reset_postdata();
}

category_nameで特定のカテゴリーに属する投稿を取得する例です。the_title()でタイトル、get_the_date()で日付を表示します。

複数の条件でフィルタリング（メタキーを使った検索）

$args = array(
    'post_type' => 'event',
    'meta_query' => array(
        array(
            'key'     => '_event_date', // メタキー「_event_date」
            'value'   => date( 'Ymd' ), // 今日の日付を基準に
            'compare' => '>=', // 未来のイベントのみ取得
            'type'    => 'NUMERIC',
        ),
    ),
    'orderby' => 'meta_value_num', // 日付順にソート
    'order'   => 'ASC',
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h4>', '</h4>' );
        echo '開催日: ' . get_post_meta( get_the_ID(), '_event_date', true );
    }
    wp_reset_postdata();
}

この例では、_event_dateというメタキーを使って未来のイベントを取得します。さらに、orderbyで日付順に並び替えています。

カスタムタクソノミーの条件で抽出する

$args = array(
    'post_type' => 'book',
    'tax_query' => array(
        array(
            'taxonomy' => 'genre', // カスタムタクソノミー「genre」
            'field'    => 'slug',
            'terms'    => 'fiction', // 「fiction」ジャンルの投稿のみ
        ),
    ),
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata();
}

この例では、カスタムタクソノミーgenreにおけるfictionというタームを持つ投稿を取得しています。タクソノミーを使った投稿の抽出は、特定のカテゴリーやジャンルごとのフィルタリングに便利です。

投稿のページネーションを実装する

$paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;

$args = array(
    'post_type'      => 'post',
    'posts_per_page' => 5,
    'paged'          => $paged,
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    previous_posts_link( '前のページ' );
    next_posts_link( '次のページ', $query->max_num_pages );
    wp_reset_postdata();
}

ページネーションを使う場合は、pagedパラメータを指定します。previous_posts_link()とnext_posts_link()で、前後のページリンクを表示します。

投稿IDを指定して特定の記事を取得する

$args = array(
    'p' => 42, // 投稿IDが42の投稿を取得
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h1>', '</h1>' );
        the_content();
    }
    wp_reset_postdata();
}

この例では、投稿IDを指定して特定の投稿を取得します。単一の投稿を取得したい場合に有用です。

投稿のステータスを指定して取得する（例：下書き記事）

$args = array(
    'post_type'   => 'post',
    'post_status' => 'draft', // ステータスが「下書き」の投稿
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、投稿のステータスがdraft（下書き）のものだけを取得します。記事の管理用ページなどで使用できます。

特定の投稿者の投稿を取得する

$args = array(
    'author' => 1, // 投稿者IDが1のユーザーの投稿
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata();
}

この例では、投稿者IDが1のユーザーの投稿を取得しています。投稿者ごとの記事リストを表示する場合に便利です。

ランダムな順番で投稿を取得する

$args = array(
    'post_type'      => 'post',
    'posts_per_page' => 3,
    'orderby'        => 'rand', // ランダム順で表示
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata();
}

この例では、投稿をランダムな順番で取得します。特定の投稿をランダム表示するウィジェットやおすすめ記事機能に使えます。

パスワード保護された投稿を取得する

$args = array(
    'post_type'      => 'post',
    'has_password'   => true, // パスワード保護された投稿
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、パスワード保護された投稿を取得しています。特定のユーザー向けに限定公開する記事リストを表示する場合に使えます。

カスタムフィールドの値でソートする

$args = array(
    'post_type'      => 'product',
    'meta_key'       => '_price',
    'orderby'        => 'meta_value_num',
    'order'          => 'ASC',
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
        echo '価格: ' . get_post_meta( get_the_ID(), '_price', true );
    }
    wp_reset_postdata();
}

この例では、カスタムフィールド_priceの値で商品を昇順にソートしています。価格順で商品リストを表示する際に使えます。

投稿の日付範囲を指定して取得する

$args = array(
    'post_type'      => 'post',
    'date_query'     => array(
        array(
            'after'     => '2023-01-01',  // 2023年1月1日以降の投稿
            'before'    => '2023-12-31',  // 2023年12月31日までの投稿
            'inclusive' => true,  // 境界値を含む
        ),
    ),
    'posts_per_page' => -1, // 全件取得
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
        echo get_the_date();
    }
    wp_reset_postdata();
}

この例では、date_queryを使って特定の期間内に投稿された記事を取得しています。inclusiveオプションで境界値を含むかどうかを指定できます。

複数カテゴリー・タクソノミーの条件で取得する

$args = array(
    'post_type' => 'post',
    'category__and' => array( 1, 3 ),  // カテゴリID 1と3の両方を持つ投稿
    'tax_query' => array(
        array(
            'taxonomy' => 'post_tag',  // タクソノミー「タグ」
            'field'    => 'slug',
            'terms'    => array( 'featured', 'popular' ),  // いずれかのタグを含む
            'operator' => 'IN',  // いずれかの条件に一致
        ),
    ),
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h3>', '</h3>' );
    }
    wp_reset_postdata();
}

この例では、カテゴリIDが1と3の両方に属し、タグがfeaturedまたはpopularのいずれかを持つ投稿を取得します。複雑な条件を設定する場合に有用です。

カスタムフィールドの範囲でフィルタリングする

$args = array(
    'post_type'  => 'product',
    'meta_query' => array(
        array(
            'key'     => '_price',
            'value'   => array( 1000, 5000 ),  // 価格が1000〜5000の範囲
            'compare' => 'BETWEEN',
            'type'    => 'NUMERIC',
        ),
    ),
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
        echo '価格: ' . get_post_meta( get_the_ID(), '_price', true );
    }
    wp_reset_postdata();
}

この例では、価格が1000円から5000円の範囲にある商品を取得しています。meta_queryとBETWEENを使って範囲指定のフィルタを行います。

カスタム投稿タイプと通常投稿を同時に取得する

$args = array(
    'post_type' => array( 'post', 'portfolio' ),  // 通常投稿とカスタム投稿を同時取得
    'posts_per_page' => 10,
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        echo '<h3>' . get_post_type() . ': ' . get_the_title() . '</h3>';
    }
    wp_reset_postdata();
}

この例では、postとportfolioという2種類の投稿タイプの投稿を一度に取得します。get_post_type()で投稿タイプを表示しています。

パスワード保護された投稿を含む投稿を取得する

$args = array(
    'post_type'      => 'post',
    'posts_per_page' => 5,
    'post_status'    => array( 'publish', 'private' ),  // 公開と非公開投稿を取得
    'has_password'   => true,  // パスワード保護された投稿を含む
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、公開された投稿とプライベートな投稿を含め、パスワード保護された投稿も取得します。

Sticky Post（固定表示投稿）のみを取得する

$args = array(
    'post_type'      => 'post',
    'posts_per_page' => -1,
    'post__in'       => get_option( 'sticky_posts' ),  // 固定投稿のみ
    'ignore_sticky_posts' => 1,  // メインクエリの固定表示を無視
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、get_option('sticky_posts')で固定表示された投稿を取得しています。ignore_sticky_postsを使用することで、他のクエリで固定投稿を無視できます。

検索キーワードで投稿を取得する

$args = array(
    'post_type'      => 'post',
    's'              => 'WordPress',  // 検索キーワード「WordPress」
    'posts_per_page' => 5,
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
        the_excerpt();  // 抜粋を表示
    }
    wp_reset_postdata();
}

この例では、sパラメータを使用して「WordPress」というキーワードで検索しています。検索機能の拡張に使用します。

投稿数の上限を設定し、オフセットする（ページ送り用）

$args = array(
    'post_type'      => 'post',
    'posts_per_page' => 5,  // 5件取得
    'offset'         => 10,  // 10件目から取得
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、投稿の取得開始位置を10件目からに設定し、5件だけ取得しています。offsetはページングなどで使われます。

クエリ結果をキャッシュしない

$args = array(
    'post_type' => 'post',
    'no_found_rows' => true,  // 総件数の計算を省略して高速化
    'cache_results' => false,  // キャッシュを無効化
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        the_title( '<h2>', '</h2>' );
    }
    wp_reset_postdata();
}

この例では、no_found_rowsをtrueにすることで、総件数の計算をスキップしてクエリのパフォーマンスを向上させています。

一緒に使うことが多い関連タグ

get_posts()

get_posts()は、シンプルなクエリを構築するためのテンプレートタグです。WP_Queryの簡易版として利用できます。

$posts = get_posts( array( 'posts_per_page' => 3 ) );
foreach ( $posts as $post ) {
    setup_postdata( $post );
    the_title();
}
wp_reset_postdata();

この例では、最新の投稿を3件取得してタイトルを表示しています。setup_postdata()を使うことで、the_title()などのテンプレートタグを利用できるようにしています。

追加情報を取得したい場合

get_the_category() で取得できるカテゴリー情報

$categories = get_the_category();
foreach ( $categories as $category ) {
    echo $category->name;
}

出力できる情報

name: カテゴリー名
slug: カテゴリーのスラッグ
term_id: カテゴリーのID
description: カテゴリーの説明

想定されるトラブル

投稿が表示されない

クエリの引数が正しく設定されているか確認してください。また、カスタム投稿タイプやタクソノミーの設定を確認することも重要です。

メインクエリに影響を与える

wp_reset_postdata()を使って、メインクエリに戻してください。

Q&A

`WP_Query`と`get_posts()`の違いは何ですか？

WP_Queryは、より詳細なクエリを構築できますが、get_posts()は単純なクエリ用の簡易版です。

`WP_Query`でカスタムタクソノミーを使うには？

tax_queryを使います。

$args = array(
    'post_type' => 'book',
    'tax_query' => array(
        array(
            'taxonomy' => 'genre',
            'field'    => 'slug',
            'terms'    => 'fiction',
        ),
    ),
);
$query = new WP_Query( $args );

`posts_per_page`の最大値はありますか？

サーバー設定によりますが、一般的にはパフォーマンスに影響があるため、大きすぎる値は避けましょう。

まとめ

WP_Queryは、WordPressで高度な投稿取得を可能にする強力なクラスです。カスタム投稿やメタデータ、タクソノミーを使った検索を簡単に実装でき、アーカイブやカスタムページでの表示に便利です。

カスタマイズ例

カテゴリーで同じタグが付けられている記事リストを表示する

まとめこのカスタマイズを導入することで、記事の末尾に関連性の高い記事を表示し、サイトの回遊率を向上させることができます。クエリ構築や条件分岐が必要なため、WordPressの基本的な知識が求められますが、ユーザビリティの向上に大きく貢献します。

2024/10/30 Wednesday

WP_Query– Class –