数据库：分页

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

简介

在其他框架中，分页可能会非常痛苦。我们希望 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
 
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 方法执行单个高效查询。

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

对 Eloquent 结果进行分页

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

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

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

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

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

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

类似地，您可以使用 cursorPaginate 方法对 Eloquent 模型进行游标分页。

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

每个页面上的多个分页器实例

有时您可能需要在应用程序呈现的单个屏幕上呈现两个独立的分页器。但是，如果两个分页器实例都使用 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 的查询字符串中包含页码，而基于游标的分页在查询字符串中放置“游标”字符串。游标是包含下一个分页查询应开始分页的位置和分页方向的编码字符串。

https://127.0.0.1/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

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

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

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

游标分页与偏移量分页

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

# 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 方法。

自定义分页 URL

默认情况下，Paginator 生成的链接将与当前请求的 URI 匹配。但是，Paginator 的 withPath 方法允许您自定义 Paginator 在生成链接时使用的 URI。例如，如果您希望 Paginator 生成类似 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 附加到每个分页链接，您应该对 appends 进行以下调用。

use App\Models\User;
 
Route::get('/users', function () {
    $users = User::paginate(15);
 
    $users->appends(['sort' => 'votes']);
 
    // ...
});

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

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

附加哈希片段

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

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

显示分页结果

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

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

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

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

调整分页链接窗口

当 Paginator 显示分页链接时，将显示当前页码以及当前页之前和之后三页的链接。使用 onEachSide 方法，您可以控制在 Paginator 生成的中间滑动窗口链接的每一侧显示多少个额外的链接。

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

将结果转换为 JSON

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

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

Paginator 的 JSON 将包含元信息，例如 total、current_page、last_page 等。结果记录可通过 JSON 数组中的 data 键获得。以下是从路由返回 Paginator 实例创建的 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":[
        {
            // Record...
        },
        {
            // Record...
        }
   ]
}

自定义分页视图

默认情况下，呈现以显示分页链接的视图与 Tailwind CSS 框架兼容。但是，如果您没有使用 Tailwind，您可以自由定义自己的视图来呈现这些链接。在 Paginator 实例上调用 links 方法时，您可以将视图名称作为方法的第一个参数传递。

{{ $paginator->links('view.name') }}
 
<!-- Passing additional data to the view... -->
{{ $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 方法中调用 Paginator 的 defaultView 和 defaultSimpleView 方法。

<?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 方法中调用 Paginator 的 useBootstrapFour 或 useBootstrapFive 方法。

use Illuminate\Pagination\Paginator;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator / LengthAwarePaginator 实例方法

每个 Paginator 实例都通过以下方法提供其他分页信息。

Cursor Paginator 实例方法

每个 Cursor Paginator 实例都通过以下方法提供其他分页信息。