query_posts() の使い方｜説明・引数・注意点

説明

基本構文

query_posts( array|string $query ): WP_Post[]|int[]

引数

• $query：クエリの条件（配列または文字列）

戻り値

投稿の配列。

使い方（サンプル）

query_posts( 'posts_per_page=3' );
while ( have_posts() ) {
	the_post();
}
wp_reset_query();

注意点

• メインクエリを上書きするため、二重にクエリが実行され、ページ送りが、壊れやすくなります。
• 使ったあとは、wp_reset_query() で、元に戻す必要があります。
• 新しく書くコードでは、使いません。

実務での使いどころ

• 古いテーマの、コードを理解・修正するとき。

よくあるミスと対処

• 新しいコードで、使っている。メインクエリの変更は、pre_get_posts フックを使う。
• wp_reset_query() を、呼んでいない。
• サブの一覧を作りたいだけなのに、使っている。サブの一覧は、WP_Query を使う。

NG例

query_posts( 'posts_per_page=3' ); // 元に戻していない。二重にクエリが実行される

OK例

add_action( 'pre_get_posts', function ( $query ) {
	if ( ! is_admin() && $query->is_main_query() && $query->is_home() ) {
		$query->set( 'posts_per_page', 3 );
	}
} );

使い分け早見表

関連項目

wp_reset_query()、get_posts()

公式リファレンス：query_posts() | WordPress Developer Resources