分页

简介

在其他框架中，分页可能会非常麻烦。我们希望 Laravel 的分页方式能带来耳目一新的感觉。Laravel 的分页器与查询构造器以及Eloquent ORM集成，能够以零配置的方式，便捷、易用地对数据库记录进行分页。

默认情况下，分页器生成的 HTML 与 Tailwind CSS 框架兼容；不过，也支持 Bootstrap 分页。

Tailwind

如果你在使用 Laravel 默认的 Tailwind 分页视图，并且使用的是 Tailwind 4.x，那么你应用中的 resources/css/app.css 文件将已正确配置为对 Laravel 的分页视图进行 @source：

@import 'tailwindcss';

@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';

基础用法

对查询构造器结果进行分页

对条目进行分页有多种方式。最简单的方式是在 查询构造器或 Eloquent 查询上使用 paginate 方法。paginate 方法会根据用户当前查看的页面，自动设置查询的“limit”和“offset”。默认情况下，当前页面通过 HTTP 请求中 page 查询字符串参数的值来检测。该值由 Laravel 自动检测，并且也会自动插入到分页器生成的链接中。

在这个示例中，传递给 paginate 方法的唯一参数是你希望“每页”显示的条目数量。在此示例中，我们指定每页显示 15 条数据：

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Show all application users.
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

简单分页

paginate 方法会在从数据库检索记录之前，先统计查询匹配的记录总数。这样做是为了让分页器知道记录总共有多少页。然而，如果你不打算在应用的用户界面中显示总页数，那么记录计数查询就是不必要的。

因此，如果你只需要在应用的用户界面中显示简单的“上一页”和“下一页”链接，你可以使用 simplePaginate 方法来执行一次高效的查询：

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

对 Eloquent 结果进行分页

你也可以对 Eloquent 查询进行分页。在这个示例中，我们将对 App\Models\User 模型进行分页，并指定每页显示 15 条记录。正如你所见，其语法与对查询构造器结果进行分页几乎完全相同：

use App\Models\User;

$users = User::paginate(15);

当然，你可以在对查询设置其他约束（如 where 子句）之后，再调用 paginate 方法：

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

在对 Eloquent 模型进行分页时，你也可以使用 simplePaginate 方法：

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

同样，你可以使用 cursorPaginate 方法对 Eloquent 模型进行游标分页：

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

每页多个分页器实例

有时，你可能需要在一个由应用渲染的界面上显示两个独立的分页器。然而，如果两个分页器实例都使用 page 查询字符串参数来存储当前页面，那么这两个分页器就会发生冲突。为了解决这个冲突，你可以通过传递给 paginate、simplePaginate 和 cursorPaginate 方法的第三个参数，指定你希望用于存储分页器当前页面的查询字符串参数名称：

use App\Models\User;

$users = User::where('votes', '>', 100)->paginate(
    $perPage = 15, $columns = ['*'], $pageName = 'users'
);

游标分页

虽然 paginate 和 simplePaginate 使用 SQL 的“offset”子句创建查询，但游标分页是通过构造比较查询中有序列值的“where”子句来实现的，是 Laravel 所有分页方法中数据库性能最优的方式。这种分页方法尤其适用于大型数据集和“无限滚动”的用户界面。

与基于偏移量的分页（在分页器生成的 URL 查询字符串中包含页码）不同，基于游标的分页会在查询字符串中放置一个“游标”字符串。游标是一个编码后的字符串，其中包含了下一次分页查询应开始的位置及其分页方向：

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

你可以通过查询构造器提供的 cursorPaginate 方法创建一个基于游标的分页器实例。该方法会返回一个 Illuminate\Pagination\CursorPaginator 实例：

$users = DB::table('users')->orderBy('id')->cursorPaginate(15);

一旦你获取了游标分页器实例，就可以像使用 paginate 和 simplePaginate 方法时那样，常规地显示分页结果。有关游标分页器提供的实例方法的更多信息，请查阅游标分页器实例方法文档。

为了充分利用游标分页，你的查询必须包含“order by”子句。此外，查询排序所依据的列必须属于你要分页的表。

游标分页与偏移分页

