WP_Query クラスの使い方｜説明・引数・注意点

説明

基本構文

new WP_Query( array|string $query = '' )

引数

• $query：取得条件の配列（post_type、posts_per_page、category_name、meta_query、tax_query、orderby、paged など）

戻り値

WP_Query オブジェクト。have_posts() / the_post() でループを回します。

使い方（サンプル）

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

注意点

• ループの後は必ず wp_reset_postdata() を呼びます。
• メインクエリの条件を変えたいときは、新しく WP_Query を作らず pre_get_posts フックを使います。
• posts_per_page に -1 を指定すると全件取得になり、件数が多いと重くなります。
• ページ送りには paged と、$q->max_num_pages を使います。

実務での使いどころ

• 投稿の一覧を、条件（投稿タイプ、タクソノミー、カスタムフィールド）を指定して、取得・表示するとき。
• ページ送りつきの、独自の一覧を、作るとき。
• 関連記事や、新着記事など、別枠の一覧を出すとき。

よくあるミスと対処

• ループのあとに、wp_reset_postdata() を呼ばず、後続の表示が、サブクエリの最後の投稿の情報になる。
• ページ送りに、paged を渡していない。2ページ目以降が、1ページ目と同じ内容になる。
• posts_per_page に -1 を指定し、件数が多いサイトで、重くなる。
• ページ送りが不要なのに、no_found_rows を、true にしていない（総件数の計算が、余分に行われる）。
• メインクエリの一覧を、変えたいのに、new WP_Query を使っている。メインクエリの変更は、pre_get_posts フックを使う。

NG例

$q = new WP_Query( array( 'post_type' => 'news', 'posts_per_page' => -1 ) );
while ( $q->have_posts() ) {
	$q->the_post();
	the_title();
}
// wp_reset_postdata() がなく、全件を取得している

OK例

$q = new WP_Query( array(
	'post_type'      => 'news',
	'posts_per_page' => 5,
	'no_found_rows'  => true,
) );
if ( $q->have_posts() ) {
	while ( $q->have_posts() ) {
		$q->the_post();
		the_title();
	}
}
wp_reset_postdata();

使い分け早見表

関連項目

get_posts()、pre_get_posts、wp_reset_postdata()

公式リファレンス：WP_Query | WordPress Developer Resources