分頁 · Laravel 5.6 中文文檔

* * * * * [TOC] ## 簡介在大多數的框架中，分頁無不令人十分頭疼。 Laravel 的分頁器與[查詢構造器](http://www.hmoore.net/tonyyu/laravel_5_6/786261)、[Eloquent ORM](http://www.hmoore.net/tonyyu/laravel_5_6/786261)?集成在一起，并提供方便易用的數據結果集分頁。分頁器生成的 HTML 與?[Bootstrap CSS 框架](https://getbootstrap.com/)?兼容。 ## 基本用法 ### 查詢構造器分頁對數據進行分頁有幾種方式。最簡單的是在?[查詢語句構造器](http://www.hmoore.net/tonyyu/laravel_5_6/786261)?或者?[Eloquent 語句](http://www.hmoore.net/tonyyu/laravel_5_6/786261)?使用?`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); ~~~ ### Eloquent 模型分頁你也可以對?[Eloquent](http://www.hmoore.net/tonyyu/laravel_5_6/786261)?查詢進行分頁。下面的例子中對?`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](http://www.hmoore.net/tonyyu/laravel_5_6/786198)?模板顯示結果集并渲染頁面鏈接： ~~~ <div class="container"> @foreach ($users as $user) {{ $user->name }} @endforeach </div> {{ $users->links() }} ~~~ `links`?方法將會鏈接渲染到結果集中其余的頁面。每個鏈接都包含了正確的?`page`?查詢字符串變量。記住，`links`?方法生成的 HTML 與?[Bootstrap CSS 框架](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'); // }); ~~~ #### 附加參數到分頁鏈接中你可以使用?`appends`?方法將查詢參數附加到分頁鏈接中。例如，要將?`sort=votes`?附加到每個分頁鏈接，可以這樣調用?`appends`?方法： ~~~ {{ $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, "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":[ { // 結果集 }, { // 結果集 } ] } ~~~ ## 自定義分頁視圖默認情況下，渲染分頁鏈接的視圖與 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 。 ## 分頁器實例方法每個分頁器實例可以通過以下方法獲取額外的分頁信息： * `$results->count()` * `$results->currentPage()` * `$results->firstItem()` * `$results->hasMorePages()` * `$results->lastItem()` * `$results->lastPage()`?（使用 simplePaginate 時不可用） * `$results->nextPageUrl()` * `$results->perPage()` * `$results->previousPageUrl()` * `$results->total()`?（使用 simplePaginate 時不可用） * `$results->url($page)`