为了说明偏移分页和游标分页的区别，我们来看看一些示例 SQL 查询。以下两条查询都会显示按 id 排序的 users 表的“第二页”结果：

# Offset Pagination...
select * from users order by id asc limit 15 offset 15;

# Cursor Pagination...
select * from users where id > 15 order by id asc limit 15;

与偏移分页相比，游标分页查询具有以下优势：

• 对于大型数据集，如果“order by”列有索引，游标分页将提供更好的性能。这是因为“offset”子句会扫描所有之前匹配的数据。
• 对于频繁写入的数据集，如果在用户当前查看的页面中最近添加或删除了结果，偏移分页可能会跳过记录或显示重复记录。

然而，游标分页有以下限制：

• 与 simplePaginate 类似，游标分页只能用于显示“上一页”和“下一页”链接，不支持生成带页码的链接。
• 它要求排序基于至少一个唯一列，或者是多个列的唯一组合。不支持值为 null 的列。
• 仅当“order by”子句中的查询表达式设置了别名，并且也添加到“select”子句中时，才支持这些查询表达式。
• 不支持带参数的查询表达式。

手动创建分页器

有时你可能希望手动创建一个分页实例，传入一个已经在内存中的条目数组。你可以根据需要，通过创建 Illuminate\Pagination\Paginator、Illuminate\Pagination\LengthAwarePaginator 或 Illuminate\Pagination\CursorPaginator 实例来实现。

Paginator 和 CursorPaginator 类不需要知道结果集中的条目总数；然而，正因如此，这些类没有获取最后一页索引的方法。LengthAwarePaginator 接受的参数与 Paginator 几乎相同；不过，它需要传入结果集中的条目总数。

换句话说，Paginator 对应于查询构造器上的 simplePaginate 方法，CursorPaginator 对应于 cursorPaginate 方法，而 LengthAwarePaginator 对应于 paginate 方法。

当手动创建分页器实例时，你应该手动对传递给分页器的结果数组进行“切片”。如果你不确定如何操作，可以查看 array_slice PHP 函数。

自定义分页 URL

默认情况下，分页器生成的链接会匹配当前请求的 URI。不过，分页器的 withPath 方法允许你自定义分页器在生成链接时所使用的 URI。例如，如果你希望分页器生成形如 http://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 追加到每个分页链接，你应该进行如下调用：

use App\Models\User;

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

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

    // ...
});

如果你希望将当前请求的所有查询字符串值都追加到分页链接中，可以使用 withQueryString 方法：

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

追加哈希片段

如果你需要为分页器生成的 URL 追加“哈希片段”，可以使用 fragment 方法。例如，若要在每个分页链接末尾追加 #users，你可以像下面这样调用 fragment 方法：

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

显示分页结果

调用 paginate 方法时，你会得到一个 Illuminate\Pagination\LengthAwarePaginator 实例；而调用 simplePaginate 方法则会得到一个 Illuminate\Pagination\Paginator 实例。最后，调用 cursorPaginate 方法会得到一个 Illuminate\Pagination\CursorPaginator 实例。

这些对象提供了若干用于描述结果集的方法。除了这些辅助方法之外，分页器实例本身是迭代器，也可以像数组一样进行循环。因此，获取到结果后，你可以使用 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 文件对应默认分页视图。你可以编辑此文件来修改分页 HTML。

如果你希望指定其他文件作为默认分页视图，可以在 App\Providers\AppServiceProvider 类的 boot 方法中调用分页器的 defaultView 与 defaultSimpleView 方法：

<?php

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * 初始化任何应用服务。
     */
    public function boot(): void
    {
        Paginator::defaultView('view-name');

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

使用 Bootstrap

Laravel 内置了使用 Bootstrap CSS 构建的分页视图。若要改用这些视图而不是默认的 Tailwind 视图，你可以在 App\Providers\AppServiceProvider 类的 boot 方法中调用分页器的 useBootstrapFour 或 useBootstrapFive 方法：

use Illuminate\Pagination\Paginator;

/**
 * 初始化任何应用服务。
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

分页器 / LengthAwarePaginator 实例方法

每个分页器实例都通过以下方法提供额外的分页信息：

游标分页器实例方法

每个游标分页器实例可通过以下方法提供额外的分页信息：