数据库：分页

简介
基本用法
显示分页结果
- 调整分页链接窗口
- 将结果转换为 JSON
自定义分页视图
- 使用 Bootstrap
Paginator 和 LengthAwarePaginator 实例方法
游标分页器实例方法

简介

在其他框架中，分页可能非常痛苦。我们希望 Laravel 的分页方法能让人耳目一新。Laravel 的分页器与查询构建器和 Eloquent ORM 集成，并提供方便易用的数据库记录分页功能，无需任何配置。

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

Tailwind JIT

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

1content: [
2    './resources/**/*.blade.php',
3    './resources/**/*.js',
4    './resources/**/*.vue',
5    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
6],

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 个项目

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use Illuminate\Support\Facades\DB;
 7use Illuminate\View\View;
 8 
 9class UserController extends Controller
10{
11    /**
12     * Show all application users.
13     */
14    public function index(): View
15    {
16        return view('user.index', [
17            'users' => DB::table('users')->paginate(15)
18        ]);
19    }
20}

<?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 方法在从数据库检索记录之前，会计算查询匹配的记录总数。这样做是为了让分页器知道总共有多少页记录。但是，如果您不打算在应用程序的 UI 中显示总页数，则记录计数查询是不必要的。

因此，如果您只需要在应用程序的 UI 中显示简单的“下一页”和“上一页”链接，则可以使用 simplePaginate 方法来执行单个高效的查询

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

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

分页 Eloquent 结果

您还可以分页 Eloquent 查询。在此示例中，我们将分页 App\Models\User 模型，并指示我们计划每页显示 15 条记录。如您所见，语法与分页查询构建器结果几乎相同

1use App\Models\User;
2 
3$users = User::paginate(15);

use App\Models\User;

$users = User::paginate(15);

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

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

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

在分页 Eloquent 模型时，您也可以使用 simplePaginate 方法

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

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

同样，您可以使用 cursorPaginate 方法来游标分页 Eloquent 模型

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

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

每页多个分页器实例

有时您可能需要在应用程序呈现的单个屏幕上渲染两个单独的分页器。但是，如果两个分页器实例都使用 page 查询字符串参数来存储当前页面，则两个分页器将冲突。要解决此冲突，您可以将您希望用于存储分页器当前页面的查询字符串参数的名称传递给提供给 paginate、simplePaginate 和 cursorPaginate 方法的第三个参数

1use App\Models\User;
2 
3$users = User::where('votes', '>', 100)->paginate(
4    $perPage = 15, $columns = ['*'], $pageName = 'users'
5);

use App\Models\User;

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

游标分页

虽然 paginate 和 simplePaginate 使用 SQL “offset” 子句创建查询，但游标分页的工作原理是构造 “where” 子句，该子句比较查询中包含的有序列的值，从而在 Laravel 的所有分页方法中提供最有效的数据库性能。这种分页方法特别适用于大型数据集和“无限”滚动用户界面。

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

1https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

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

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

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

检索到游标分页器实例后，您可以像使用 paginate 和 simplePaginate 方法时一样显示分页结果。有关游标分页器提供的实例方法的更多信息，请查阅游标分页器实例方法文档。

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

游标分页与偏移分页

为了说明偏移分页和游标分页之间的差异，让我们检查一些示例 SQL 查询。以下两个查询都将显示按 id 排序的 users 表的“第二页”结果

1# Offset Pagination...
2select * from users order by id asc limit 15 offset 15;
3 
4# Cursor Pagination...
5select * from users where id > 15 order by id asc limit 15;

# 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 的链接，您应该将 /admin/users 传递给 withPath 方法

1use App\Models\User;
2 
3Route::get('/users', function () {
4    $users = User::paginate(15);
5 
6    $users->withPath('/admin/users');
7 
8    // ...
9});

use App\Models\User;

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

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

    // ...
});

附加查询字符串值

您可以使用 appends 方法附加到分页链接的查询字符串。例如，要将 sort=votes 附加到每个分页链接，您应该对 appends 进行以下调用

1use App\Models\User;
2 
3Route::get('/users', function () {
4    $users = User::paginate(15);
5 
6    $users->appends(['sort' => 'votes']);
7 
8    // ...
9});

use App\Models\User;

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

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

    // ...
});

如果您想将当前请求的所有查询字符串值附加到分页链接，则可以使用 withQueryString 方法

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

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

附加哈希片段

