数据库：分页

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

介绍

在其他框架中，分页可能非常痛苦，我们希望 Laravel 的分页方法像一股清新的空气。Laravel 的分页器集成了 query builder 和 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',
],

基础用法

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

有几种方法可以对结果进行分页，最简单的方法是在 query builder 或 Eloquent query 上使用 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
{
    /**
     * 显示所有应用程序用户。
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

简单分页

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

因此，如果你只需要显示简单的 "下一步 "和 "上一步 "链接，您可以使用 simplePaginate 方法来执行一次高效的查询：

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

分页集合结果

您也可以对 Eloquent 查询进行分页。在本例中，我们将分页显示 App\Models\User 模型，并指出我们计划每页显示 15 条记录。如您所见，该语法与查询生成器结果的分页几乎完全相同：

use App\Models\User;

$users = User::paginate(15);

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

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

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

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

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

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

每页有多个 Paginator 实例

有时你可能需要在应用程序呈现的单个屏幕上呈现两个单独的分页器。 但是，如果两个分页器实例都使用 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 类似，游标分页只能用于显示「下一页」和「上一页」链接，不支持生成带页码的链接。
• 它要求排序至少基于一个唯一列或一组唯一列。不支持带有 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 的链接，你应该将 /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":[
        {
            // 记录...
        },
        {
            // 记录...
        }
   ]
}

自定义分页视图

默认情况下，用于显示分页链接的视图与 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();
}

Paginator / LengthAwarePaginator 实例方法

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

方法	描述
$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->perPage()	每页显示的条目数。
$paginator->previousPageUrl()	获取前一页的 URL。
$paginator->total()	确定数据存储中匹配条目的总数。（使用 simplePaginate 时不可用）。
$paginator->url($page)	获取给定页码的 URL。
$paginator->getPageName()	获取用于存储页码的查询字符串变量。
$paginator->setPageName($name)	设置用于存储页码的查询字符串变量。
$paginator->through($callback)	使用回调转换每个项。

游标分页器（Cursor Paginator）实例方法

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

方法	描述
$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。

---

原文地址：cndocs/11.x/pa...

译文地址：cndocs/11.x/pa...