分頁 (Pagination)

簡介 (Introduction)

在其他框架中，分頁可能非常痛苦。我們希望 Laravel 的分頁方法能讓您耳目一新。Laravel 的分頁器與查詢建構器和 Eloquent ORM 整合，提供便利、易於使用的資料庫記錄分頁功能，無需任何配置。

預設情況下，分頁器產生的 HTML 與 Tailwind CSS 框架相容；不過，也提供 Bootstrap 分頁支援。

Tailwind

如果您使用 Laravel 預設的 Tailwind 分頁視圖搭配 Tailwind 4.x，您的應用程式的 resources/css/app.css 檔案已經正確配置為 @source Laravel 的分頁視圖：

@import "tailwindcss";

@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';

基本使用 (Basic Usage)

分頁查詢建構器結果 (Paginating Query Builder Results)

有幾種方法可以分頁項目。最簡單的方法是在查詢建構器或 Eloquent 查詢上使用 paginate 方法。paginate 方法會根據使用者目前檢視的頁面自動設定查詢的「limit」和「offset」。預設情況下，目前頁面是透過 HTTP 請求中 page 查詢字串參數的值來偵測的。此值由 Laravel 自動偵測，並且也會自動插入到分頁器產生的連結中。

在此範例中，傳遞給 paginate 方法的唯一參數是您希望「每頁」顯示的項目數量。在這種情況下，讓我們指定我們希望每頁顯示 15 個項目：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show all application users.
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

簡單分頁 (Simple Pagination)

paginate 方法會在從資料庫取得記錄之前計算查詢匹配的記錄總數。這樣分頁器就知道總共有多少頁的記錄。然而，如果您不打算在應用程式的 UI 中顯示總頁數，則記錄計數查詢是不必要的。

因此，如果您只需要在應用程式的 UI 中顯示簡單的「下一頁」和「上一頁」連結，您可以使用 simplePaginate 方法來執行單一、高效的查詢：

$users = DB::table('users')->simplePaginate(15);

分頁 Eloquent 結果 (Paginating Eloquent Results)

您也可以分頁 Eloquent 查詢。在此範例中，我們將分頁 App\Models\User 模型並指出我們計劃每頁顯示 15 條記錄。如您所見，語法與分頁查詢建構器結果幾乎相同：

use App\Models\User;

$users = User::paginate(15);

當然，您可以在設定查詢的其他約束（例如 where 子句）之後呼叫 paginate 方法：

$users = User::where('votes', '>', 100)->paginate(15);

您也可以在分頁 Eloquent 模型時使用 simplePaginate 方法：

$users = User::where('votes', '>', 100)->simplePaginate(15);

同樣地，您可以使用 cursorPaginate 方法對 Eloquent 模型進行游標分頁：

$users = User::where('votes', '>', 100)->cursorPaginate(15);

每頁多個分頁器實例 (Multiple Paginator Instances per Page)

有時您可能需要在應用程式渲染的單一畫面上渲染兩個獨立的分頁器。然而，如果兩個分頁器實例都使用 page 查詢字串參數來儲存目前頁面，則兩個分頁器會發生衝突。若要解決此衝突，您可以透過提供給 paginate、simplePaginate 和 cursorPaginate 方法的第三個參數傳遞您希望用來儲存分頁器目前頁面的查詢字串參數名稱：

use App\Models\User;

$users = User::where('votes', '>', 100)->paginate(
    $perPage = 15, $columns = ['*'], $pageName = 'users'
);

游標分頁 (Cursor Pagination)

雖然 paginate 和 simplePaginate 使用 SQL「offset」子句建立查詢，但游標分頁透過建構「where」子句來比較查詢中包含的排序欄位的值，在 Laravel 的所有分頁方法中提供最高效的資料庫效能。這種分頁方法特別適合大型資料集和「無限」捲動使用者介面。

與基於偏移的分頁（在分頁器產生的 URL 查詢字串中包含頁碼）不同，基於游標的分頁會在查詢字串中放置一個「游標」字串。游標是一個編碼字串，包含下一個分頁查詢應該開始分頁的位置以及應該分頁的方向：

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