如果您需要将“哈希片段”附加到分页器生成的 URL，则可以使用 fragment 方法。例如，要将 #users 附加到每个分页链接的末尾，您应该像这样调用 fragment 方法

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

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

调用 paginate 方法时，您将收到 Illuminate\Pagination\LengthAwarePaginator 的实例，而调用 simplePaginate 方法会返回 Illuminate\Pagination\Paginator 的实例。最后，调用 cursorPaginate 方法会返回 Illuminate\Pagination\CursorPaginator 的实例。

这些对象提供了几个描述结果集的方法。除了这些辅助方法之外，分页器实例也是迭代器，可以像数组一样循环。因此，一旦您检索到结果，您可以使用 Blade 显示结果并呈现页面链接

1<div class="container">
2    @foreach ($users as $user)
3        {{ $user->name }}
4    @endforeach
5</div>
6 
7{{ $users->links() }}

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

{{ $users->links() }}

links 方法将呈现结果集中其余页面的链接。这些链接中的每一个都将已经包含正确的 page 查询字符串变量。请记住，links 方法生成的 HTML 与 Tailwind CSS 框架兼容。

调整分页链接窗口

当分页器显示分页链接时，除了当前页面的前后三页的链接外，还会显示当前页码。使用 onEachSide 方法，您可以控制在分页器生成的中间滑动链接窗口中，当前页面每一侧显示多少个附加链接

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

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

将结果转换为 JSON

Laravel 分页器类实现了 Illuminate\Contracts\Support\Jsonable 接口契约并公开了 toJson 方法，因此将分页结果转换为 JSON 非常容易。您还可以通过从路由或控制器操作返回分页器实例来将分页器实例转换为 JSON

1use App\Models\User;
2 
3Route::get('/users', function () {
4    return User::paginate();
5});

use App\Models\User;

Route::get('/users', function () {
    return User::paginate();
});

来自分页器的 JSON 将包含元信息，例如 total、current_page、last_page 等。结果记录通过 JSON 数组中的 data 键可用。以下是从路由返回分页器实例创建的 JSON 示例

 1{
 2   "total": 50,
 3   "per_page": 15,
 4   "current_page": 1,
 5   "last_page": 4,
 6   "first_page_url": "http://laravel.app?page=1",
 7   "last_page_url": "http://laravel.app?page=4",
 8   "next_page_url": "http://laravel.app?page=2",
 9   "prev_page_url": null,
10   "path": "http://laravel.app",
11   "from": 1,
12   "to": 15,
13   "data":[
14        {
15            // Record...
16        },
17        {
18            // Record...
19        }
20   ]
21}

{
   "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 方法时，您可以将视图名称作为方法的第一个参数传递

1{{ $paginator->links('view.name') }}
2 
3<!-- Passing additional data to the view... -->
4{{ $paginator->links('view.name', ['foo' => 'bar']) }}

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

<!-- Passing additional data to the view... -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

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

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

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

此命令会将视图放置在应用程序的 resources/views/vendor/pagination 目录中。此目录中的 tailwind.blade.php 文件对应于默认分页视图。您可以编辑此文件以修改分页 HTML。

如果您想将其他文件指定为默认分页视图，您可以在 App\Providers\AppServiceProvider 类的 boot 方法中调用分页器的 defaultView 和 defaultSimpleView 方法

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Pagination\Paginator;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Bootstrap any application services.
12     */
13    public function boot(): void
14    {
15        Paginator::defaultView('view-name');
16 
17        Paginator::defaultSimpleView('view-name');
18    }
19}

<?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 方法

 1use Illuminate\Pagination\Paginator;
 2 
 3/**
 4 * Bootstrap any application services.
 5 */
 6public function boot(): void
 7{
 8    Paginator::useBootstrapFive();
 9    Paginator::useBootstrapFour();
10}

use Illuminate\Pagination\Paginator;

/**
 * Bootstrap any application services.
 */
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)`	使用回调转换每个项目。

游标分页器实例方法

每个游标分页器实例通过以下方法提供其他分页信息

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

序言

快速入门

架构概念

基础知识

深入探讨

安全性

数据库

Eloquent ORM

测试

软件包

数据库：分页

简介

Tailwind JIT

基本用法

分页查询构建器结果

分页 Eloquent 结果

每页多个分页器实例

手动创建分页器

附加查询字符串值

附加哈希片段

将结果转换为 JSON

使用 Bootstrap

Paginator / LengthAwarePaginator 实例方法

游标分页器实例方法

产品

软件包

资源