# 分頁 - [簡介](#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) 集成提供了方便，使用數據庫分頁更容易。生成的分頁樣式兼容 [Bootstrap CSS 框架](http://getbootstrap.com/)。 <a name="basic-usage"></a> ## 基本使用 <a name="paginating-query-builder-results"></a> ### 對查詢語句構造器進行分頁 有幾種方法可以對項目進行分頁。最簡單的是在 [查詢構造器](/docs/{{version}}/queries) 和 [Eloquent ORM](/docs/{{version}}/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); <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](http://php.net/manual/en/function.array-slice.php) 函數。 <a name="displaying-pagination-results"></a> ## 顯示分頁結果 當你調用查詢構建器或 Eloquent 查詢上的 `simplePaginate` 或 `paginate`方法時,你將會獲取一個分頁實例，當調用 `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 框架](https://getbootstrap.com)。 #### 自定義分頁鏈接 `setPath` 方法允許你生成分頁鏈接時自定義分頁使用的 URI 。例如，如果你想要分頁器生成例如 `http://example.com/custom/url?page=N` 類似的鏈接，你可以使用 `setPath` 方法將 `custom/url` 加到分頁中： Route::get('users', function () { $users = App\User::paginate(15); $users->setPath('custom/url'); // }); #### 添加參數到分頁鏈接 你可以使用 `appends` 方法添加所需要的參數到分頁鏈接中。例如，要加入 `&sort=votes` 到每個分頁鏈接時，你應該這樣使用 `appends` 方法： {{ $users->appends(['sort' => 'votes'])->links() }} 如果你想加入一個有 “hash fragment” 的分頁鏈接網址, 則可以使用 `fragment` 方法。例如，要在每個分頁鏈接的最后加入 `#foo` , 應該像這樣使用 `fragment` 方法： {{ $users->fragment('foo')->links() }} <a name="converting-results-to-json"></a> ### 轉換至 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 } ] } <a name="customizing-the-pagination-view"></a> ## 在視圖中顯示分頁結果 默認情況下，渲染顯示分頁鏈接使用 Bootstrap CSS 框架。不過，如果你不使用 Bootstrap 你可以自由定義您自己的視圖來呈現這些鏈接，當我們在分頁實例中調用 `links` 方法，將視圖名稱傳遞給方法的第一個參數： {{ $paginator->links('view.name') }} 自定義分頁視圖的最簡單的方法是通過 `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)`