WP_Queryで表示件数とページネーションを設定する方法
｜posts_per_page・pagedの基本

ページネーションは4つの値でできている

表示件数だけ指定しても、WP_Queryは現在が何ページ目か分かりません。ページリンクを表示するだけでは投稿は切り替わらず、取得側へ現在ページを渡す必要があります。件数・現在ページ・総ページ数・リンクを、次のようにつなぎます。

WP_Queryとpaginate_links()をつないだ完成例

次のコードは、検証用の通常投稿6件（ID 10〜15）を3件ずつ取得し、番号付きページネーションを表示します。画像・表でも同じ6件を使います。IDはご自身の検証環境の投稿へ置き換え、通常運用で全投稿を対象にするときはpost__inを外してください。

クラシックテーマの子テーマへtemplate-parts/paginated-posts.phpとして保存します。固定フロントページ以外の一覧用テンプレートで、表示したい場所のPHP処理へget_template_part( ‘template-parts/paginated-posts’ );を追加して呼び出してください。ファイルを保存するだけでは一覧は出ません。WordPress標準のアーカイブそのものを変更する場合は、後のメインクエリの例を使います。

<?php$current_page = max( 1, (int) get_query_var( 'paged', 1 ) ); $list_query = new WP_Query(   [      'post_type'           => 'post',      'post_status'         => 'publish',      'post__in'            => [ 10, 11, 12, 13, 14, 15 ],      'orderby'             => 'post__in',      'posts_per_page'      => 3,      'paged'               => $current_page,      'ignore_sticky_posts' => true,      'no_found_rows'       => false,   ]); if ( $list_query->have_posts() ) {   echo '<ul>';    while ( $list_query->have_posts() ) {      $list_query->the_post();       printf(         '<li><a href="%1$s">%2$s</a></li>',         esc_url( get_permalink() ),         esc_html( get_the_title() )      );   }    echo '</ul>';    $placeholder = '999999999';   $pagination  = paginate_links(      [         'base'      => str_replace(            $placeholder,            '%#%',            get_pagenum_link( $placeholder, false )         ),         'format'    => '?paged=%#%',         'current'   => $current_page,         'total'     => $list_query->max_num_pages,         'type'      => 'list',         'prev_text' => '前へ',         'next_text' => '次へ',      ]   );    if ( $pagination ) {      echo '<nav aria-label="投稿一覧のページ送り">';      echo wp_kses_post( $pagination );      echo '</nav>';   }} else {   echo '<p>表示できる投稿はありません。</p>';} wp_reset_postdata();

新しく作るパーツには、先頭の<?phpも含めて保存します。すでにPHPが始まっている場所へ追加するなら、開始タグは不要です。get_pagenum_link()は現在のパーマリンク設定に合わせたページURLの土台を作ります。第2引数をfalseにし、リンク生成前にはHTML用のエスケープをしません。既存のクエリ文字列がある場合のURL破損を避け、生成後のHTMLをwp_kses_post()で出力します。

paginate_links()は総ページ数が2未満ならnullを返すため、戻り値がある場合だけnavを表示しています。

999999999は実際のページ番号ではありません。ページURLの中でほかの数字と重なりにくい仮の番号として入れ、直後のstr_replace()で%#%へ置き換えます。paginate_links()は、この%#%へ1、2、3のようなページ番号を入れてリンクを作ります。

type=’list’にすると、リンクはulとliを含むリスト形式のHTMLで返ります。wp_kses_post()は、WordPressの記事本文で許可される安全なHTMLだけを残して出力する関数です。この例では、navの開始タグ、ページリンク、終了タグを順にechoし、ページ送り全体を1つのナビゲーションとして表示しています。

独自ループでthe_post()を使った後は、wp_reset_postdata()で後続のテンプレートタグがメイン側の投稿を参照する状態へ戻します。

完成例は本番と分けたWordPress環境で、1ページ目と2ページ目の投稿・URLを比べます。検証や公開に使うサーバーをこれから用意する場合は、XserverのPHP対応やバックアップ条件も確認できます。

posts_per_pageで1ページの表示件数を決める

posts_per_pageは、1ページにつきWP_Queryが取得する投稿数です。3を指定すれば、条件に一致する投稿を最大3件取得します。最終ページは残り件数だけになるため、常に3件とは限りません。

全件表示が必要でも、投稿が増えるページでは-1を安易に使わず、上限を決めます。通常のページ送りを作る記事では、1以上の整数を指定してください。

pagedへ現在ページ番号を渡す

