数据库：分页

简介

在其他框架中，分页可能非常痛苦。我们希望 Laravel 的分页方式能带来清新体验。Laravel 的分页器与查询构建器和 Eloquent ORM 集成，零配置即可对数据库记录进行便捷、易用的分页。

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

Tailwind

若在 Tailwind 4.x 下使用 Laravel 默认的 Tailwind 分页视图，应用的 resources/css/app.css 文件已正确配置为 @source Laravel 的分页视图：

@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 方法在从数据库检索记录之前，会先统计查询匹配的总记录数，以便分页器知道总共有多少页。但若你不打算在应用 UI 中显示总页数，则该计数查询是不必要的。

因此，若只需在应用 UI 中显示简单的「下一页」与「上一页」链接，可使用 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 查询字符串中包含页码的基于 offset 的分页不同，基于游标的分页会在查询字符串中放置「cursor」字符串。游标是一个编码字符串，包含下一页分页查询应开始的位置以及分页方向：

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

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

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

获取游标分页器实例后，可像使用 paginate 与 simplePaginate 方法时一样展示分页结果。关于游标分页器提供的实例方法，请参阅游标分页器实例方法文档。

WARNING

查询必须包含「order by」子句才能利用游标分页。此外，查询排序所依据的列必须属于你正在分页的表。

游标分页与 Offset 分页对比

为说明 offset 分页与游标分页的差异，我们来看一些示例 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;

游标分页查询相对 offset 分页有以下优势：

• 对于大数据集，若「order by」列已建立索引，游标分页性能更好。因为「offset」子句会扫描此前匹配的全部数据。
• 对于频繁写入的数据集，若用户当前查看的页面上的结果刚被新增或删除，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 方法。

WARNING

手动创建分页器实例时，应手动「切片」传给分页器的结果数组。若不确定如何操作，请参阅 PHP 的 array_slice 函数。

自定义分页 URL

默认情况下，分页器生成的链接会匹配当前请求的 URI。不过，分页器的 withPath 方法允许你自定义生成链接时使用的 URI。例如，若希望分页器生成类似 http://example.com/admin/users?page=N 的链接，应将 /admin/users 传给 withPath 方法：

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 方法。例如，要在每个分页链接末尾追加 #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,
   "current_page_url": "http://laravel.app?page=1",
   "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":[
        {
            // Record...
        },
        {
            // Record...
        }
   ]
}

自定义分页视图

默认情况下，用于显示分页链接的视图与 Tailwind CSS 框架兼容。但若你未使用 Tailwind，可自由定义自己的视图来渲染这些链接。在分页器实例上调用 links 方法时，可将视图名称作为第一个参数传入：

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

<!-- Passing additional 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 目录。该目录中的 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
{
    /**
     * Bootstrap any application services.
     */
    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;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator / LengthAwarePaginator 实例方法

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

Method	Description
$paginator->count()	获取当前页的条目数。
$paginator->currentPage()	获取当前页码。
$paginator->firstItem()	获取结果中第一条的结果序号。
$paginator->getOptions()	获取分页器选项。
$paginator->getUrlRange($start, $end)	创建一段分页 URL 范围。
$paginator->hasPages()	判断条目是否足以拆分为多页。
$paginator->hasMorePages()	判断数据存储中是否还有更多条目。
$paginator->items()	获取当前页的条目。
$paginator->lastItem()	获取结果中最后一条的结果序号。
$paginator->lastPage()	获取最后可用页的页码。（使用 simplePaginate 时不可用）。
$paginator->nextPageUrl()	获取下一页的 URL。
$paginator->onFirstPage()	判断分页器是否在第一页。
$paginator->onLastPage()	判断分页器是否在最后一页。
$paginator->perPage()	每页显示的条目数。
$paginator->previousPageUrl()	获取上一页的 URL。
$paginator->total()	确定数据存储中匹配条目的总数。（使用 simplePaginate 时不可用）。
$paginator->url($page)	获取给定页码的 URL。
$paginator->getPageName()	获取用于存储页码的查询字符串变量。
$paginator->setPageName($name)	设置用于存储页码的查询字符串变量。
$paginator->through($callback)	使用回调转换每个条目。

游标分页器实例方法

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

Method	Description
$paginator->count()	获取当前页的条目数。
$paginator->cursor()	获取当前游标实例。
$paginator->getOptions()	获取分页器选项。
$paginator->hasPages()	判断条目是否足以拆分为多页。
$paginator->hasMorePages()	判断数据存储中是否还有更多条目。
$paginator->getCursorName()	获取用于存储游标的查询字符串变量。
$paginator->items()	获取当前页的条目。
$paginator->nextCursor()	获取下一组条目的游标实例。
$paginator->nextPageUrl()	获取下一页的 URL。
$paginator->onFirstPage()	判断分页器是否在第一页。
$paginator->onLastPage()	判断分页器是否在最后一页。
$paginator->perPage()	每页显示的条目数。
$paginator->previousCursor()	获取上一组条目的游标实例。
$paginator->previousPageUrl()	获取上一页的 URL。
$paginator->setCursorName()	设置用于存储游标的查询字符串变量。
$paginator->url($cursor)	获取给定游标实例的 URL。