資料庫：分頁
簡介
在其他框架中，分頁可能非常痛苦。我們希望 Laravel 的分頁處理方式能讓你耳目一新。Laravel 的分頁器與 查詢產生器 (Query Builder) 和 Eloquent ORM 整合在一起，提供了方便且易於使用的資料庫紀錄分頁功能，且無需任何配置。
預設情況下，分頁器產生的 HTML 與 Tailwind CSS 框架 相容；不過，也提供 Bootstrap 分頁支持。
Tailwind
如果你在 Tailwind 4.x 中使用 Laravel 預設的 Tailwind 分頁視圖，你的應用程式的 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'
);指標分頁 (Cursor Pagination)
雖然 paginate 和 simplePaginate 使用 SQL 的 "offset" 子句建立查詢，但指標分頁（cursor pagination）的工作原理是構建 "where" 子句，比較查詢中所包含的排序欄位的值，提供 Laravel 所有分頁方法中最有效的資料庫性能。這種分頁方法特別適用於大型資料集和「無限捲動」的用戶介面。
與基於位移（offset）的分頁不同（它在分頁器產生的 URL 查詢字串中包含頁碼），基於指標的分頁在查詢字串中放置一個 "cursor" 字串。指標是一個經過編碼的字串，包含下一次分頁查詢應該開始分頁的位置以及分頁的方向：
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] 手動建立分頁器實例時，你應該手動「切片 (slice)」傳遞給分頁器的結果陣列。如果你不確定如何操作，請查看 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();附加雜湊片段 (Hash Fragments)
如果你需要將「雜湊片段」附加到分頁器產生的 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 將包含元信息（meta information），例如 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 實例方法
每個分頁器實例都透過以下方法提供額外的分頁信息：