通常のアーカイブや一覧URLでは、get_query_var( ‘paged’, 1 )から現在ページを取得します。1つ目の引数pagedは取得したい値の名前、2つ目の引数1は値がないときの初期値です。1ページ目では0になる構成もあるため、max( 1, … )で1以上にそろえます。

$current_page = max( 1, (int) get_query_var( 'paged', 1 ) ); $args = [   'posts_per_page' => 3,   'paged'          => $current_page,];

これは完成例から現在ページの取得と設定だけを抜き出したコードです。同じテンプレートパーツで取得した$current_pageを、WP_Queryのpagedとpaginate_links()のcurrentの両方へ渡します。取得側とリンク側の値を別々に計算しないことが重要です。

ページリンクのURLが2ページ目になっても、WP_Queryへpagedを渡していなければ取得条件は毎回1ページ目のままです。現在ページは、リンク側より先に取得側へ渡します。

表示件数と現在ページの役割が分かったら、取得条件をWP Query Builderで整理できます。画面で指定したページ番号は固定値なので、実装時はURLから取得した$current_pageへ置き換えます。

found_postsとmax_num_pagesの役割を分ける

WP_Queryの実行後は、post_count、found_posts、max_num_pagesで件数を確認できます。ページリンクのtotalへ渡すのは、総件数ではなく総ページ数です。6件を3件ずつ表示する例で、違いを見てみましょう。

max_num_pagesは、総件数と1ページの件数から計算された結果です。追加した一覧を$list_queryで取得したなら、$list_query->max_num_pagesを使います。グローバル$wp_query->max_num_pagesを使うと、ブラウザで開いているページと追加した一覧の総ページ数が混ざります。

paginate_links()へcurrentとtotalを明示する

paginate_links()にはメインクエリを使う既定値があります。独自WP_Queryでは、現在ページと総ページ数を明示し、どのクエリのリンクかをそろえます。次は完成例のリンク生成部分の抜粋で、$current_pageと$list_queryを作った同じテンプレートパーツ内で使います。

$placeholder = '999999999'; $pagination = paginate_links(   [      'base'      => str_replace(         $placeholder,         '%#%',         get_pagenum_link( $placeholder, false )      ),      'format'    => '?paged=%#%',      'current'   => $current_page,      'total'     => $list_query->max_num_pages,      'type'      => 'list',      'prev_text' => '前へ',      'next_text' => '次へ',   ]);

currentは現在ページ、totalは総ページ数です。typeをlistにするとリスト形式のHTMLが返ります。この抜粋は生成までなので、表示するときは最初の完成例と同じように、戻り値がある場合だけwp_kses_post( $pagination )をechoします。文字列連結そのものが問題なのではなく、HTMLを適切に扱って出力することが重要です。

固定フロントページではpageも確認する

固定フロントページ上のページテンプレートで独自一覧を表示する場合、現在ページ番号がpagedではなくpageへ入る構成があります。WordPress公式のget_query_var()リファレンスも、固定フロントページではpageを使う例を示しています。

$current_page = max( 1, (int) get_query_var( 'page', 1 ) ); $front_query = new WP_Query(   [      'post_type'      => 'post',      'post_status'    => 'publish',      'post__in'       => [ 10, 11, 12, 13, 14, 15 ],      'orderby'        => 'post__in',      'posts_per_page' => 3,      'paged'          => $current_page,      'ignore_sticky_posts' => true,      'no_found_rows'  => false,   ]);

ここではURLからページ番号を読むときにpageを使いますが、追加のWP_Queryへ渡すパラメーター名はpagedです。つまり「WordPressから読む名前」と「WP_Queryへ渡す名前」が異なります。front-page.phpで使う取得部分の例なので、表示ループとページリンクでは変数名を$front_queryへ揃え、リンクのcurrentには同じ$current_pageを渡します。トップページだけ2ページ目が同じになる場合は、「設定 → 表示設定」で固定フロントページかを確認し、pagedとpageの値をローカルで比べます。

既存のアーカイブ一覧は作り直さない

カテゴリー、検索、投稿タイプアーカイブなど、WordPressが元から用意する一覧そのものを変えたい場合は、テンプレートで同じ投稿を独自WP_Queryし直す前に、メインクエリの変更を検討します。

対象を限定したpre_get_postsでposts_per_pageを変更すれば、同じメインクエリのfound_postsとmax_num_pagesが更新されます。テーマのページネーションもメインクエリへつながるため、独自の現在ページと総ページ数を別管理せずに済むことがあります。次はアーカイブを有効にした投稿タイプnewsが登録済みの場合の例で、子テーマのfunctions.phpまたは専用プラグインへ1回だけ置きます。

