WP_Query 用語pagination

pagination は、日本語ではページネーションやページ送りと呼ばれます。記事一覧が50件ある時に、1ページに10件ずつ表示し、1ページ目、2ページ目、3ページ目へ移動できるようにする仕組みです。

WordPress では、pagination は単にリンクを出せば完成するものではありません。取得側の WP_Query が現在ページを理解していること、表示側のページリンクが正しい総ページ数を使っていること、そして main query と custom query のどちらを扱っているかを分けることが重要です。

pagination は何を指す言葉か

pagination は、投稿一覧を複数ページに分割して表示する仕組みです。1ページに表示する件数を決め、現在のページ番号に応じて取得する投稿を切り替えます。

たとえば、1ページに10件表示する一覧で、2ページ目では11件目から20件目を表示します。この切り替えに関係するのが posts_per_page と paged です。

ここで大事なのは、posts_per_page だけではページ送りにならないことです。1ページあたりの件数を決めるだけで、現在ページの指定やページリンクの生成は別に必要です。

逆に、ページリンクだけを出しても、WP_Query に paged が渡っていなければ、2ページ目でも1ページ目と同じ投稿が出ることがあります。

posts_per_page と paged の関係

posts_per_page は、1ページに何件表示するかを指定する引数です。paged は、現在何ページ目かを指定する引数です。この2つをセットで考えると、pagination の基本が理解しやすくなります。

たとえば posts_per_page => 10 で paged => 2 なら、2ページ目にあたる投稿を取得する意図になります。paged が正しく渡らないと、2ページ目以降の表示が崩れます。

main query では、WordPress が現在ページを扱ってくれる場面があります。一方、custom query では、開発者が get_query_var( ‘paged’ ) などで現在ページを取得し、WP_Query の paged に渡す必要があります。

pagination の不具合では、まず posts_per_page と paged を確認します。表示件数が合わない場合は件数、2ページ目以降がおかしい場合は paged が原因候補になります。

Builder での扱い

WP Query Builder では、pagination は「ページ送りを有効にするかどうか」の設定として扱う想定です。有効にする場合は、posts_per_page、paged、ページリンク生成までをセットで出力します。

初心者向けには、「1ページあたりの件数」と「ページ送りを表示する」を分けると分かりやすくなります。件数だけを変えるのか、ページリンクまで必要なのかを先に選ばせます。

また、main query を調整するのか、custom query を生成するのかも分ける必要があります。既存アーカイブのページ送りと、追加の独自一覧のページ送りでは、扱うクエリが違います。

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

投稿一覧を複数ページへ分け、現在ページに対応する投稿集合と移動リンクを提供する時に使う仕組みです。

「もっと見る」の非同期追加や単一ページ内の表示切替を、同じ実装だと決めつけません。

取得件数、現在ページ、総ページ数、リンクURLは別々の値なので、一箇所の修正だけで直るとは限りません。

投稿の取得、総ページ数の計算、リンク生成の三つを分けて確認すると、直す場所を誤りません。

全投稿数、posts_per_page、paged、max_num_pages、各ページの投稿ID、リンク先URLを同じ台帳へ記録します。

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

ページ送りが動かない時に、取得・総数・リンクのどこでずれたかを順番に確認できます。

記事を読む →

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

公式資料では、WP_Query Class で posts_per_page や paged などの引数を確認できます。現在ページ番号を取得する場合は、get_query_var() を確認します。

ページリンクの生成には paginate_links() の公式リファレンスを確認します。取得側とリンク生成側を分けて読むと、pagination の流れが理解しやすくなります。

pagination は、投稿一覧を複数ページに分けて表示する仕組みです。posts_per_page で件数を決め、paged で現在ページを渡し、総ページ数をもとにページリンクを生成します。

迷った時は、custom query なのか main query なのかを分けます。custom query なら get_query_var( ‘paged’ )、$args[‘paged’]、$query->max_num_pages を順番に確認します。