WP_Query 実装用語paginate_links()

paginate_links() は、1、2、3、次へ、前へ、のようなページ番号リンクを生成するために使います。投稿一覧を複数ページに分けたい時に関係する関数です。

初心者がつまずきやすいのは、paginate_links() は「リンクを作る関数」であって、「投稿取得をページごとに切り替える関数」ではないという点です。取得側では WP_Query の paged、表示側では paginate_links() の current と total を確認します。

paginate_links() は何をする関数か

paginate_links() は、ページネーション用のリンクを生成する関数です。現在ページ、総ページ数、リンクの形式などをもとに、ページ番号リンクを作ります。

たとえば、投稿一覧が5ページある場合に、1、2、3、4、5 のようなリンクを表示するために使います。前後リンクや省略表示も、指定内容によって調整できます。

ここで大事なのは、paginate_links() と WP_Query の役割を分けることです。WP_Query はどの投稿を取得するかを決め、paginate_links() はページ移動用のリンクを作ります。

つまり、ページ番号リンクが表示されていても、WP_Query に paged が渡っていなければ、2ページ目で同じ投稿が表示されることがあります。

$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1; $args = [   'post_type'      => 'post',   'post_status'    => 'publish',   'posts_per_page' => 10,   'paged'          => $paged,]; $query = new WP_Query( $args ); if ( $query->have_posts() ) {   while ( $query->have_posts() ) {      $query->the_post();       the_title( '<h2>', '</h2>' );   }} echo paginate_links( [   'current' => $paged,   'total'   => $query->max_num_pages,] ); wp_reset_postdata();

current と total に何を渡すか

paginate_links() で特に重要なのが、current と total です。current は現在ページ、total は総ページ数です。

この2つがずれると、現在ページの表示が合わない、ページリンクが足りない、存在しないページへのリンクが出る、といった問題が起きます。

custom query の場合は、main query の総ページ数ではなく、その custom query の max_num_pages を使います。ここを混同すると、リンク数と実際の取得結果がずれやすくなります。

main query の通常アーカイブで使う場合は、グローバルなクエリの総ページ数を使うことがあります。どのクエリのページ送りなのかを先に分けます。

Builder での扱い

WP Query Builder では、paginate_links() は pagination を有効にした時のリンク生成部分として扱う想定です。posts_per_page と paged だけでなく、リンク生成の current と total まで出力する必要があります。

初心者向けには、ページ送りを有効にした場合に何が増えるのかを明確に見せると分かりやすくなります。取得条件に paged が追加され、表示部分に paginate_links() が追加されます。

また、main query 用のページネーションなのか、custom query 用のページネーションなのかを分ける必要があります。custom query では $query->max_num_pages を使う点を明確にします。

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

現在ページと総ページ数が確定した後に、一覧のページ番号リンクを出力する時に使います。

WP_Queryの取得条件や総ページ数を計算する関数としては扱いません。

current、total、base のどれかが現在URLと合わないと、見た目は出ても遷移先が誤ります。

リンクが表示されるだけでは不十分で、押した先のURLと投稿集合まで合って初めてページ送りとして成立します。

先頭・中間・最終ページで現在表示、前後リンク、各リンク先URL、遷移後に表示された投稿IDを一組として確認します。

実践記事で確認WP_Queryでページネーションがうまく動かない原因

クエリ側の paged からリンク側の current・total まで、ページ送り全体の確認手順を追えます。

記事を読む →

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

公式資料では、paginate_links() のリファレンスで、ページリンク生成に使える引数を確認できます。WP_Query のリファレンスでは、paged や max_num_pages と関係する取得側の考え方を確認できます。

現在ページ番号を取得する場合は、get_query_var() も合わせて確認します。取得側とリンク生成側を分けて読むと、ページネーションの全体像が理解しやすくなります。

paginate_links() は、ページ番号リンクを生成するための関数です。投稿の取得をページごとに切り替えるには、WP_Query 側で paged を正しく渡す必要があります。

迷った時は、現在ページ、総ページ数、取得条件を分けて確認します。custom query では、current に $paged、total に $query->max_num_pages を渡す形をまず確認します。