Laravel 分頁方法與使用時機

發表於 所需閱讀時間 ≈ 2 分鐘

Laravel Page 種類與使用時機

Laravel Page 種類與使用時機

📦 Laravel 方法總結

方法 用法範例 說明
paginate User::paginate(15) 傳統 OFFSET 分頁，使用的是 OFFSET 分頁，查得越後面效能越差
simplePaginate User::simplePaginate(15) paginate 簡化版，無 total、last_page
cursorPaginate User::orderBy(‘id’)->cursorPaginate(15) infinite scroll，大量資料，支援無限滾動， 都是基於主鍵進行篩選，不使用 OFFSET，效能穩定適合大量資料

📦 API Response 格式差異

方法 回傳欄位（部分） 備註
paginate data, total, current_page, last_page 完整資訊，適合 UI 跳頁
simplePaginate data, current_page, next_page_url 效能佳，少欄位
cursorPaginate data, per_page, next_cursor base64 游標，適合 infinite scroll

✅ paginate() 回傳格式範例：

1
2
3
4
5
6
7
8
9
{
  "data": [ { "id": 1, "name": "Alice" }, ... ],
  "current_page": 1,
  "last_page": 5,
  "per_page": 15,
  "total": 63,
  "next_page_url": "https://example.com/api/users?page=2",
  "prev_page_url": null
}

適合需要「總筆數、跳頁 UI、前/後頁按鈕」的使用場景。

✅ simplePaginate() 回傳格式範例：

1
2
3
4
5
6
7
{
  "data": [ { "id": 1, "name": "Alice" }, ... ],
  "current_page": 1,
  "per_page": 15,
  "next_page_url": "https://example.com/api/users?page=2",
  "prev_page_url": null
}

適合列表只需簡單「下一頁」功能，不需顯示頁數或總筆數，查詢速度較好。

✅ cursorPaginate() 回傳格式範例：

1
2
3
4
5
6
{
  "data": [ { "id": 101, "name": "Alice" }, ... ],
  "per_page": 15,
  "next_cursor": "eyJpZCI6MTE1fQ==",
  "prev_cursor": null
}

適合 infinite scroll，next_cursor 為游標 base64 編碼，請求下一頁時帶入 ?cursor=eyJpZCI6MTE1fQ==。

SQL 對照

以下為各種分頁背後的 SQL 執行邏輯（簡化範例）：

1
2
3
4
5
6
7
8
9
-- paginate
SELECT * FROM users LIMIT 15 OFFSET 0;
SELECT COUNT(*) AS aggregate FROM users;

-- simplePaginate
SELECT * FROM users LIMIT 15 OFFSET 0 

-- cursorPaginate
SELECT * FROM users WHERE id > 0 ORDER BY id ASC LIMIT 15;