WP_Query パラメーターposts_per_page

posts_per_page は、WP_Query の中でも特によく使う引数です。記事一覧、関連記事、トップページの新着記事、カスタム投稿タイプの一覧など、「何件出すか」を決める場面で使います。

ただし、posts_per_page は「条件に合う投稿の総数」を指定する引数ではありません。1ページに何件取得するかを指定する引数です。ページネーションがある場合は、条件に合う投稿が30件あっても、posts_per_page が10なら1ページ目には10件だけ取得されます。

posts_per_page は何を指定する引数か

posts_per_page は、WP_Query で取得する投稿数を制御するための引数です。名前の通り、1ページあたりに何件の投稿を取得するかを指定します。

たとえば、トップページに新着記事を3件だけ表示したい場合は posts_per_page に 3 を指定します。記事一覧を10件ずつページ送りしたい場合は 10 を指定します。

ここで重要なのは、posts_per_page は「表示したい最大件数」として考えることです。条件に合う投稿が2件しかない場合、posts_per_page に 5 を指定しても、実際に取得されるのは2件です。

逆に、条件に合う投稿が100件ある場合でも、posts_per_page に 5 を指定すれば、通常は現在のページで5件だけ取得されます。総件数やページ数は、found_posts や max_num_pages など別の情報として確認します。

posts_per_page、posts_per_archive_page、paged、offset の違い

posts_per_page と一緒に混同しやすい引数があります。特に posts_per_archive_page、paged、offset は、表示件数やページ送りに関係するため、役割を分けて理解しておくと安全です。

posts_per_archive_page は、アーカイブページや検索結果などで関係する件数指定です。通常の一覧では posts_per_page を見ていても、アーカイブや検索結果だけ件数が違う場合は、posts_per_archive_page の影響を疑います。

paged は、現在何ページ目かを WP_Query に伝えるために使います。posts_per_page が「1ページに何件か」を決めるのに対して、paged は「今どのページか」を決める役割です。

offset は、先頭から何件か飛ばすための引数です。便利に見えますが、ページネーションと一緒に使うと、2ページ目以降の件数や投稿の続き方がずれやすくなります。表示件数がおかしい時は、offset を一度外して確認するのがおすすめです。

Builder での扱い

WP Query Builder では、posts_per_page は件数指定の基本項目として扱う想定です。post_type や post_status を決めた後に、何件取得するかを指定する流れにすると、初心者にも分かりやすくなります。

Builder の入力欄では、最初から大きな数や -1 を使わせるより、1件、3件、5件、10件のような小さい候補を用意すると安全です。確認用のクエリでは1件、カード一覧では3件、通常の一覧では10件のように、用途別に選べると迷いにくくなります。

Builder 側でページネーションを扱う場合は、posts_per_page と paged をセットで考えます。posts_per_page だけでは、2ページ目、3ページ目の取得までは決まりません。

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

1ページに返す投稿件数を決め、表示密度やページ数を要件へ合わせる時に使います。

全件が必要か検討せず -1 にしたり、総件数そのものを変える指定だと考えたりしません。

固定表示投稿、offset、管理画面設定との関係で見える件数が変わるため、post_count と found_posts を分けます。

画面に10件出す設定と、条件に該当した総件数は別なので、post_count と found_posts を使い分けます。

設定値、取得できた投稿IDの数、post_count、found_posts、max_num_pages を同時に出力し、1〜2ページ目で比較します。

実践記事で確認表示件数が合わないときの確認事項と対処法まとめ

表示件数と総件数の違い、設定値どおりに見えない原因を実例で確認できます。

記事を読む →

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

公式資料では、WP_Query の posts_per_page は Pagination Parameters の中で説明されています。1ページあたりの投稿数を指定する引数として確認できます。

また、未指定の場合に関係する表示設定は、WordPress のオプション値として扱われます。実装中に「コードでは件数を指定していないのに何件か表示される」場合は、管理画面の表示設定や、関連するオプション値を確認します。

posts_per_page は、WP_Query の表示件数を決める基本的な引数です。ただし、指定した件数が必ず表示されるとは限りません。条件に合う投稿が少なければ、その件数までしか表示されません。

迷った時は、最小構成で1件だけ取得し、その後で件数を増やします。ページネーションがある場合は paged、アーカイブや検索結果だけ件数が違う場合は posts_per_archive_page、2ページ目以降がずれる場合は offset も確認します。