在開發網頁時，當資料量變大時，將所有資料一次性載入會影響效能與使用者體驗。因此，Laravel 提供了強大的 分頁 (Pagination) 功能，讓我們能夠輕鬆地分批顯示資料。

本文將介紹：

  1. Laravel 基本分頁
  2. 簡單分頁 (simplePaginate())
  3. 游標分頁 (cursorPaginate())
  4. 在 Controller 中使用分頁
  5. 在 Blade 模板中顯示分頁
  6. API 回傳分頁 JSON
  7. 自訂分頁樣式（Bootstrap 5）
  8. 快取分頁結果提升效能

1. Laravel 基本分頁 (paginate())

Laravel 提供的 paginate() 方法會自動處理 SQL LIMIT 查詢，讓你輕鬆取得分頁資料。

使用範例

use App\Models\User;

$users = User::paginate(10); // 每頁顯示 10 筆資料

這會產生對應的 SQL：

 SELECT * FROM users LIMIT 10 OFFSET 0;

當你瀏覽 ?page=2 時，SQL 會自動變為：

SELECT * FROM users LIMIT 10 OFFSET 10;

 

2. 簡單分頁 (simplePaginate())

如果你的資料量非常大，並且不需要顯示「總頁數」，你可以使用 simplePaginate()，這樣 Laravel 不會執行 COUNT(*) 查詢，效能更佳。

$users = User::simplePaginate(10);

此方法只提供「上一頁」和「下一頁」的按鈕，沒有頁碼顯示，適合大數據網頁。 

 

3. 游標分頁 (cursorPaginate())

cursorPaginate() 是 Laravel 8 之後的新功能，適用於資料量龐大時，它不使用 OFFSET，而是根據「游標」來獲取資料。

使用範例

$users = User::orderBy('id')->cursorPaginate(10);

游標分頁比 paginate() 和 simplePaginate() 更有效率，適合需要不斷載入新資料的結構，如無限滾動（Infinite Scroll）。 

 

4. 在 Controller 中使用分頁

我們可以將分頁邏輯放入 Controller，然後傳遞到 View。

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;

class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate(10);
        return view('users.index', compact('users'));
    }
}

路由設定

在 routes/web.php 中定義路由：

use App\Http\Controllers\UserController;

Route::get('/users', [UserController::class, 'index'])->name('users.index');

5. 在 Blade 模板中顯示分頁

在 resources/views/users/index.blade.php 中顯示分頁結果：

Blade 分頁

<table class="table">
    <thead>
        <tr>
            <th>ID</th>
            <th>名稱</th>
            <th>Email</th>
        </tr>
    </thead>
    <tbody>
        @foreach ($users as $user)
            <tr>
                <td>{{ $user->id }}</td>
                <td>{{ $user->name }}</td>
                <td>{{ $user->email }}</td>
            </tr>
        @endforeach
    </tbody>
</table>

<!-- 分頁按鈕 -->
<div class="d-flex justify-content-center">
    {{ $users->links() }}
</div>

這樣就可以顯示分頁按鈕，並且 Laravel 會自動偵測 ?page= 參數。

 

6. API 回傳分頁 JSON

如果你的網頁是 API，可以直接回傳 JSON 格式：

return User::paginate(10);

這會產生 JSON 結果：

{
    "current_page": 1,
    "data": [...],
    "first_page_url": "...",
    "last_page_url": "...",
    "next_page_url": "...",
    "prev_page_url": "...",
    "per_page": 10,
    "total": 100,
    "last_page": 10
}

 

7. 自訂分頁樣式（Bootstrap 5）

Laravel 預設使用 Tailwind CSS，但如果你想使用 Bootstrap 5，可以在 AppServiceProvider.php 中設定：

use Illuminate\Pagination\Paginator;

public function boot()
{
    Paginator::useBootstrapFive();
}
 

這樣 {{ $users->links() }} 產生的 HTML 會自動適配 Bootstrap 5 樣式！

 

8. 快取分頁結果提升效能

如果你的資料變動不頻繁，可以使用 快取 (Cache) 來減少資料庫查詢：

use Illuminate\Support\Facades\Cache;

public static function getCachedPaginate()
{
    $page = request()->input('page', 1);

    return Cache::remember("users_paginate_{$page}", 3600, function () {
        return self::orderBy('updated_at', 'desc')->paginate(10);
    });
}

這樣，每個頁數的查詢結果會快取 1 小時 (3600 秒)，大幅減少資料庫負擔。 

以上就是 Laravel 在快速製作分頁按鈕上的教學。