資料庫：分頁

簡介
基本用法
顯示分頁結果
- 調整分頁連結視窗
- 將結果轉換為 JSON
自訂分頁視圖
- 使用 Bootstrap
Paginator 和 LengthAwarePaginator 實例方法
游標分頁器實例方法

簡介

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

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

Tailwind JIT

如果您正在使用 Laravel 的預設 Tailwind 分頁視圖和 Tailwind JIT 引擎，您應確保應用程式的 tailwind.config.js 檔案的 content 鍵參考 Laravel 的分頁視圖，以便其 Tailwind 類別不會被清除

1content: [
2    './resources/**/*.blade.php',
3    './resources/**/*.js',
4    './resources/**/*.vue',
5    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
6],

content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],

基本用法

分頁查詢建構器結果

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

在此範例中，傳遞給 paginate 方法的唯一引數是您想要顯示的「每頁」項目數。在此情況下，讓我們指定我們想要每頁顯示 15 個項目

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use Illuminate\Support\Facades\DB;
 7use Illuminate\View\View;
 8 
 9class UserController extends Controller
10{
11    /**
12     * Show all application users.
13     */
14    public function index(): View
15    {
16        return view('user.index', [
17            'users' => DB::table('users')->paginate(15)
18        ]);
19    }
20}

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
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)
        ]);
    }
}

簡易分頁

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

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

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

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

分頁 Eloquent 結果

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

1use App\Models\User;
2 
3$users = User::paginate(15);

use App\Models\User;

$users = User::paginate(15);

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

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

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

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

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

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

同樣地，您可以使用 cursorPaginate 方法來游標分頁 Eloquent 模型

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

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

每個頁面多個分頁器實例

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

1use App\Models\User;
2 
3$users = User::where('votes', '>', 100)->paginate(
4    $perPage = 15, $columns = ['*'], $pageName = 'users'
5);

use App\Models\User;

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

游標分頁

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

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

1https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

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

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

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

一旦您檢索到游標分頁器實例，您可以像使用 paginate 和 simplePaginate 方法時一樣，顯示分頁結果。如需游標分頁器提供的實例方法的詳細資訊，請參閱游標分頁器實例方法文件。

您的查詢必須包含 "order by" 子句，才能利用游標分頁。此外，查詢排序的欄位必須屬於您正在分頁的表格。

游標與 Offset 分頁

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

1# Offset Pagination...
2select * from users order by id asc limit 15 offset 15;
3 
4# Cursor Pagination...
5select * from users where id > 15 order by id asc limit 15;

# Offset Pagination...
select * from users order by id asc limit 15 offset 15;

# Cursor Pagination...
select * from users where id > 15 order by id asc limit 15;

游標分頁查詢提供比 offset 分頁以下優勢

對於大型資料集，如果 "order by" 欄位已編製索引，則游標分頁將提供更好的效能。這是因為 "offset" 子句會掃描所有先前比對的資料。
對於頻繁寫入的資料集，如果結果最近已新增至或從使用者目前正在檢視的頁面中刪除，則 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 方法。

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

自訂分頁 URL

預設情況下，分頁器產生的連結將與目前的請求 URI 相符。但是，分頁器的 withPath 方法可讓您自訂分頁器在產生連結時使用的 URI。例如，如果您希望分頁器產生類似 http://example.com/admin/users?page=N 的連結，您應該將 /admin/users 傳遞給 withPath 方法

1use App\Models\User;
2 
3Route::get('/users', function () {
4    $users = User::paginate(15);
5 
6    $users->withPath('/admin/users');
7 
8    // ...
9});

use App\Models\User;

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

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

    // ...
});

附加查詢字串值

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

1use App\Models\User;
2 
3Route::get('/users', function () {
4    $users = User::paginate(15);
5 
6    $users->appends(['sort' => 'votes']);
7 
8    // ...
9});

use App\Models\User;

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

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

    // ...
});

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

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

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

附加雜湊片段

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

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

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

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

這些物件提供多種描述結果集的方法。除了這些輔助方法之外，分頁器實例也是迭代器，可以作為陣列迴圈。因此，一旦您檢索到結果，您可以使用 Blade 顯示結果並呈現頁面連結

1<div class="container">
2    @foreach ($users as $user)
3        {{ $user->name }}
4    @endforeach
5</div>
6 
7{{ $users->links() }}

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

{{ $users->links() }}

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

調整分頁連結視窗

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

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

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

將結果轉換為 JSON

Laravel 分頁器類別實作 Illuminate\Contracts\Support\Jsonable Interface 合約並公開 toJson 方法，因此將分頁結果轉換為 JSON 非常容易。您也可以透過從路由或控制器動作傳回分頁器實例，將其轉換為 JSON

1use App\Models\User;
2 
3Route::get('/users', function () {
4    return User::paginate();
5});

