資料庫：分頁

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

簡介

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

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

Tailwind JIT

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

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 個項目

<?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 方法來執行單一、有效率的查詢

$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 的查詢字串中包含頁碼，基於游標的分頁則在查詢字串中放置「游標」字串。游標是一個編碼字串，其中包含下一個分頁查詢應開始分頁的位置，以及它應分頁的方向

https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

您可以使用查詢建構器提供的 cursorPaginate 方法，建立基於游標的分頁器實例。這個方法會傳回 Illuminate\Pagination\CursorPaginator 的實例

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

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

游標與偏移量分頁

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

# 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;

游標分頁查詢提供以下優於偏移量分頁的優點

• 對於大型資料集，如果「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 方法。

自訂分頁 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,
   "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 方法時，您可以將視圖名稱作為該方法的第一個參數傳遞。

{{ $paginator->links('view.name') }}
 
<!-- Passing additional data to the view... -->
{{ $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

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 實例方法

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

游標分頁器實例方法

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