您可以透過查詢建構器提供的 cursorPaginate 方法建立基於游標的分頁器實例。此方法回傳 Illuminate\Pagination\CursorPaginator 的實例：

$users = DB::table('users')->orderBy('id')->cursorPaginate(15);

取得游標分頁器實例後，您可以像使用 paginate 和 simplePaginate 方法時一樣顯示分頁結果。有關游標分頁器提供的實例方法的更多資訊，請查閱游標分頁器實例方法文件。

[!WARNING] 您的查詢必須包含「order by」子句才能利用游標分頁。此外，查詢排序的欄位必須屬於您正在分頁的資料表。

游標分頁 vs. 偏移分頁 (Cursor vs. Offset Pagination)

為了說明偏移分頁和游標分頁之間的差異，讓我們來檢視一些範例 SQL 查詢。以下兩個查詢都會顯示依 id 排序的 users 資料表結果的「第二頁」：

# 偏移分頁...
select * from users order by id asc limit 15 offset 15;

# 游標分頁...
select * from users where id > 15 order by id asc limit 15;

與偏移分頁相比，游標分頁查詢具有以下優勢：

• 對於大型資料集，如果「order by」欄位已建立索引，游標分頁將提供更好的效能。這是因為「offset」子句會掃描所有先前匹配的資料。
• 對於經常寫入的資料集，如果使用者目前檢視的頁面最近新增或刪除了結果，偏移分頁可能會跳過記錄或顯示重複項目。

然而，游標分頁有以下限制：

• 與 simplePaginate 一樣，游標分頁只能用於顯示「下一頁」和「上一頁」連結，不支援產生帶有頁碼的連結。
• 它要求排序至少基於一個唯一欄位或唯一欄位的組合。不支援含有 null 值的欄位。
• 只有在「order by」子句中的查詢表達式已設定別名並新增到「select」子句時才支援。
• 不支援帶有參數的查詢表達式。

手動建立分頁器 (Manually Creating a Paginator)

有時您可能希望手動建立分頁實例，傳遞您已在記憶體中擁有的項目陣列。您可以根據需求建立 Illuminate\Pagination\Paginator、Illuminate\Pagination\LengthAwarePaginator 或 Illuminate\Pagination\CursorPaginator 實例。

Paginator 和 CursorPaginator 類別不需要知道結果集中的項目總數；然而，因此這些類別沒有取得最後一頁索引的方法。LengthAwarePaginator 接受與 Paginator 幾乎相同的參數；但是，它需要結果集中項目的總數計數。

換句話說，Paginator 對應於查詢建構器上的 simplePaginate 方法，CursorPaginator 對應於 cursorPaginate 方法，而 LengthAwarePaginator 對應於 paginate 方法。

[!WARNING] 手動建立分頁器實例時，您應該手動「切片」傳遞給分頁器的結果陣列。如果您不確定如何執行此操作，請查看 array_slice PHP 函式。

自訂分頁 URL (Customizing Pagination URLs)

預設情況下，分頁器產生的連結會匹配目前請求的 URI。然而，分頁器的 withPath 方法允許您自訂分頁器產生連結時使用的 URI。例如，如果您希望分頁器產生類似 http://example.com/admin/users?page=N 的連結，您應該將 /admin/users 傳遞給 withPath 方法：

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->withPath('/admin/users');

    // ...
});

附加查詢字串值 (Appending Query String Values)

您可以使用 appends 方法附加到分頁連結的查詢字串。例如，若要將 sort=votes 附加到每個分頁連結，您應該對 appends 進行以下呼叫：

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->appends(['sort' => 'votes']);

    // ...
});

如果您希望將目前請求的所有查詢字串值附加到分頁連結，您可以使用 withQueryString 方法：

$users = User::paginate(15)->withQueryString();

附加雜湊片段 (Appending Hash Fragments)

如果您需要將「雜湊片段」附加到分頁器產生的 URL，您可以使用 fragment 方法。例如，若要將 #users 附加到每個分頁連結的結尾，您應該如此呼叫 fragment 方法：

$users = User::paginate(15)->fragment('users');

顯示分頁結果 (Displaying Pagination Results)

