# Laravel 的分頁功能 - [簡介](#introduction) - [基本用法](#basic-usage) - [對查詢語句構造器進行分頁](#paginating-query-builder-results) - [對 Eloquent 模型進行分頁](#paginating-eloquent-results) - [手動創建分頁](#manually-creating-a-paginator) - [顯示分頁結果](#displaying-pagination-results) - [將結果轉換為JSON](#converting-results-to-json) - [自定義分頁視圖](#customizing-the-pagination-view) - [分頁器實例方法](#paginator-instance-methods) <a name="introduction"></a> ## 簡介 在其他的框架中，分頁往往是令人十分頭疼的。 Laravel 的分頁器與 [查詢語句構造器](/docs/{{version}}/queries) 、 [Eloquent ORM](/docs/{{version}}/eloquent) 集成在一起，為數據庫結果集提供了便捷的、開箱即用的分頁器。分頁器生產的 HTML 兼容 Bootstrap CSS framework. <a name="basic-usage"></a> ## 基本用法 <a name="paginating-query-builder-results"></a> ### 對查詢語句構造器進行分頁 有幾種方法可以對項目進行分頁。最簡單的是在 [查詢語句構造器](/docs/{{version}}/queries) 或 [Eloquent 查詢](/docs/{{version}}/eloquent) 中使用 `paginate` 方法。 `paginate` 方法會自動基于用戶當前所查看的頁面來設置適當的限制和偏移。默認情況下，當前頁面通過 HTTP 請求所帶的 `page` 字符串參數的值來檢測。當然，這個值會被 Laravel 自動檢測，并且自動插入到由分頁器產生的鏈接中。 在下面這個例子中，傳遞給 `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} 目前，Laravel無法有效執行使用 `groupBy` 語句的分頁操作。如果你需要在一個分頁結果集中使用 `groupBy`，建議你查詢數據庫并手動創建分頁器。 #### "簡單分頁" 如果你只需要在你的分頁視圖中顯示簡單的「上一頁」和「下一頁」的鏈接，你可以使用 `simplePaginate` 方法來執行更高效的查詢。這在你操作大型數據集、渲染視圖時不需要顯示頁碼鏈接的時候非常有用： $users = DB::table('users')->simplePaginate(15); <a name="paginating-eloquent-results"></a> ### 對 Eloquent 模型進行分頁 你也可以對 [Eloquent](/docs/{{version}}/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); <a name="manually-creating-a-paginator"></a> ### 手動創建分頁 有些時候你可能希望手動創建一個分頁實例，將其傳遞為一個項目數組。你可以依據你的需求創建 `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) 函數。 <a name="displaying-pagination-results"></a> ## 顯示分頁結果 當調用 `paginate` 方法的時候，你將會接收到一個 `Illuminate\Pagination\LengthAwarePaginator` 實例。而當你調用 `simplePaginate` 方法時，你將會接收到一個 `Illuminate\Pagination\Paginator` 實例。這些對象提供了一些用于描述結果集的方法。除了這些輔助方法，分頁器實例也是一個迭代器，并且可以作為數組循環。因此，一旦檢索到結果集，你可以使用 [Blade](/docs/{{version}}/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() }} <a name="converting-results-to-json"></a> ### 將結果轉換為 JSON Laravel 分頁器結果類實現了 `Illuminate\Contracts\Support\Jsonable` 接口契約并且提供 `toJson` 方法，所以它很容易將你的分頁結果集轉換為 JSON。你也可以通過簡單地從路由返回或者控制器 action 的方式，將分頁實例轉換為 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 } ] } <a name="customizing-the-pagination-view"></a> ## 自定義分頁視圖 在默認情況下，視圖渲染顯示的分頁鏈接都兼容 Bootstrap CSS 框架。但是，如果你不使用 Bootstrap，你可以隨意定義你自己的視圖去渲染這些鏈接。當在分頁器實例中調用 `links` 方法時，傳遞視圖名稱作為方法的第一參數即可： {{ $paginator->links('view.name') }} // Passing 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` 目錄中。這個目錄下的 `default.blade.php` 文件對應于默認分頁視圖。你可以簡單地編輯這個文件來修改分頁的 HTML 。 <a name="paginator-instance-methods"></a> ## 分頁器實例方法 每個分頁器實例通過以下方法提供額外的分頁信息： - `$results->count()` - `$results->currentPage()` - `$results->firstItem()` - `$results->hasMorePages()` - `$results->lastItem()` - `$results->lastPage() (Not available when using simplePaginate)` - `$results->nextPageUrl()` - `$results->perPage()` - `$results->previousPageUrl()` - `$results->total() (Not available when using simplePaginate)` - `$results->url($page)` ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | |---|---|---|---| |<br>[@ChrisonWang](https://github.com/ChrisonWang) | <img class="avatar-66 rm-style" src="https://avatars0.githubusercontent.com/u/16531947?v=4&s=80"> | <br>翻譯 | <br>[@王欣](https://www.linkedin.com/in/ChrisonWang/) at LinkedIn| --- > {note} 歡迎任何形式的轉載，但請務必注明出處，尊重他人勞動共創開源社區。 > > 轉載請注明：本文檔由 Laravel China 社區 [laravel-china.org](https://laravel-china.org) 組織翻譯，詳見 [翻譯召集帖](https://laravel-china.org/topics/5756/laravel-55-document-translation-call-come-and-join-the-translation)。 > > 文檔永久地址： https://d.laravel-china.org