資料庫：分頁

• 簡介
• 基本用法
  • 分頁查詢建構器結果
  • 分頁 Eloquent 結果
  • 游標分頁
  • 手動建立分頁器
  • 自訂分頁 URL
• 顯示分頁結果
  • 調整分頁連結視窗
  • 將結果轉換為 JSON
• 自訂分頁視圖
  • 使用 Bootstrap
• Paginator 和 LengthAwarePaginator 實例方法
• Cursor Paginator 實例方法

簡介

在其他框架中，分頁可能非常痛苦。我們希望 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';

基本用法

分頁查詢建構器結果

有多種方式可以對項目進行分頁。最簡單的方法是使用查詢建構器或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
{
    /**
     * 顯示所有應用程式使用者。
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

簡單分頁

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

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

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

分頁 Eloquent 結果

您也可以對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);

每頁多個分頁器實例

有時您可能需要在單個螢幕上渲染兩個獨立的分頁器，該螢幕由您的應用程式渲染。但是，如果兩個分頁器實例都使用 page 查詢字串參數來儲存當前頁面，則兩個分頁器將會衝突。為了解決此衝突，您可以透過 paginate、simplePaginate 和 cursorPaginate 方法提供的第三個參數，傳遞您希望用於儲存分頁器當前頁面的查詢字串參數名稱：

use App\Models\User;

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

游標分頁

雖然 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. 偏移量分頁

為了說明偏移量分頁和游標分頁之間的差異，讓我們檢查一些範例 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」子句中時，才支援它們。
• 不支援帶有參數的查詢表達式。

手動建立分頁器

有時您可能希望手動建立一個分頁器實例，並傳遞給它一個您已經在記憶體中的項目陣列。您可以透過建立 Illuminate\Pagination\Paginator、Illuminate\Pagination\LengthAwarePaginator 或 Illuminate\Pagination\CursorPaginator 實例來實現這一點，具體取決於您的需求。

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

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

[!WARNING] 手動建立分頁器實例時，您應該手動「切片」傳遞給分頁器的結果陣列。如果您不確定如何做到這一點，請查看 array_slice PHP 函數。

自訂分頁 URL

預設情況下，分頁器生成的連結將與當前請求的 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');

    // ...
});

附加查詢字串值

您可以使用 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();

附加雜湊片段

如果您需要向分頁器生成的 URL 附加「雜湊片段」，可以使用 fragment 方法。例如，要向每個分頁連結的末尾附加 #users，您應該像這樣呼叫 fragment 方法：

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

顯示分頁結果

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

這些物件提供了幾個描述結果集的方法。除了這些輔助方法之外，分頁器實例還是迭代器，可以作為陣列進行迴圈。因此，一旦您檢索到結果，您就可以使用 Blade 顯示結果並渲染頁面連結：

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

{{ $users->links() }}

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

調整分頁連結視窗

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

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

將結果轉換為 JSON

Laravel 分頁器類別實現了 Illuminate\Contracts\Support\Jsonable 介面合約並公開了 toJson 方法，因此將分頁結果轉換為 JSON 非常容易。您也可以透過從路由或控制器動作返回分頁器實例將其轉換為 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":[
        {
            // 記錄...
        },
        {
            // 記錄...
        }
   ]
}

自訂分頁視圖

預設情況下，用於顯示分頁連結的視圖與 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
{
    /**
     * 啟動任何應用程式服務。
     */
    public function boot(): void
    {
        Paginator::defaultView('view-name');

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

使用 Bootstrap

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

use Illuminate\Pagination\Paginator;

/**
 * 啟動任何應用程式服務。
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator / LengthAwarePaginator 實例方法

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

Cursor Paginator 實例方法

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