WP_Query パラメーターoffset

offset は、「最初の記事だけ大きく表示して、残りを通常一覧に出したい」といった場面で使いたくなる引数です。考え方自体は分かりやすく、先頭から何件スキップするかを数値で指定します。

ただし、offset はページネーションと組み合わせる時に注意が必要です。1ページ目だけを見ていると正しく動いているように見えても、2ページ目以降で投稿の続き方や件数がずれることがあります。

offset は何を指定する引数か

offset は、取得結果の先頭から何件飛ばすかを指定する WP_Query の引数です。offset に 0 を指定すれば先頭から取得し、1 を指定すれば1件飛ばし、3 を指定すれば3件飛ばしてから取得します。

たとえば、公開済みの通常投稿を日付順で取得する場合、offset に 1 を指定すると、最新の1件を飛ばして2件目以降から取得します。posts_per_page と組み合わせることで、「1件飛ばして、その次から3件取得する」のような指定ができます。

ここで大事なのは、offset は「除外したい投稿を指定する引数」ではないことです。特定の投稿IDを除外するのではなく、並び順の先頭から指定件数だけ機械的に飛ばします。

そのため、並び順が変わると、飛ばされる投稿も変わります。日付順、ランダム順、メニュー順など、orderby の指定によって offset の結果も変わる点に注意します。

offset、paged、posts_per_page、post__not_in の違い

offset は、表示件数やページ送りに関係する他の引数と混同しやすいです。特に paged、posts_per_page、post__not_in とは役割を分けて理解しておく必要があります。

posts_per_page は1ページあたりの取得件数、paged は現在のページ番号、offset は先頭から飛ばす件数です。post__not_in は、指定した投稿IDを除外するための引数です。

たとえば「最新記事1件だけを別枠で出したので、その同じ記事を下の一覧に出したくない」という目的なら、offset よりも post__not_in のほうが意図に合うことがあります。

一方で、「並び順の先頭から必ず3件飛ばす」という目的が明確で、ページネーションも使わないなら、offset が分かりやすい場合もあります。目的によって使い分けます。

Builder での扱い

WP Query Builder では、offset は注意付きの高度な引数として扱うのが安全です。初心者が最初から使う基本引数というより、「先頭から何件か飛ばしたい」という目的がはっきりしている時にだけ選ぶ項目です。

特にページネーションを有効にしている場合は、Builder 側で注意文を出すと親切です。offset を使うと、2ページ目以降の表示や総ページ数が想定とずれる可能性があるためです。

Builder では、offset を入力できるようにする場合でも、初期状態では空欄にしておくのが分かりやすいです。必要がある時だけ数値を入れる形にすると、意図しないズレを減らせます。

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

先頭の一定件数を一度だけ除外するなど、固定位置から取得を始める要件に使います。

通常のページ送りでは paged と競合しやすいため、単純に併用しません。

2ページ目以降も同じ offset が作用すると欠落や重複が生じるため、ページ番号を含む計算式が必要か判断します。

先頭3件を除外する処理を各ページへそのまま当てると欠落するため、1ページ目だけか全ページ共通かを先に決めます。

連番の投稿IDを持つテスト投稿で1〜3ページの表示IDを記録し、全IDが重複・欠落なく一度ずつ現れるか確かめます。

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

offset と paged の組み合わせでページ送りがずれる原因を、確認順とともに追えます。

記事を読む →

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

公式資料では、WP_Query の offset は Pagination Parameters の中で確認できます。posts_per_page、paged など、ページ送りに関係する引数と合わせて見ると理解しやすくなります。

ページネーション付き一覧で使う場合は、現在ページ番号を取得する get_query_var() や、ページ番号リンクを作る paginate_links() も一緒に確認します。offset だけを見ても、ページ送り全体の挙動は判断しにくいためです。

offset は、先頭から指定件数を飛ばすための引数です。小さな一覧では便利ですが、ページネーション付き一覧では件数やページ送りがずれやすいため、使う前に目的を確認します。

「先頭から何件飛ばしたい」のか、「特定の記事を除外したい」のかで選ぶ方法は変わります。特定の記事を除外したい場合は、post__not_in のように投稿IDを指定する方法も検討します。