[ Laravel 5.2 文檔 ] 服務 -- 分頁

1、簡介

在其他架構中，分頁是件非常痛苦的事，Laravel則使其變得輕而易舉。Laravel能夠基於當前頁智能產生一定範圍的連結，且產生的HTML相容 Bootstrap CSS 架構。

2、基本使用

2.1 基於查詢構建器分頁

有多種方式實現分頁，最簡單的方式就是使用查詢構建器或 Eloquent模型的 paginate方法。該方法基於目前使用者查看頁自動化佈建合適的位移（offset）和限制（limit）。預設情況下，當前頁通過HTTP請求查詢字串參數 ?page的值判斷。當然，該值由Laravel自動檢測，然後自動插入分頁器產生的連結中。

讓我們先來看看如何在查詢上調用 paginate方法。在本例中，傳遞給 paginate的唯一參數就是你每頁想要顯示的數目，這裡我們指定每頁顯示 15個：

paginate(15);        return view('user.index', ['users' => $users]);    }}

注意：目前，使用 groupBy的分頁操作不能被Laravel有效執行，如果你需要在分頁結果中使用 groupBy，推薦你手動查詢資料庫然後建立分頁器。

簡單分頁

如果你只需要在分頁檢視中簡單的顯示“下一個”和“上一個”連結，可以使用 simplePaginate方法來執行該查詢。在渲染包含大資料集的視圖且不需要顯示每個頁碼時非常有用：

$users = DB::table('users')->simplePaginate(15);

2.2 基於Eloquent 模型分頁

你還可以對Eloquent查詢結果進行分頁，在本例中，我們對 User模型進行分頁，每頁顯示 15條記錄。正如你所看到的，該文法和基於查詢構建器的分頁差不多：

$users = App\User::paginate(15);

當然，你可以在設定其它約束調價之後調用 paginate，比如 where子句：

$users = User::where('votes', '>', 100)->paginate(15);

你也可以使用 simplePaginate方法：

$users = User::where('votes', '>', 100)->simplePaginate(15);

2.3 手動建立分頁器

有時候你可能想要通過傳遞數組資料來手動建立分頁執行個體，你可以基於自己的需求通過建立 Illuminate\Pagination\Paginator或 Illuminate\Pagination\LengthAwarePaginator執行個體來實現。

Paginator類不需要知道結果集中資料項目的總數；然而，正因如此，該類也沒有提供擷取最後一頁索引的方法。

LengthAwarePaginator接收參數和 Paginator幾乎一樣，只是，它要求傳入結果集的總數。

換句話說， Paginator對應 simplePaginate方法，而 LengthAwarePaginator對應 paginate方法。

當手動建立分頁器執行個體的時候，應該手動對傳遞到分頁器的結果集進行“切片”，如果你不確定怎麼做，查看PHP函數 array_slice。

3、在視圖中顯示分頁結果

當你調用查詢構建器或Eloquent查詢上的 paginate或 simplePaginate方法時，你將會擷取一個分頁器執行個體。當調用 paginate方法時，你將擷取 Illuminate\Pagination\LengthAwarePaginator，而調用方法 simplePaginate時，將會擷取 Illuminate\Pagination\Paginator執行個體。這些對象提供相關方法描述這些結果集，除了這些協助函數外，分頁器執行個體本身就是迭代器，可以像數組一樣對其進行迴圈調用。

所以，擷取到結果後，可以按如下方式使用Blade顯示這些結果並渲染頁面連結：

    @foreach ($users as $user)        {{ $user->name }}    @endforeach{!! $users->links() !!}

links方法將會將結果集中的其它頁面連結渲染出來。每個連結已經包含了 ?page查詢字串變數。記住， render方法產生的HTML相容 Bootstrap CSS 架構。

注意：我們從Blade模板調用 render方法時，確保使用 {!! !!}文法以便HTML連結不被過濾。

自訂分頁連結

setPath方法允許你產生分頁連結時自訂分頁器使用的URI，例如，如果你想要分頁器產生形如 http://example.com/custom/url?page=N的連結，應該傳遞 custom/url到 setPath方法：

Route::get('users', function () {    $users = App\User::paginate(15);    $users->setPath('custom/url');    //});

添加參數到分頁連結

你可以使用 appends方法添加查詢參數到分頁連結查詢字串。例如，要添加 &sort=votes到每個分頁連結，應該像如下方式調用 appends：

{!! $users->appends(['sort' => 'votes'])->links() !!}

如果你想要添加”雜湊片段”到分頁連結，可以使用 fragment方法。例如，要添加 #foo到每個分頁連結的末尾，像這樣調用 fragment方法：

{!! $users->fragment('foo')->links() !!}

更多輔助方法

你還可以通過如下分頁器執行個體上的方法訪問更多分頁資訊：

• $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)

4、將結果轉化為JSON

Laravel分頁器結果類實現了 Illuminate\Contracts\Support\JsonableInterface契約並實現 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        }   ]}

