> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ページネーションの扱い方

> スクレイパーが1ページ目で止まらないために、番号付きページ、Nextリンク、無限スクロール、Load More、APIのoffset/カーソルをどう検出し処理するかを解説します。

ページネーションはスクレイパーの「遷移」レイヤーです。1ページからデータを抽出できても、次のデータ群がどこにあり、どこで止めるべきかを判断できなければ、収集はすぐに不完全になります。

まずUIではなくリクエストを見ます。DevToolsのNetworkタブを開き、Nextボタンを押す、下までスクロールする、Load Moreをクリックするなど、実際に次のデータを読み込ませます。URL、query parameter、request body、responseを確認し、リンクを辿るべきか、ブラウザ操作を再現すべきか、APIを直接呼べるかを判断します。

| 変化                                        | 最初に試すこと                     |
| ----------------------------------------- | --------------------------- |
| URLに`page=2`や`/page/2`が出る                 | 番号付きURLをループする               |
| `<a>`のNextリンクがある                          | `href`を辿り、消える/無効になるまで続ける    |
| スクロールで新しい項目が出る                            | XHR/APIを探し、必要ならブラウザでスクロールする |
| ボタンで項目が追加される                              | APIを再利用するか、ボタンをクリックする       |
| JSONに`next_cursor`、`has_more`、`offset`がある | APIレスポンスのページ情報で進める          |

## 番号付きページ

もっとも単純な形式です。

```text theme={null}
https://example.com/products?page=1
https://example.com/products?page=2
https://example.com/catalog/page/3
```

スクレイパーはページ番号を増やし、項目が0件になった、期待件数より少なくなった、404や空状態になった時点で止めます。注意すべき点は、`page=0`から始まるサイト、`p`や`start`など別名のパラメータ、範囲外ページで1ページ目を返すサイトです。最後のケースは重複を生むため、URLだけでなく項目IDや商品URLも見て停止条件を作ります。

## Nextリンク

番号がなく、Nextや矢印だけがあるサイトもあります。通常の`<a>`であればリンクを辿るだけです。最後のページでNextが消える場合もあれば、`disabled`や`aria-disabled="true"`になる場合もあります。要素の存在だけでなく無効状態を確認します。

URLの循環にも注意します。最後のNextが同じページや1ページ目を指すサイトでは、訪問済みURLの集合を持たないと無限ループになります。

## 無限スクロール

無限スクロールはブラウザ操作が必要に見えますが、多くの場合は裏側でAPIを呼んでいます。スクロール時にNetworkタブで`offset`、`cursor`、`after`、`page`などを含むリクエストを探します。

APIが直接呼べるなら、ブラウザを動かすより高速で安定します。認証、署名付きパラメータ、複雑なクライアント状態がある場合だけ、PlaywrightやPuppeteerのようなブラウザ自動化でスクロールを再現します。停止条件はページ高さだけに頼らず、項目数、network idle、最大スクロール回数を組み合わせる方が安全です。

## Load Moreボタン

Load Moreは制御された無限スクロールです。クリックごとに次のまとまりが追加されるため、スクロールよりもペースを調整しやすいのが利点です。

重要なのは「クリックできた」ではなく「新しい項目が増えた」ことを確認することです。ボタンは最後まで表示されたまま無効になることがあり、クリックが失敗してもエラーにならない場合があります。

## offsetとカーソルAPI

APIベースのページネーションには大きく2種類あります。offset方式は`/api/products?offset=40&limit=20`のように位置を数値で指定します。カーソル方式は前回レスポンスに含まれる`endCursor`や`next_cursor`を次回リクエストに渡します。

動的なデータではカーソル方式の方が安定します。番号やoffsetは途中でデータが追加/削除されると重複や取りこぼしが起きますが、カーソルは「この位置の続き」を指すためです。

## 複合パターン

現実のサイトでは複数の方式が混ざります。

* 番号付きページの各ページ内でさらに無限スクロールする
* 最初はLoad Moreで、途中から番号付きページになる
* New/Popular/Saleなどタブごとに独立したページネーションがある
* 一覧ページをページングし、詳細ページ内のレビューも別にページングする

この場合はネストしたループとして設計します。外側はカテゴリやページ、内側はスクロールやレビューのように責任を分け、全体で一意IDを追跡して重複を防ぎます。

## 実務上のガード

* 停止条件を必ず定義する
* 重複IDやURLを記録する
* 固定sleepだけでなく、項目数やDOM変化を待つ
* 失敗したURLやカーソルをログに残す
* APIが正当に使えるならブラウザ操作より優先する
* Octoparseのようなビジュアルツールでは、Nextページ、Load More、無限スクロールを設定し、ローカルまたはクラウドで実行できる

ページネーションは単なる「次へ」ではなく、スクレイパーの制御ループです。次に進む条件、止まる条件、重複を防ぐ仕組みが揃って初めて、1ページ目だけで終わらない収集になります。