分页 · laravel 5.4

<article><h1>Laravel 的分页功能</h1><ul><li><a href="#introduction">简介</a></li><li><a href="#basic-usage">基本使用</a><ul><li><a href="#paginating-query-builder-results">对查询语句构造器进行分页</a></li><li><a href="#paginating-eloquent-results">对 Eloquent 模型进行分页</a></li><li><a href="#manually-creating-a-paginator">手动创建分页</a></li></ul></li><li><a href="#displaying-pagination-results">显示分页结果</a><ul><li><a href="#converting-results-to-json">将结果转换为 JSON</a></li></ul></li><li><a href="#customizing-the-pagination-view">自定义分页视图</a></li><li><a href="#paginator-instance-methods">分页器实例方法</a></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>在其他的框架中，分页是令人非常烦恼的。 Laravel 的分页器为 <a href="/docs/5.4/queries">查询构造器</a> 和 <a href="/docs/5.4/eloquent">Eloquent ORM</a> 集成提供了方便，并提供基于数据库结果集的分页开箱即用。分页器生产的 HTML 兼容 <a href="https://getbootstrap.com/">Bootstrap CSS framework</a>.<a name="basic-usage"></a><h2><a href="#basic-usage">基本使用</a></h2><a name="paginating-query-builder-results"></a><h3>对查询语句构造器进行分页</h3>有几种方法可以对项目进行分页。最简单的是在 <a href="/docs/5.4/queries">查询语句构造器</a> 或 <a href="/docs/5.4/eloquent">Eloquent 查询</a> 中使用 <code class=" language-php">paginate</code> 方法。 <code class=" language-php">paginate</code> 方法会自动基于当前用户查看的当前页面来设置适当的限制和偏移。默认情况下，当前页面通过 HTTP 请求所带的 <code class=" language-php">?page</code> 参数的值来检测。当然，这个值会被 Laravel 自动检测，并且自动插入到由分页器生产的链接中。首先，让我们先来看看如何在查询上调用 <code class=" language-php">paginate</code> 方法。在这个例子中，传递给 <code class=" language-php">paginate</code> 方法的唯一参数是你希望在「每页」显示的数据数。在这种情况下，让我们指定希望每页显示 <code class=" language-php">15</code> 条数据：<pre class=" language-php"><code class=" language-php"><?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]); } }</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 目前，使用 <code class=" language-php">groupBy</code> 语句的分页操作无法由 Laravel 有效执行。如果你需要在一个分页结果集中使用 <code class=" language-php">groupBy</code>，建议你查询数据库并手动创建分页器。</blockquote><h4>「简单分页」</h4>如果你只需要在你的分页视图中显示简单的「上一页」和「下一页」的链接，你可以使用 <code class=" language-php">simplePaginate</code> 方法来执行更高效的查询。当你在渲染视图时不需要显示页码链接，这对于大数据集非常有用。<pre class=" language-php"><code class=" language-php">$users = DB::table('users')->simplePaginate(15);</code></pre><a name="paginating-eloquent-results"></a><h3>对 Eloquent 模型进行分页</h3>你也可以对 <a href="/docs/5.4/eloquent">Eloquent</a> 查询进行分页。在这个例子中，我们将对 <code class=" language-php">User</code> 模型进行分页并且每页显示 <code class=" language-php">15</code> 条数据。正如你看到的，语法几乎与基于查询语句构造器的分页相同：<pre class=" language-php"><code class=" language-php">$users = App\User::paginate(15);</code></pre>当然，你可以在对查询设置了其他限制之后调用 <code class=" language-php">paginate</code> 方法，例如 <code class=" language-php">where</code> 子句：<pre class=" language-php"><code class=" language-php">$users = User::where('votes', '>', 100)->paginate(15);</code></pre>你也可以在 Eloquent 模型进行分页使用 <code class=" language-php">simplePaginate</code> 方法：<pre class=" language-php"><code class=" language-php">$users = User::where('votes', '>', 100)->simplePaginate(15);</code></pre><a name="manually-creating-a-paginator"></a><h3>手动创建分页</h3>有时候你可能希望手动创建一个分页实例，并传递其到项目数组中。你可以依据你的需求创建 <code class=" language-php">Illuminate\Pagination\Paginator</code> 或 <code class=" language-php">Illuminate\Pagination\LengthAwarePaginator</code> 实例。<code class=" language-php">Paginator</code> 类不需要知道结果集中的数据项总数；然而，由于这个，该类没有用于检索最后一页索引的方法。<code class=" language-php">LengthAwarePaginator</code> 接收的参数几乎和 <code class=" language-php">Paginator</code> 一样；但是，它需要计算结果集中的数据项总数。换一种说法，<code class=" language-php">Paginator</code> 对应于查询语句构造器和 Eloquent 的 <code class=" language-php">simplePaginate</code> 方法，而 <code class=" language-php">LengthAwarePaginator</code> 对应于 <code class=" language-php">paginate</code> 方法。<blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 当手动创建分页器实例时，你应该手动「切割」传递给分页器的结果集。如果你不确定如何去做到这一点，查阅 PHP 的函数 <a href="https://secure.php.net/manual/en/function.array-slice.php">array_slice</a> 。</blockquote><a name="displaying-pagination-results"></a><h2><a href="#displaying-pagination-results">显示分页结果</a></h2>当调用 <code class=" language-php">paginate</code> 方法的时候，你将会接收到一个 <code class=" language-php">Illuminate\Pagination\LengthAwarePaginator</code> 实例。而当你调用 <code class=" language-php">simplePaginate</code> 方法时，你将会接收到一个 <code class=" language-php">Illuminate\Pagination\Paginator</code> 实例。这些对象提供了一些描述结果集的方法。除了这些辅助方法，分页器是迭代器并且可以作为数组循环。因此，一旦检索到结果集，你可以使用 <a href="/docs/5.4/blade">Blade</a> 模板显示结果集并渲染页面链接：<pre class=" language-php"><code class=" language-php"><div class="container"> @foreach ($users as $user) {{ $user->name }} @endforeach </div> {{ $users->links() }}</code></pre><code class=" language-php">links</code> 方法将会渲染结果集中的其他页链接。这些链接中每一个都已经包含了 <code class=" language-php">?page</code> 查询字符串变量。记住，<code class=" language-php">links</code> 方法生产的 HTML 兼容 <a href="https://getbootstrap.com">Bootstrap CSS framework</a><h4>自定义分页器的 URI</h4><code class=" language-php">withPath</code> 方法允许你在生成分页链接时自定义 URI 。例如，如果你想分页器生成的链接如 <code class=" language-php">http://example.com/custom/url?page=N</code>，你应该传递 <code class=" language-php">custom/url</code> 到 <code class=" language-php">withPath</code> 方法：<pre class=" language-php"><code class=" language-php">Route::get('users', function () { $users = App\User::paginate(15); $users->withPath('custom/url'); // });</code></pre><h4>附加参数到分页链接中</h4>你可以使用 <code class=" language-php">append</code> 方法附加查询参数到分页链接中。例如，要附加 <code class=" language-php">sort=votes</code> 到每个分页链接，你应该这样调用 <code class=" language-php">append</code> 方法：<pre class=" language-php"><code class=" language-php">{{ $users->appends(['sort' => 'votes'])->links() }}</code></pre>如果你希望附加「哈希片段」到分页器的链接中，你应该使用 <code class=" language-php">fragment</code> 方法。例如，要附加 <code class=" language-php">#foo</code> 到每个分页链接的末尾，应该这样调用 <code class=" language-php">fragment</code> 方法：<pre class=" language-php"><code class=" language-php">{{ $users->fragment('foo')->links() }}</code></pre><a name="converting-results-to-json"></a><h3>将结果转换为 JSON</h3>Laravel 分页器结果类实现了 <code class=" language-php">Illuminate\Contracts\Support\Jsonable</code> 接口契约并且提供 <code class=" language-php">toJson</code> 方法，所以它很容易将你的分页结果集转换为 Json。你也可以简单地通过从路由或者控制器动作返回分页实例并将其转换为 JSON ：<pre class=" language-php"><code class=" language-php">Route::get('users', function () { return App\User::paginate(); });</code></pre>从分页器获取的 JSON 将包含元信息，如： <code class=" language-php">total</code>, <code class=" language-php">current_page</code>, <code class=" language-php">last_page</code> 等等。实际的结果对象将通过 JSON 数组中的 <code class=" language-php">data</code> 键来获取。以下是一个从路由返回分页器实例创建的 JSON 示例：<pre class=" language-php"><code class=" language-php">{ "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 } ] }</code></pre><a name="customizing-the-pagination-view"></a><h2><a href="#customizing-the-pagination-view">自定义分页视图</a></h2>在默认情况下，视图渲染显示的分页链接都兼容 Bootstrap CSS 框架。但是，如果你不使用 Bootstrap，你可以自定义你自己的视图去渲染这些链接。当在分页器实例中调用 <code class=" language-php">links</code> 方法，传递视图名称作为方法的第一参数：<pre class=" language-php"><code class=" language-php">{{ $paginator->links('view.name') }} // 传递数据到视图中... {{ $paginator->links('view.name', ['foo' => 'bar']) }}</code></pre>然而，自定义分页视图最简单的方法是通过 <code class=" language-php">vendor:publish</code> 命令将它们导出到你的 <code class=" language-php">resources/views/vendor</code> 目录：<pre class=" language-php"><code class=" language-php">php artisan vendor:publish --tag=laravel-pagination</code></pre>这个命令将视图放置在 <code class=" language-php">resources/views/vendor/pagination</code> 目录中。这个目录下的 <code class=" language-php">default.blade.php</code> 文件对应于默认分页视图。你可以简单地编辑这个文件以修改分页的 HTML 。<a name="paginator-instance-methods"></a><h2><a href="#paginator-instance-methods">分页器实例方法</a></h2>每个分页器实例通过以下方法提供额外的分页信息：<ul><li><code class=" language-php">$results->count()</code></li><li><code class=" language-php">$results->currentPage()</code></li><li><code class=" language-php">$results->firstItem()</code></li><li><code class=" language-php">$results->hasMorePages()</code></li><li><code class=" language-php">$results->lastItem()</code></li><li><code class=" language-php">$results->lastPage() (当使用 simplePagination 时无效)</code></li><li><code class=" language-php">$results->nextPageUrl()</code></li><li><code class=" language-php">$results->perPage()</code></li><li><code class=" language-php">$results->previousPageUrl()</code></li><li><code class=" language-php">$results->total() (当使用 simplePagination 时无效)</code></li><li><code class=" language-php">$results->url($page)</code></li></ul><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://laravel-china.org/users/3848">@cjjian</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/3848_1477641871.png?imageView2/1/w/100/h/100"></td><td>翻译</td><td>Nothing is impossible. <a href="https://github.com/jcc/">@Jiajian Chan</a> at Github</td></tr></tbody></table></article>