use App\Models\User;

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

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

 1{
 2   "total": 50,
 3   "per_page": 15,
 4   "current_page": 1,
 5   "last_page": 4,
 6   "first_page_url": "http://laravel.app?page=1",
 7   "last_page_url": "http://laravel.app?page=4",
 8   "next_page_url": "http://laravel.app?page=2",
 9   "prev_page_url": null,
10   "path": "http://laravel.app",
11   "from": 1,
12   "to": 15,
13   "data":[
14        {
15            // Record...
16        },
17        {
18            // Record...
19        }
20   ]
21}

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "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...
        }
   ]
}

自訂分頁視圖

預設情況下，呈現以顯示分頁連結的視圖與 Tailwind CSS 框架相容。但是，如果您未使用 Tailwind，您可以自由定義自己的視圖來呈現這些連結。當在分頁器實例上呼叫 links 方法時，您可以將視圖名稱作為方法的第一個引數傳遞

1{{ $paginator->links('view.name') }}
2 
3<!-- Passing additional data to the view... -->
4{{ $paginator->links('view.name', ['foo' => 'bar']) }}

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

<!-- Passing additional data to the view... -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

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

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

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

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

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

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Pagination\Paginator;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Bootstrap any application services.
12     */
13    public function boot(): void
14    {
15        Paginator::defaultView('view-name');
16 
17        Paginator::defaultSimpleView('view-name');
18    }
19}

<?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

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

 1use Illuminate\Pagination\Paginator;
 2 
 3/**
 4 * Bootstrap any application services.
 5 */
 6public function boot(): void
 7{
 8    Paginator::useBootstrapFive();
 9    Paginator::useBootstrapFour();
10}

use Illuminate\Pagination\Paginator;

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

Paginator / LengthAwarePaginator 實例方法

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

方法	描述
`$paginator->count()`	取得目前頁面的項目數量。
`$paginator->currentPage()`	取得目前頁碼。
`$paginator->firstItem()`	取得結果中第一個項目的結果編號。
`$paginator->getOptions()`	取得分頁器選項。
`$paginator->getUrlRange($start, $end)`	建立分頁 URL 範圍。
`$paginator->hasPages()`	判斷是否有足夠的項目可以分割成多個頁面。
`$paginator->hasMorePages()`	判斷資料儲存區中是否有更多項目。
`$paginator->items()`	取得目前頁面的項目。
`$paginator->lastItem()`	取得結果中最後一個項目的結果編號。
`$paginator->lastPage()`	取得最後一個可用頁面的頁碼。（使用 `simplePaginate` 時不可用）。
`$paginator->nextPageUrl()`	取得下一頁的 URL。
`$paginator->onFirstPage()`	判斷分頁器是否位於第一頁。
`$paginator->perPage()`	每頁要顯示的項目數。
`$paginator->previousPageUrl()`	取得上一頁的 URL。
`$paginator->total()`	判斷資料儲存區中符合條件的項目總數。（使用 `simplePaginate` 時不可用）。
`$paginator->url($page)`	取得給定頁碼的 URL。
`$paginator->getPageName()`	取得用於儲存頁面的查詢字串變數。
`$paginator->setPageName($name)`	設定用於儲存頁面的查詢字串變數。
`$paginator->through($callback)`	使用回呼轉換每個項目。

游標分頁器實例方法

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

方法	描述
`$paginator->count()`	取得目前頁面的項目數量。
`$paginator->cursor()`	取得目前的游標實例。
`$paginator->getOptions()`	取得分頁器選項。
`$paginator->hasPages()`	判斷是否有足夠的項目可以分割成多個頁面。
`$paginator->hasMorePages()`	判斷資料儲存區中是否有更多項目。
`$paginator->getCursorName()`	取得用於儲存游標的查詢字串變數。
`$paginator->items()`	取得目前頁面的項目。
`$paginator->nextCursor()`	取得下一組項目的游標實例。
`$paginator->nextPageUrl()`	取得下一頁的 URL。
`$paginator->onFirstPage()`	判斷分頁器是否位於第一頁。
`$paginator->onLastPage()`	判斷分頁器是否位於最後一頁。
`$paginator->perPage()`	每頁要顯示的項目數。
`$paginator->previousCursor()`	取得前一組項目的游標實例。
`$paginator->previousPageUrl()`	取得上一頁的 URL。
`$paginator->setCursorName()`	設定用於儲存游標的查詢字串變數。
`$paginator->url($cursor)`	取得給定游標實例的 URL。

前言

開始使用

架構概念

基礎

深入探討

安全性

資料庫

Eloquent ORM

測試

套件

資料庫：分頁

簡介

Tailwind JIT

基本用法

分頁查詢建構器結果

分頁 Eloquent 結果

每個頁面多個分頁器實例

手動建立分頁器

附加查詢字串值

附加雜湊片段

將結果轉換為 JSON

使用 Bootstrap

Paginator / LengthAwarePaginator 實例方法

游標分頁器實例方法

產品

套件

資源