数据库：分页

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

介绍

在其他框架中，分页可能非常繁琐。我们希望 Laravel 的分页方法能够带来一股清风。Laravel 的分页器与查询构建器和Eloquent ORM集成，提供便捷易用的数据库记录分页功能，且无需任何配置。

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

顺风

如果您在 Tailwind 4.x 中使用 Laravel 的默认 Tailwind 分页视图，则您的应用程序resources/css/app.css文件将已经正确配置为@sourceLaravel 的分页视图：

1@import 'tailwindcss';
2 
3@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';

@import 'tailwindcss';

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

基本用法

对查询生成器结果进行分页

有几种方法可以对项目进行分页。最简单的方法是使用查询构建器或Eloquent 查询paginate中的方法。该方法会根据用户当前正在查看的页面自动设置查询的“限制”和“偏移量”。默认情况下，当前页面由HTTP 请求中的查询字符串参数值检测。该值由 Laravel 自动检测，并自动插入到分页器生成的链接中。paginatepage

在这个例子中，传递给方法的唯一参数paginate是您希望“每页”显示的项目数。在本例中，我们指定15每页显示的项目数：

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

<?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方法执行单个有效的查询：

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);

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

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

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

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

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的第三个参数，传递您希望用于存储分页器当前页面的查询字符串参数的名称：paginatesimplePaginatecursorPaginate

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和使用 SQL 的“offset”子句创建查询，而simplePaginate游标分页则通过构造“where”子句来比较查询中包含的有序列的值，从而在 Laravel 的所有分页方法中提供最高效的数据库性能。这种分页方法特别适用于大型数据集和“无限”滚动的用户界面。

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

1http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

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

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

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

获取游标分页器实例后，您可以像通常使用和方法一样显示分页结果。有关游标分页器提供的实例方法的更多信息，请参阅游标分页器实例方法文档。paginatesimplePaginate

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

游标与偏移分页

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

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接受的参数与几乎相同；但是，它需要计算结果集中项目总数。CursorPaginatorLengthAwarePaginatorPaginator

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

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

自定义分页 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查询字符串变量。请记住，该方法生成的 HTML与Tailwind CSS 框架links兼容。

调整分页链接窗口

分页器显示分页链接时，会显示当前页码以及当前页前后三个页面的链接。使用该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等。结果记录可通过dataJSON 数组中的键获取。以下是从路由返回分页器实例所创建的 JSON 示例：

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

{
   "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在分页器实例上调用该方法时，您可以将视图名称作为第一个参数传递给该方法：

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']) }}

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

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

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

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

如果您想指定不同的文件作为默认分页视图，您可以在类的方法中调用分页器defaultView和defaultSimpleView方法：bootApp\Providers\AppServiceProvider

 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 视图，你可以在类的方法中调用分页器的useBootstrapFour或useBootstrapFive方法：bootApp\Providers\AppServiceProvider

 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->onLastPage()`	确定分页器是否位于最后一页。
`$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。

序幕

入门

架构概念

基础知识

深入挖掘

安全

数据库

Eloquent ORM

测试

Packages

数据库：分页

介绍

顺风

基本用法

对查询生成器结果进行分页

对 Eloquent 结果进行分页

每页多个分页器实例

手动创建分页器

附加查询字符串值

附加哈希片段

将结果转换为 JSON

使用 Bootstrap

Paginator / LengthAwarePaginator 实例方法

Cursor Paginator 实例方法

本页内容