function wptl_change_news_archive_count( WP_Query $query ) {   if ( is_admin() || ! $query->is_main_query() ) {      return;   }    if ( $query->is_post_type_archive( 'news' ) ) {      $query->set( 'posts_per_page', 12 );   }}add_action( 'pre_get_posts', 'wptl_change_news_archive_count' );

add_action()は、WordPressがpre_get_postsを実行したときに、wptl_change_news_archive_count()を呼ぶための登録です。関数の中で、管理画面ではない、メインクエリである、newsアーカイブである、という順に対象を絞っています。

この例では、テンプレート側の通常ループとページリンクをそのまま使います。追加した一覧を作る目的なら、最初の追加WP_Queryの完成例を使います。

正常なページ送りでは3つの指定を避ける

総ページ数を使って数字のリンクを出す場合、次の3つを加えるとページ送りが崩れる原因になります。最初の完成例では使わず、必要になったときに右の各記事で条件を確認してください。

no_found_rows=trueは、総件数を数える処理を省いて軽くする指定です。その代わり、通常のmax_num_pagesを計算できないため、ページ送りが必要な一覧では使いません。

WP Query Builderでは取得条件を作り、ページ番号とリンクはテンプレートでつなぐ

WP Query Builderでは、投稿タイプ、表示件数、並び順、絞り込みなど、WP_Queryへ渡す$argsを整理できます。ページネーションを使う場合は、総ページ数が必要なのでno_found_rowsを有効にしない構成を確認します。

現在URLからページ番号を読む処理、固定フロントページのpage判定、paginate_links()のHTML出力はテンプレート側で追加します。Builderで生成した$argsへpagedを渡し、同じクエリのmax_num_pagesをリンクへつなぎます。

Builderの画面操作は公式チュートリアルで詳しく説明しています。この記事では、生成後のコードとページリンクをWordPress側でつなぐ部分を扱います。

同じ6件で投稿と現在ページの切り替わりを比べる

6件の記事を3件ずつ表示すると、1ページ目は最初の3件、2ページ目は残りの3件になります。投稿の内容だけでなく、ページ番号の現在位置も一緒に切り替わるかを見てください。次の値と画面は、本文と同じ6件をローカルのWordPress 7.1／PHP 8.4.20で表示したものです。

まず1ページ目には、最初の3件が出ます。番号の「1」が現在位置です。

「2」のリンクを開くと、次の3件へ進み、現在位置も「2」へ移ります。

同じ総件数と総ページ数を保ちながら、ページごとの投稿IDが次の3件へ切り替わります。paginate_links()へcurrent=2とtotal=2を渡すと、現在ページ2のaria-currentを含むHTMLが生成されます。2枚は同じサイトの1ページ目と2ページ目を、それぞれ撮影したものです。検証環境では専用のURL変数fixture_pageでページを切り替えていますが、本文コードへその名前を追加する必要はありません。

固定フロントページについては、公式仕様に従いpageを取得元とするコードを分離しました。実サイトでは表示設定を確認し、対象トップページでpageとpagedの実値を記録してください。

実装後は最後のページまで確認する

変更範囲を広げる前に、次の順番で原因を絞ります。

記事の追加や削除で最終ページは変わります。テスト用の固定件数だけでなく、0件、1ページだけ、2ページ以上、最終ページが端数になる条件を確認してください。

設定時によくある間違い

実装や公開へ進む前に、見落としやすい項目をまとめて確認します。

リンクが出ない、2ページ目が同じ、404になるなどの症状がすでにある場合は、WP_Queryでページネーションが動かない原因で症状別に確認します。表示件数だけが合わない場合は、posts_per_pageの確認方法もご覧ください。

あわせて読みたいWP_Queryの基本的な書き方記事を読む

あわせて読みたいWP_Queryでページネーションが動かない原因記事を読む

あわせて読みたいWP_Queryの表示件数が合わない原因記事を読む

あわせて読みたいoffsetとページネーションを併用すると件数がずれる理由記事を読む

あわせて読みたいWP Query Builderでページ送りを作る方法記事を読む

あわせて読みたいposts_per_page=-1が重くなる理由記事を読む

WP_Queryとpaginate_links()の公式資料

posts_per_pageとpagedで取得する範囲、max_num_pagesと現在ページをpaginate_links()へ渡す方法は、次の公式資料で確認できます。

リンクと投稿の両方が切り替わるか確かめる

リンクを押してURLが変わるだけでなく、表示される投稿と現在ページの番号も変われば、取得側とリンク側がつながっています。投稿が少ない場合や増減した場合も、最後のページまで確かめてから本番へ反映しましょう。