呼叫 paginate 方法時，您將收到 Illuminate\Pagination\LengthAwarePaginator 的實例，而呼叫 simplePaginate 方法則回傳 Illuminate\Pagination\Paginator 的實例。最後，呼叫 cursorPaginate 方法會回傳 Illuminate\Pagination\CursorPaginator 的實例。

這些物件提供了多種描述結果集的方法。除了這些輔助方法外，分頁器實例是迭代器，可以像陣列一樣循環。因此，一旦取得結果，您可以使用 Blade 顯示結果並渲染頁面連結：

<div className="container">
    @foreach ($users as $user)
        {{ $user->name }}
    @endforeach
</div>

{{ $users->links() }}

links 方法會渲染結果集中其餘頁面的連結。這些連結中的每一個都已經包含正確的 page 查詢字串變數。請記住，links 方法產生的 HTML 與 Tailwind CSS 框架相容。

調整分頁連結視窗 (Adjusting the Pagination Link Window)

當分頁器顯示分頁連結時，會顯示目前頁碼以及目前頁面前後三頁的連結。使用 onEachSide 方法，您可以控制在分頁器產生的中間滑動連結視窗中，目前頁面每側顯示多少個額外連結：

{{ $users->onEachSide(5)->links() }}

將結果轉換為 JSON (Converting Results to JSON)

Laravel 分頁器類別實作了 Illuminate\Contracts\Support\Jsonable 介面合約並公開 toJson 方法，因此將分頁結果轉換為 JSON 非常簡單。您也可以透過從路由或 Controller 動作回傳分頁器實例來將其轉換為 JSON：

use App\Models\User;

Route::get('/users', function () {
    return User::paginate();
});

分頁器的 JSON 會包含 total、current_page、last_page 等元資訊。結果記錄可透過 JSON 陣列中的 data 鍵取得。以下是從路由回傳分頁器實例所建立的 JSON 範例：

{
  "total": 50,
  "per_page": 15,
  "current_page": 1,
  "last_page": 4,
  "current_page_url": "http://laravel.app?page=1",
  "first_page_url": "http://laravel.app?page=1",
  "last_page_url": "http://laravel.app?page=4",
  "next_page_url": "http://laravel.app?page=2",
  "prev_page_url": null,
  "path": "http://laravel.app",
  "from": 1,
  "to": 15,
  "data": [
    {
      // Record...
    },
    {
      // Record...
    }
  ]
}

自訂分頁視圖 (Customizing the Pagination View)

預設情況下，渲染以顯示分頁連結的視圖與 Tailwind CSS 框架相容。然而，如果您不使用 Tailwind，您可以自由定義自己的視圖來渲染這些連結。在分頁器實例上呼叫 links 方法時，您可以將視圖名稱作為第一個參數傳遞給該方法：

{{ $paginator->links('view.name') }}

<!-- 將額外資料傳遞給視圖... -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

然而，自訂分頁視圖最簡單的方法是使用 vendor:publish 命令將它們匯出到您的 resources/views/vendor 目錄：

php artisan vendor:publish --tag=laravel-pagination

此命令會將視圖放置在您應用程式的 resources/views/vendor/pagination 目錄中。此目錄內的 tailwind.blade.php 檔案對應於預設的分頁視圖。您可以編輯此檔案來修改分頁 HTML。

如果您想要指定不同的檔案作為預設分頁視圖，您可以在 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫分頁器的 defaultView 和 defaultSimpleView 方法：

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

使用 Bootstrap (Using Bootstrap)

Laravel 包含使用 Bootstrap CSS 建構的分頁視圖。若要使用這些視圖而非預設的 Tailwind 視圖，您可以在 App\Providers\AppServiceProvider 類別的 boot 方法中呼叫分頁器的 useBootstrapFour 或 useBootstrapFive 方法：

use Illuminate\Pagination\Paginator;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator / LengthAwarePaginator 實例方法 (Paginator / LengthAwarePaginator (Paginator and LengthAwarePaginator Instance Methods)

Instance Methods)

每個分頁器實例透過以下方法提供額外的分頁資訊：

Cursor Paginator 實例方法 (Cursor Paginator Instance Methods)

每個游標分頁器實例透過以下方法提供額外的分頁資訊：