表示件数がおかしい！posts_per_page の指定でWebデザイナーがハマる落とし穴とは？
WordPressで特定の投稿一覧ページ（例：カスタム投稿タイプアーカイブ、固定ページ内のループ）を作成する際、WP_Queryやquery_posts（非推奨）を用いて表示件数を制御するのは日常茶飯事です。このとき、指定するのが有名な引数posts_per_pageでしょう。しかし、なぜか意図した件数で表示されず、サイト全体の「表示設定」で指定した件数のままだったり、全件表示にしたいのに上手くいかなかったりして、「あれ？なんでだろう？」と頭を抱えた経験はありませんか？ これはコードの書き方自体は間違っていなくても、引数に入れる「値」がもつ意味を誤解していると起こりがちな現象です。
特に、Webデザイナーとしてクライアントワークで多岐にわたる案件をこなす場合、案件ごとに異なる表示ロジックを正確に制御するスキルは、もはや必須能力であります。
本記事では、この
posts_per_pageに指定できる3つの主要な値の意味と、2025年現在のWordPressの正しい挙動を明確に解説します。posts_per_page に指定すべき3つの値とその役割
posts_per_pageは、クエリで取得する投稿の最大件数を制御するパラメータです。指定できる値は基本的に「正の整数」「0」「-1」の3パターンに集約されます。| 指定する値 | 役割・挙動 | 実務での利用シーン |
|---|---|---|
正の整数（例：5） |
指定した件数（n）の投稿を表示します。最も一般的な使い方です。 | トップページの新着記事欄、関連投稿リストなど |
0 |
WordPress管理画面の「表示設定」で指定された件数を適用します。 | 個別ページング機能を実装するカスタムアーカイブページなど、設定に依存させたい場合 |
-1 |
すべての投稿を件数無制限で取得・表示します。 | すべてのタグリスト、全件表示が必要なポートフォリオ一覧など |
これらの値を意図的に使い分けることが、表示件数制御をマスターする鍵です。
ケーススタディ：実務で必須のposts_per_page 正しいコードスニペット
実際にposts_per_pageを適用する際、主要な3つのケースに分けて、具体的なコードを見ていきましょう。なお、モダンなWordPress開発では、WP_Queryクラスの使用を推奨します。①件数（n）を指定して表示する
特定の件数だけを表示させたい、最も標準的なケースです。例えば、トップページに最新の投稿を5件だけ表示したい場合に適用します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
// 新着投稿を5件だけ表示するクエリ $args = array( 'post_type' => 'post', // 投稿タイプ 'posts_per_page' => 5, // 取得する件数を5件に指定 'orderby' => 'date', 'order' => 'DESC', ); $the_query = new WP_Query( $args ); if ( $the_query->have_posts() ) : // ループ処理... while ( $the_query->have_posts() ) : $the_query->the_post(); // 投稿の表示処理 endwhile; wp_reset_postdata(); // クエリのリセットは忘れずに endif; |
表示件数を固定したい場合は、この正の整数を指定するのが一番手っ取り早いでしょう。直感的に理解しやすい使い方です。
②管理画面の「表示設定」に依存させる場合（値：0）
これがWebデザイナーが意外と見落としがちなポイントかもしれません。WordPressの「設定」→「表示設定」にある「1ページに表示する最大投稿数」の値を利用したい場合は、
posts_per_pageに「0」を指定します。0を指定することで、カスタムクエリであっても管理画面の設定値が継承されるという動作になります。ページネーションを伴うカスタム投稿アーカイブなど、管理者が設定値を変えられた方が都合が良い場合に大変有効です。
|
1 2 3 4 5 6 7 |
// 表示設定の値を適用するクエリ $args = array( 'post_type' => 'my_portfolio', 'posts_per_page' => 0, // 👈 ココ！ 管理画面の値を適用 'paged' => get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1, // ページネーション用 ); // ...クエリの実行とループ処理 |
以前のWordPressバージョンや一部の情報では、posts_per_pageを省略するか、値を指定しないことで管理画面の設定が適用されるとされてきました。
しかし、明示的に「0」を指定することで、意図がより明確になり、クエリが複雑になる環境下でも意図しない上書きを防ぐ効果が期待できます。省略せずに0の利用を検討すべきです。
③全件表示をさせる場合（値：-1）
カスタム投稿やカスタムタクソノミーの一覧ページなどで、ページングなしで全ての投稿を一度に表示したいことがあります。この場合は、
posts_per_pageに-1を指定します。
|
1 2 3 4 5 6 7 8 |
// 投稿を全件表示するクエリ $args = array( 'post_type' => 'product', 'posts_per_page' => -1, // 👈 全件取得を指定 'orderby' => 'menu_order', // 必要に応じて並び替え 'order' => 'ASC', ); // ...クエリの実行とループ処理 |
ただし、全件表示はサイトのパフォーマンスに大きな影響を与えます。特に、投稿件数が数百件を超えるような大規模サイトで安易に-1を使うと、サーバーに負荷がかかり、表示が「もっさり」してしまう可能性は高いです。
デザイン上の要請がない限り、極力避けるか、代替策としてAjaxロードなど部分的な表示方法を検討すべきでしょう。
pre_get_posts アクションでメインクエリを操作する
特定のアーカイブページ全体で表示件数を変えたい場合、テンプレートファイル内でWP_Queryを新しく作成するよりも、メインクエリを操作する方が、ページネーションの挙動などが安定するため推奨されます。この操作に用いるのが
pre_get_postsアクションフックです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
function change_archive_posts_per_page( $query ) { // 管理画面の操作などでメインクエリが変更されていないかを確認 if ( is_admin() || ! $query->is_main_query() ) { return; } // 例：特定のカスタム投稿タイプ「event」のアーカイブページでのみ適用 if ( $query->is_post_type_archive( 'event' ) ) { // イベントアーカイブの表示件数を8件に固定 $query->set( 'posts_per_page', 8 ); } // 例：特定のカスタムタクソノミー「genre」のタームページでのみ全件表示 if ( $query->is_tax( 'genre' ) ) { // 全件表示は -1 $query->set( 'posts_per_page', -1 ); } } add_action( 'pre_get_posts', 'change_archive_posts_per_page' ); |
この方法であれば、表示件数の指定は一度フックに記述するだけで済み、テーマテンプレート内で何度もクエリを記述する必要がなくなります。
また、管理画面で設定した値（0の挙動）を意図的に上書きしたい場合にも非常に有効な手段といえるでしょう。
まとめ
本記事では、WordPressにおける投稿の表示件数制御の核心となる引数posts_per_pageについて、以下の3つの値を正しく使い分ける重要性を解説しました。これを覚えておくだけで、WordPress案件における表示ロジックの制御は格段に安定します。特に、「0」の挙動を理解しておくことは、クライアントの要望に柔軟に対応するための秘訣です。
コメント