数据库：分页

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

介绍

在其他框架中，分页可能非常麻烦。我们希望 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 方法会根据用户当前查看的页面自动设置查询的“限制”和“偏移”。默认情况下，当前页面由 HTTP 请求上的 page 查询字符串参数的值检测。这个值由 Laravel 自动检测，并自动插入分页器生成的链接中。

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

php

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\DB;

class UserController extends Controller
{
    /**
     * 显示所有应用程序用户。
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        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);

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

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 的查询字符串中包含页码，游标分页在查询字符串中放置一个“游标”字符串。游标是一个编码字符串，包含下一个分页查询应该开始分页的位置和分页的方向：

bash

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb25leHRJdGVtcyI6dHJ1ZX0

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

php

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

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

你的查询必须包含一个“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”列被索引，游标分页将提供更好的性能。这是因为“偏移”子句会扫描所有先前匹配的数据。
对于频繁写入的数据集，如果用户当前查看的页面最近添加或删除了结果，偏移分页可能会跳过记录或显示重复项。

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

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

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
{
    /**
     * 启动任何应用程序服务。
     *
     * @return void
     */
    public function boot()
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

使用 Bootstrap

Laravel 包含使用 Bootstrap CSS 构建的分页视图。要使用这些视图而不是默认的 Tailwind 视图，你可以在 App\Providers\AppServiceProvider 类的 boot 方法中调用分页器的 useBootstrapFour 或 useBootstrapFive 方法：

php

use Illuminate\Pagination\Paginator;

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    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->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 JIT ​

基本用法 ​

分页查询构建器结果 ​

简单分页 ​

分页 Eloquent 结果 ​

每页多个分页器实例 ​

游标分页 ​

游标分页与偏移分页 ​

手动创建分页器 ​

自定义分页 URL ​

附加查询字符串值 ​

附加哈希片段 ​

显示分页结果 ​

调整分页链接窗口 ​

将结果转换为 JSON ​

自定义分页视图 ​

使用 Bootstrap ​

Paginator / LengthAwarePaginator 实例方法 ​

游标分页器实例方法 ​

数据库：分页

介绍

Tailwind JIT

基本用法

分页查询构建器结果

简单分页

分页 Eloquent 结果

每页多个分页器实例

游标分页

游标分页与偏移分页

手动创建分页器

自定义分页 URL

附加查询字符串值

附加哈希片段

显示分页结果

调整分页链接窗口

将结果转换为 JSON

自定义分页视图

使用 Bootstrap

Paginator / LengthAwarePaginator 实例方法

游标分页器实例方法