数据库:分页
介绍
在其他框架中,分页可能非常痛苦,我们希望 Laravel 的分页方法像一股新鲜空气。 Laravel 的分页器集成了 query builder 和 Eloquent ORM,并提供了方便、易于使用的无需任何配置的数据库记录分页。
默认情况下,由分页器生成的 HTML 与 Tailwind CSS 框架 兼容,然而,引导分页支持也是可用的。
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',
],
基础用法
对查询构造器结果进行分页
有几种方法可以对结果进行分页,最简单的方法是在 query builder 或 Eloquent query 上使用 paginate
方法, paginate
方法根据用户查看的当前页面自动设置查询的「limit」和「offset」,默认情况下,通过 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
{
/**
* 显示应用中所有用户列表
*/
public function index(): View
{
return view('user.index', [
'users' => DB::table('users')->paginate(15)
]);
}
}
简单分页
paginate
方法会在查询数据库之前先计算与查询匹配的记录总数,从而让分页器知道总共需要有多少个页面来显示所有的记录。不过,如果你不打算在界面上显示总页数的话,那么计算记录总数是没有意义的。simplePaginate
方法是一个更高效的选择:$users = DB::table('users')->simplePaginate(15);
Eloquent ORM 分页
App\Models\User
模型按每页 15 条记录进行分页。如你所见,其语法与查询构造器分页基本相同:use App\Models\User;
$users = User::paginate(15);
paginate
方法之前为查询添加其他约束,例如 where
子句:$users = User::where('votes', '>', 100)->paginate(15);
你也可以在 Eloquent ORM 分页中使用 simplePaginate
:
$users = User::where('votes', '>', 100)->simplePaginate(15);
同样,您可以使用 cursorPaginate
方法对 Eloquent 模型进行游标分页:
$users = User::where('votes', '>', 100)->cursorPaginate(15);
每页有多个 Paginator 实例
有时你可能需要在应用程序呈现的单个屏幕上呈现两个单独的分页器。 但是,如果两个分页器实例都使用 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 的查询字符串中包含页码不同,基于游标的分页在查询字符串中放置一个「游标」字符串。游标是一个编码字符串,包含下一个分页查询应该开始分页的位置和它应该分页的方向:
http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
你可以通过查询生成器提供的 cursorPaginate
方法创建基于游标的分页器实例。这个方法返回一个 Illuminate\Pagination\CursorPaginator
的实例:
$users = DB::table('users')->orderBy('id')->cursorPaginate(15);
检索到游标分页器实例后,你可以像使用 paginate
和 simplePaginate
方法时一样显示分页结果。更多游标分页器提供的实例方法请参考游标分页器实例方法文档.
注意
你的查询必须包含「order by」子句才能使用游标分页。
游标与偏移分页
为了说明偏移分页和游标分页之间的区别,让我们检查一些示例 SQL 查询。 以下两个查询都将显示按 id
排序的 users
表的「第二页」结果:
# 偏移分页...
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
不需要知道数据的总数。然而,你也无法通过 Paginator
获取最后一页的索引。而 LengthAwarePaginator
接受和 Paginator
几乎相同的参数,不过,它会计算数据的总数。
或者说,Paginator
相当于查询构造器或者 Eloquent ORM 分页的 simplePaginate
方法,而 LengthAwarePaginator
相当于 paginate
方法。
注意
手动创建分页器实例时,你应该手动「切片」传递给分页器的结果数组。如果你不确定如何执行此操作,请查看 array_slice PHP 函数。
自定义分页的 URL
默认情况下,分页器生成的链接会匹配当前的请求 URL。不过,分页器的 withPath 方法允许你自定义分页器生成链接时使用的 URL。比如说,你想要分页器生成类似 https://example.com/admin/users?page=N 的链接,你应该给 withPath
方法传递 /admin/users
参数:
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();
附加 hash 片段
如果你希望向分页器的 URL 添加「哈希片段」,你可以使用 fragment
方法。例如,你可以使用 fragment
方法,为 #user
添加分页链接:
$users = User::paginate(15)->fragment('users');
显示分页结果
当调用 paginate
方法时, 你会得到一个 Illuminate\Pagination\LengthAwarePaginator
实例, 而调用 simplePaginate
方法时,会得到一个 Illuminate\Pagination\Paginator
实例。 最后,调用 cursorPaginate
方法,会得到 Illuminate\Pagination\CursorPaginator
实例。
这些对象提供了数个方法来获取结果集的信息。除了这些辅助方法外,分页器的实例是迭代器,可以像数组一样遍历。所以,你可以使用 Blade 模板来显示数据、渲染分页链接等:
<div class="container">
@foreach ($users as $user)
{{ $user->name }}
@endforeach
</div>
{{ $users->links() }}
links 方法会渲染结果集中剩余页面的链接。每个链接都包含了 page 查询字符串变量。请记住,links 方法生成的 HTML 兼容 Tailwind CSS 框架 。
调整分页链接窗口
在使用分页器展示分页链接时,将展示当前页及当前页面前后各三页的链接。如果有需要,你可以通过 onEachSide
方法来控制每侧显示多少个链接:
{{ $users->onEachSide(5)->links() }}
将结果转换为JSON
Laravel 分页器类实现了 Illuminate\Contracts\Support\Jsonable
接口契约,提供了 toJson
方法。这意味着你可以很方便地将分页结果转换为 JSON。你也可以通过直接在路由闭包或者控制器方法中返回分页实例来将其转换为 JSON:
use App\Models\User;
Route::get('/users', function () {
return User::paginate();
});
分页器生成的 JSON 会包括诸如 total
,current_page
,last_page
等元数据信息。实际结果对象将通过 JSON 数组的 data
键提供。以下是通过自路由中分页器实例的方式创建 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
方法时,将视图名称作为第一个参数传递给该方法:
{{ $paginator->links('view.name') }}
<!-- 向视图传递参数... -->
{{ $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
文件就是默认的分页视图。你可以通过编辑这一文件来自定义分页视图。
如果你想要定义不同的文件作为默认的分页视图,你可以在 App\Providers\AppServiceProvider
服务提供者中的 boot
方法内调用 defaultView
和 defaultSimpleView
方法:
<?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
方法:
use Illuminate\Pagination\Paginator;
/**
* 引导应用程序服务
*/
public function boot(): void
{
Paginator::useBootstrapFive();
Paginator::useBootstrapFour();
}
分页器实例方法
每一个分页器实例都提供了下列方法来获取分页信息:
方法 | 描述 |
---|---|
$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->perPage() | 每页显示的数据数量 |
$paginator->previousCursor() | 获取上一页数据实例 |
$paginator->previousPageUrl() | 获取上一页URL |
$paginator->setCursorName() | 设置用于查询实例的变量名称 |
$paginator->url($cursor) | 获取指定实例的 URL |