分页

引言

在其他框架中，分页可能非常麻烦。我们希望 Laravel 的分页方法能为您带来一阵清新的空气。Laravel 的分页器与查询构建器和 Eloquent ORM 集成在一起，可以方便地对数据库记录进行零配置的分页。

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

Tailwind JIT

如果您正在使用 Laravel 的默认 Tailwind 分页视图和 Tailwind JIT 引擎，请确保您的应用程序的 tailwind.config.js 文件的 content 键引用 Laravel 的分页视图，以便它们的 Tailwind 类不会被清除：

content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
    './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 App\Http\Controllers\Controller;
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);

当然，您也可以在设置其他限制条件的查询后调用 paginate 方法，例如 where 子句：

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

您还可以在分页 Eloquent 模型时使用 simplePaginate 方法：

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

类似地，您可以使用 cursorPaginate 方法进行游标分页：

$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 表的结果的“第二页”：

# 基于偏移的分页...
select * from users order by id asc limit 15 offset 15;

# 基于游标的分页...
select * from users where id > 15 order by id asc limit 15;

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

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

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

• 与 simplePaginate 类似，游标分页只能用于显示“上一页”和“下一页”链接，不支持生成带有页码的链接。
• 它要求按照至少一个唯一列或唯一列组合进行排序。不支持具有空值的列。
• 仅当查询表达式被别名并添加到“select”子句中时，才支持在“order by”子句中使用查询表达式。
• 不支持带有参数的查询表达式。

手动创建分页器

有时您可能希望手动创建一个分页器实例，向其传递您已经在内存中拥有的项目数组。您可以通过创建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，则应该将 /admin/users 传递给 withPath 方法：

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":[
        {
            // 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()
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator / LengthAwarePaginator 实例方法

每个分页器实例通过以下方法提供了附加的分页信息：

Cursor Paginator 实例方法

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