数据库：分页

• 简介
• 基本用法
  • 查询构造器分页
  • Eloquent ORM 分页
  • 手动创建分页
  • 自定义分页 URL
• 显示分页结果
  • 调整分页链接窗口
  • 将结果转换为 JSON
• 自定义分页视图
  • 使用 Bootstrap
• 分页器实例方法

简介

使用其他框架时，分页可以是一件非常痛苦的事。Laravel 的分页器与 查询构造器 和 Eloquent ORM 集成，提供了方便、易用且无需配置的数据库结果分页。

默认情况下，分页器所生成的 HTML 适用于 Tailwind CSS 框架。不过，Laravel 依然提供了对 Bootstrap 的支持。

基本用法

查询构造器分页

数据分页有很多种方法。最简单的是使用 查询构造器 和 Eloquent query 的 pagiante 方法。pagiante 方法会根据用户浏览的页码，自动设置合适的偏移量和限制量。默认情况下，HTTP 请求中的 page 查询参数将会被当作当前页的页码。Laravel 会自动检测该值，并自动将其插入到分页器生成的链接中。

在下面的例子中，传递给 pagiante 方法的唯一参数是你想要在一页中显示的记录数。在此例中，我们希望每页显示 15 条数据：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\DB;

class UserController extends Controller
{
    /**
     * 显示所有用户列表
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

「简单分页」

paginate 会在查询数据库之前先计算与查询匹配的记录总数，从而让分页器知道总共需要有多少个页面来显示所有的记录。不过，如果你不打算在界面上显示总页数的话，那么计算记录总数是没有意义的。

因此，如果你只需要显示一个简单的「上一页」和「下一页」链接的话，simplePaginate 是一个更高效的选择：

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

Eloquent ORM 分页

你也可以对 Eloquent ORM 查询结果进行分页。在下面的例子中，我们将 App\Models\User 模型按每页 15 条记录进行分页。如你所见，其语法与查询构造器分页基本相同：

use App\Models\User;

$users = User::paginate(15);

当然，你也可以在调用 paginate 方法之前为查询添加其他约束，例如 where：

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

你也可以在 Eloquent ORM 分页中使用 simplePaginate：

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

手动创建分页

有时你可能希望手动创建分页，并传递一个包含数据的数组给它。这可以通过手动创建 Illuminate\Pagination\Paginator 或者 Illuminate\Pagination\LengthAwarePaginator 实例来实现，这取决于你的需要。

Paginator 不需要知道数据的总数。然而，你也无法通过 Paginator 获取最后一页的索引。而 LengthAwarePaginator 接受和 Paginator 几乎相同的参数，不过，它会计算数据的总数。

或者说，Paginator 相当于查询构造器或者 Eloquent ORM 分页的 simplePaginate 方法，而 LengthAwarePaginator 相当于 paginate 方法。

注意：在手动创建分页实例时，需要手动「切割（slice）」传递给分页实例的数据数组。如果你不知道应该怎么做，请参考 PHP 的 array_slice 函数。

自定义分页 URL

默认情况下，分页器生成的链接会匹配当前的请求 URL。不过，分页器的 withPath 方法允许你自定义分页器生成链接时使用的 URL。比如说，你想要分页器生成类似 https://example.com/admin/users?page=N 的链接，你应该给 withPath 方法传递 /admin/users 参数：

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->withPath('/admin/users');

    //
});

附加参数到分页链接

你可以使用 appends 方法向分页链接中添加查询参数。例如，要在每个分页链接中添加 sort=votes ，你应该这样调用 appends：

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->appends(['sort' => 'votes']);

    //
});

如果你想要把当前所有的请求查询参数添加到分页链接，你可以使用 withQueryString 方法：

$users = User::paginate(15)->withQueryString();

添加哈希片段

如果你希望向分页器的 URL 添加「哈希片段」，你可以使用 fragment 方法。例如，你可以使用以下方法向分页链接添加 #foo：

$users = User::paginate(15)->fragment('users');

展示分页结果

当调用 paginate 方法时，你会得到一个 Illuminate\Pagination\LengthAwarePaginator 实例。而调用 simplePaginate 方法时，你会得到 Illuminate\Pagination\Paginator 的实例。这些对象提供了数个方法来获取结果集的信息。除了这些辅助方法外，分页器的实例是迭代器，可以像数组一样遍历。所以，你可以使用 Blade 模板来显示数据、渲染分页链接等：

<div class="container">
    @foreach ($users as $user)
        {{ $user->name }}
    @endforeach
</div>

{{ $users->links() }}

links 方法会渲染结果集中剩余页面的链接。每个链接都包含了 page 查询字符串变量。请记住，links 方法生成的 HTML 兼容 Tailwind CSS 框架。

调整分页链接窗口

在使用分页器展示分页链接时，将展示当前页前后各三页的链接。如果有需要，你可以通过 onEachSide 方法来控制每侧显示多少个链接：

{{ $users->onEachSide(5)->links() }}

将结果转换为 JSON

Laravel 分页器类实现了 Illuminate\Contracts\Support\Jsonable 接口契约，提供了 toJson 方法。这意味着你可以很方便地将分页结果转换为 JSON。你也可以通过直接在路由闭包或者控制器方法中返回分页实例来将其转换为 JSON：

use App\Models\User;

Route::get('/users', function () {
    return 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":[
        {
            // 记录...
        },
        {
            // 记录...
        }
   ]
}

自定义分页视图

默认情况下，分页器渲染的视图与 Tailwind CSS 框架 兼容。不过，如果你并非使用 Tailwind，你也可以自由地定义用于渲染这些链接的视图。在调用分页器实例的 links 方法时，将视图名称作为第一个参数传递给该方法：

{{ $paginator->links('view.name') }}

// 将额外数据传递给视图...
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

不过，最简单的自定义分页视图的方法依然是使用 vendor:publish 命令将它们导出到 resources/views/vendor 目录

php artisan vendor:publish --tag=laravel-pagination

这个命令将会把分页视图导出到 resources/views/vendor/pagination 目录。该目录下的 tailwind.blade.php 文件就是默认的分页视图。你可以通过编辑这一文件来自定义分页视图。

如果你想要定义不同的文件作为默认的分页视图，你可以在 App\Providers\AppServiceProvider 服务提供者中的 boot 方法内调用 defaultView 和 defaultSimpleView 方法：

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 引导任意应用服务
     *
     * @return void
     */
    public function boot()
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

使用 Bootstrap

Laravel 同样包含使用 Bootstrap CSS 构建的分页视图。要使用这些视图来替代默认的 Tailwind 视图，你可以在 App\Providers\AppServiceProvider 服务提供者中的 boot 方法内调用分页器的 useBootstrap 方法：

use Illuminate\Pagination\Paginator;

/**
 * 引导任意应用服务
 *
 * @return void
 */
public function boot()
{
    Paginator::useBootstrap();
}

分页器实例方法

每一个分页器实例都提供了下列方法来获取分页信息：