数据库：分页

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

介绍

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

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

Tailwind

如果您使用的是Laravel默认的Tailwind分页视图，并且使用的是Tailwind 4.x，那么您的应用程序的resources/css/app.css文件将已经正确配置为@source Laravel的分页视图：

css

@import 'tailwindcss';

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

基本用法

分页查询构建器结果

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

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

php

<?php

namespace App\Http\Controllers;

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

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

php

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

分页Eloquent结果

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

php

use App\Models\User;

$users = User::paginate(15);

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

php

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

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

php

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

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

php

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

每页多个分页器实例

有时您可能需要在应用程序渲染的单个屏幕上呈现两个独立的分页器。然而，如果两个分页器实例都使用page查询字符串参数来存储当前页面，则两个分页器会发生冲突。为了解决这个冲突，您可以通过传递给paginate、simplePaginate和cursorPaginate方法的第三个参数来指定用于存储分页器当前页面的查询字符串参数的名称：

php

use App\Models\User;

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

游标分页

虽然paginate和simplePaginate使用SQL的“偏移”子句创建查询，但游标分页通过构建“where”子句来比较查询中包含的有序列的值，提供了在Laravel所有分页方法中最有效的数据库性能。这种分页方法特别适合于大型数据集和“无限”滚动用户界面。

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

text

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb25leHRJdGVtcyI6dHJ1ZX0

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

php

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

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

WARNING

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

游标分页与偏移分页

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

sql

# 偏移分页...
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方法。

WARNING

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

自定义分页URL

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

php

use App\Models\User;

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

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

    // ...
});

附加查询字符串值

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

php

use App\Models\User;

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

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

    // ...
});

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

php

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

附加哈希片段

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

php

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

显示分页结果

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

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

blade

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

{{ $users->links() }}

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

调整分页链接窗口

当分页器显示分页链接时，当前页码以及当前页之前和之后的三个页面的链接将被显示。使用onEachSide方法，您可以控制在分页器生成的中间滑动窗口中每侧显示的附加链接数量：

blade

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

将结果转换为JSON

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

php

use App\Models\User;

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

分页器生成的JSON将包括诸如total、current_page、last_page等元信息。结果记录通过JSON数组中的data键可用。以下是从路由返回分页器实例生成的JSON示例：

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

blade

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

<!-- 向视图传递附加数据... -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

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

shell

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

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

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

php

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

php

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

数据库：分页 ​

介绍 ​

Tailwind ​

基本用法 ​

分页查询构建器结果 ​

简单分页 ​

分页Eloquent结果 ​

每页多个分页器实例 ​

游标分页 ​

游标分页与偏移分页 ​

手动创建分页器 ​

自定义分页URL ​

附加查询字符串值 ​

附加哈希片段 ​

显示分页结果 ​

调整分页链接窗口 ​

将结果转换为JSON ​

自定义分页视图 ​

使用Bootstrap ​

Paginator / LengthAwarePaginator实例方法 ​

游标分页器实例方法 ​

数据库：分页

介绍

Tailwind

基本用法

分页查询构建器结果

简单分页

分页Eloquent结果

每页多个分页器实例

游标分页

游标分页与偏移分页

手动创建分页器

自定义分页URL

附加查询字符串值

附加哈希片段

显示分页结果

调整分页链接窗口

将结果转换为JSON

自定义分页视图

使用Bootstrap

Paginator / LengthAwarePaginator实例方法

游标分页器实例方法