Appearance
分页
介绍
在其他框架中,分页可能非常痛苦。我们希望 Laravel 的分页方法能带来一股清新的空气。Laravel 的分页器与查询生成器和 Eloquent ORM 集成,提供方便、易于使用的数据库记录分页,无需配置。
默认情况下,分页器生成的 HTML 与 Tailwind CSS 框架兼容;但是,Bootstrap 分页支持也可用。
Tailwind JIT
如果你使用的是 Laravel 的默认 Tailwind 分页视图和 Tailwind JIT 引擎,你应该确保你的应用程序的 tailwind.config.js
文件的内容
键引用了 Laravel 的分页视图,以便它们的 Tailwind 类不会被清除:
js
content: [
'./resources/**/*.blade.php',
'./resources/**/*.js',
'./resources/**/*.vue',
'./vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],
基本用法
对 Query Builder 结果进行分页
有几种方法可以对项目进行分页。最简单的方法是使用查询生成器上的 paginate
方法或 Eloquent 查询。paginate
方法根据用户正在查看的当前页面自动负责设置查询的 “limit” 和 “offset”。默认情况下,当前页面由 HTTP 请求上的 page
query string 参数的值检测。该值由 Laravel 自动检测,并且还会自动插入到分页器生成的链接中。
在此示例中,传递给 paginate
方法的唯一参数是您希望“每页”显示的项目数。在本例中,让我们指定每页显示 15
个项目:
php
<?php
namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
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 中显示总页数,则不需要 record count 查询。
因此,如果您只需要在应用程序的 UI 中显示简单的 “Next” 和 “Previous” 链接,则可以使用 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);
每页多个 Paginator 实例
有时,您可能需要在应用程序呈现的单个屏幕上呈现两个单独的分页器。但是,如果两个 paginator 实例都使用 page
查询字符串参数来存储当前页面,则两个 paginator 实例将发生冲突。要解决此冲突,您可以通过提供给 paginate
、simplePaginate
和 cursorPaginate
方法的第三个参数来传递要用于存储分页器当前页面的查询字符串参数的名称:
php
use App\Models\User;
$users = User::where('votes', '>', 100)->paginate(
$perPage = 15, $columns = ['*'], $pageName = 'users'
);
游标分页
Paginate
和 simplePaginate
使用 SQL “offset” 子句创建查询,而游标分页的工作原理是构造“where”子句来比较查询中包含的有序列的值,从而在 Laravel 的所有分页方法中提供最高效的数据库性能。这种分页方法特别适用于大型数据集和“无限”滚动用户界面。
与基于偏移量的分页不同,基于光标的分页在分页器生成的 URL 的查询字符串中包含页码,而基于光标的分页将在查询字符串中放置“光标”字符串。游标是一个编码字符串,其中包含下一个分页查询应开始分页的位置以及它应分页的方向:
php
http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
您可以通过查询构建器提供的 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
一样,光标分页只能用于显示 “Next” 和 “Previous” 链接,不支持生成带有页码的链接。 - 它要求排序至少基于一个唯一列或唯一列的组合。不支持具有
null
值的列。 - 仅当 “order by” 子句中的查询表达式被别名并添加到 “select” 子句中时,才受支持。
- 不支持带参数的查询表达式。
手动创建分页器
有时您可能希望手动创建一个 pagination 实例,向其传递内存中已有的项数组。您可以根据需要,通过创建 Illuminate\Pagination\Paginator
、 Illuminate\Pagination\LengthAwarePaginator
或 Illuminate\Pagination\CursorPaginator
实例 来实现此目的。
Paginator
和 CursorPaginator
类不需要知道结果集中的项总数;但是,因此,这些类没有检索最后一页索引的方法。LengthAwarePaginator
接受与 Paginator
几乎相同的参数;但是,它需要结果集中项目总数的计数。
换句话说,Paginator
对应于查询生成器上的 simplePaginate
方法,CursorPaginator
对应于 cursorPaginate
方法,LengthAwarePaginator
对应于 paginate
方法。
WARNING
手动创建 paginator 实例时,您应该手动“切片”传递给 paginator 的结果数组。如果您不确定如何执行此操作,请查看 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();
附加哈希片段
如果您需要将 “hash fragment” 附加到 paginator 生成的 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
方法将呈现指向结果集中其余页面的链接。这些链接中的每一个都已包含正确的页面
查询字符串变量。请记住,由 links
方法生成的 HTML 与 Tailwind CSS 框架兼容。
调整 Pagination Link 窗口
当分页器显示分页链接时,将显示当前页码以及当前页之前和之后的三个页面的链接。使用 onEachSide
方法,您可以控制在分页器生成的链接的中间滑动窗口中,当前页面的每一侧显示多少个附加链接:
blade
{{ $users->onEachSide(5)->links() }}
将结果转换为 JSON
Laravel 分页器类实现了 Illuminate\Contracts\Support\Jsonable
Interface 合约并公开了 toJson
方法,因此很容易将分页结果转换为 JSON。您还可以通过从路由或控制器操作返回 paginator 实例来将其转换为 JSON:
php
use App\Models\User;
Route::get('/users', function () {
return User::paginate();
});
来自分页器的 JSON 将包含元信息,例如 total
、current_page
、last_page
等。结果记录可通过 JSON 数组中的 data
键获得。以下是通过从路由返回 paginator 实例创建的 JSON 示例:
php
{
"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,则可以自由定义自己的视图来呈现这些链接。在 paginator 实例上调用 links
方法时,您可以将视图名称作为第一个参数传递给该方法:
blade
{{ $paginator->links('view.name') }}
<!-- Passing additional data to the view... -->
{{ $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 实例都通过以下方法提供额外的分页信息:
Method | Description |
---|---|
$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) | 使用回调转换每个项 |
Cursor Paginator 实例方法
每个游标分页器实例都通过以下方法提供额外的分页信息:
Method | Description |
---|---|
$paginator->count() | 获取当前页面的项数 |
$paginator->cursor() | 获取当前游标实例 |
$paginator->getOptions() | 获取分页器选项 |
$paginator->hasPages() | 确定是否有足够的项目拆分为多个页面 |
$paginator->hasMorePages() | 确定数据存储区中是否有更多项 |
$paginator->getCursorName() | 获取用于存储游标的查询字符串变量 |
$paginator->items() | 获取当前页面的项目 |
$paginator->nextCursor() | 获取下一组项的 cursor 实例 |
$paginator->nextPageUrl() | 获取下一页的 URL |
$paginator->onFirstPage() | 确定分页器是否位于第一页上 |
$paginator->onLastPage() | 确定分页器是否位于最后一页 |
$paginator->perPage() | 每页要显示的项目数 |
$paginator->previousCursor() | 获取上一组项的 cursor 实例 |
$paginator->previousPageUrl() | 获取上一页的 URL |
$paginator->setCursorName() | 设置用于存储游标的查询字符串变量 |
$paginator->url($cursor) | 获取给定游标实例的 URL |