* * * * * [TOC] ## 簡介 在其他的框架中，分頁是令人非常煩惱的。 Laravel 的分頁器為?[查詢構造器](https://laravel-china.org/docs/laravel/5.4/queries)?和?[Eloquent ORM](https://laravel-china.org/docs/laravel/5.4/eloquent)?集成提供了方便，并提供基于數據庫結果集的分頁開箱即用。分頁器生產的 HTML 兼容?[Bootstrap CSS framework](https://getbootstrap.com/). ## 基本使用 ### 對查詢語句構造器進行分頁 有幾種方法可以對項目進行分頁。最簡單的是在?[查詢語句構造器](https://laravel-china.org/docs/laravel/5.4/queries)?或?[Eloquent 查詢](https://laravel-china.org/docs/laravel/5.4/eloquent)?中使用?`paginate`?方法。?`paginate`?方法會自動基于當前用戶查看的當前頁面來設置適當的限制和偏移。默認情況下，當前頁面通過 HTTP 請求所帶的?`?page`?參數的值來檢測。當然，這個值會被 Laravel 自動檢測，并且自動插入到由分頁器生產的鏈接中。 首先，讓我們先來看看如何在查詢上調用?`paginate`?方法。在這個例子中，傳遞給?`paginate`?方法的唯一參數是你希望在「每頁」顯示的數據數。在這種情況下，讓我們指定希望每頁顯示?`15`?條數據： ~~~ <?php namespace App\Http\Controllers; use Illuminate\Support\Facades\DB; use App\Http\Controllers\Controller; class UserController extends Controller { /** * 顯示應用中所有的用戶 * * @return Response */ public function index() { $users = DB::table('users')->paginate(15); return view('user.index', ['users' => $users]); } } ~~~ > {note} 目前，使用?`groupBy`?語句的分頁操作無法由 Laravel 有效執行。如果你需要在一個分頁結果集中使用?`groupBy`，建議你查詢數據庫并手動創建分頁器。 #### 「簡單分頁」 如果你只需要在你的分頁視圖中顯示簡單的「上一頁」和「下一頁」的鏈接，你可以使用?`simplePaginate`?方法來執行更高效的查詢。當你在渲染視圖時不需要顯示頁碼鏈接，這對于大數據集非常有用。 ~~~ $users = DB::table('users')->simplePaginate(15); ~~~ ### 對 Eloquent 模型進行分頁 你也可以對?[Eloquent](https://laravel-china.org/docs/laravel/5.4/eloquent)?查詢進行分頁。在這個例子中，我們將對?`User`?模型進行分頁并且每頁顯示?`15`?條數據。正如你看到的，語法幾乎與基于查詢語句構造器的分頁相同： ~~~ $users = App\User::paginate(15); ~~~ 當然，你可以在對查詢設置了其他限制之后調用?`paginate`?方法，例如?`where`?子句： ~~~ $users = User::where('votes', '>', 100)->paginate(15); ~~~ 你也可以在 Eloquent 模型進行分頁使用?`simplePaginate`?方法： ~~~ $users = User::where('votes', '>', 100)->simplePaginate(15); ~~~ ### 手動創建分頁 有時候你可能希望手動創建一個分頁實例，并傳遞其到項目數組中。你可以依據你的需求創建?`Illuminate\Pagination\Paginator`?或?`Illuminate\Pagination\LengthAwarePaginator`?實例。 `Paginator`?類不需要知道結果集中的數據項總數；然而，由于這個，該類沒有用于檢索最后一頁索引的方法。`LengthAwarePaginator`?接收的參數幾乎和?`Paginator`?一樣；但是，它需要計算結果集中的數據項總數。 換一種說法，`Paginator`?對應于查詢語句構造器和 Eloquent 的?`simplePaginate`?方法，而?`LengthAwarePaginator`?對應于?`paginate`?方法。 > {note} 當手動創建分頁器實例時，你應該手動「切割」傳遞給分頁器的結果集。如果你不確定如何去做到這一點，查閱 PHP 的函數?[array_slice](https://secure.php.net/manual/en/function.array-slice.php)?。 ## 顯示分頁結果 當調用?`paginate`?方法的時候，你將會接收到一個?`Illuminate\Pagination\LengthAwarePaginator`?實例。而當你調用?`simplePaginate`?方法時，你將會接收到一個?`Illuminate\Pagination\Paginator`?實例。這些對象提供了一些描述結果集的方法。除了這些輔助方法，分頁器是迭代器并且可以作為數組循環。因此，一旦檢索到結果集，你可以使用?[Blade](https://laravel-china.org/docs/laravel/5.4/blade)?模板顯示結果集并渲染頁面鏈接： ~~~ <div class="container"> @foreach ($users as $user) {{ $user->name }} @endforeach </div> {{ $users->links() }} ~~~ `links`?方法將會渲染結果集中的其他頁鏈接。這些鏈接中每一個都已經包含了?`?page`?查詢字符串變量。記住，`links`?方法生產的 HTML 兼容?[Bootstrap CSS framework](https://getbootstrap.com/) #### 自定義分頁器的 URI `withPath`?方法允許你在生成分頁鏈接時自定義 URI 。例如，如果你想分頁器生成的鏈接如?`http://example.com/custom/url?page=N`，你應該傳遞?`custom/url`?到?`withPath`?方法： ~~~ Route::get('users', function () { $users = App\User::paginate(15); $users->withPath('custom/url'); // }); ~~~ #### 附加參數到分頁鏈接中 你可以使用?`append`?方法附加查詢參數到分頁鏈接中。例如，要附加?`sort=votes`?到每個分頁鏈接，你應該這樣調用?`append`?方法： ~~~ {{ $users->appends(['sort' => 'votes'])->links() }} ~~~ 如果你希望附加「哈希片段」到分頁器的鏈接中，你應該使用?`fragment`?方法。例如，要附加?`#foo`?到每個分頁鏈接的末尾，應該這樣調用?`fragment`?方法： ~~~ {{ $users->fragment('foo')->links() }} ~~~ ### 將結果轉換為 JSON Laravel 分頁器結果類實現了?`Illuminate\Contracts\Support\Jsonable`?接口契約并且提供?`toJson`?方法，所以它很容易將你的分頁結果集轉換為 Json。你也可以簡單地通過從路由或者控制器動作返回分頁實例并將其轉換為 JSON ： ~~~ Route::get('users', function () { return App\User::paginate(); }); ~~~ 從分頁器獲取的 JSON 將包含元信息，如：?`total`,?`current_page`,?`last_page`?等等。實際的結果對象將通過 JSON 數組中的?`data`?鍵來獲取。 以下是一個從路由返回分頁器實例創建的 JSON 示例： ~~~ { "total": 50, "per_page": 15, "current_page": 1, "last_page": 4, "next_page_url": "http://laravel.app?page=2", "prev_page_url": null, "from": 1, "to": 15, "data":[ { // Result Object }, { // Result Object } ] } ~~~ ## 自定義分頁視圖 在默認情況下，視圖渲染顯示的分頁鏈接都兼容 Bootstrap CSS 框架。但是，如果你不使用 Bootstrap，你可以自定義你自己的視圖去渲染這些鏈接。當在分頁器實例中調用?`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`?目錄中。這個目錄下的?`default.blade.php`?文件對應于默認分頁視圖。你可以簡單地編輯這個文件以修改分頁的 HTML 。 ## 分頁器實例方法 每個分頁器實例通過以下方法提供額外的分頁信息： * `$results->count()` * `$results->currentPage()` * `$results->firstItem()` * `$results->hasMorePages()` * `$results->lastItem()` * `$results->lastPage() (當使用 simplePagination 時無效)` * `$results->nextPageUrl()` * `$results->perPage()` * `$results->previousPageUrl()` * `$results->total() (當使用 simplePagination 時無效)` * `$results->url($page)`