# 数据库:分页
- [介绍](#介绍)
- [基本用法](#基本用法)
- [对查询构造器结果进行分页](#对查询构造器结果进行分页)
- [Eloquent ORM 分页](#EloquentORM分页)
- [游标分页](#游标分页)
- [手动创建分页](#手动创建分页)
- [自定义分页 URL](#自定义分页URL)
- [显示分页结果](#显示分页结果)
- [调整分页链接窗口](#调整分页链接窗口)
- [将结果转换为 JSON](#将结果转换为JSON)
- [自定义分页视图](#自定义分页视图)
- [使用 Bootstrap](#使用Bootstrap)
- [分页器实例方法](#分页器实例方法)
- [游标分页器实例方法](#游标分页器实例方法)
## 介绍
在其他框架中,分页可能非常痛苦,我们希望 Laravel 的分页方法像一股新鲜空气。 Laravel 的分页器集成了 [query builder](/docs/laravel/10.x/queries) 和 [Eloquent ORM](/docs/laravel/10.x/eloquent),并提供了方便、易于使用的无需任何配置的数据库记录分页。
默认情况下,由分页器生成的 HTML 与 [Tailwind CSS 框架](https://tailwindcss.com/) 兼容,然而,引导分页支持也是可用的。
#### Tailwind JIT
如果你使用 Laravel 的默认 Tailwind 视图和 Tailwind JIT 引擎,你应该确保你的应用程序的 `tailwind.config.js` 文件的 `content` 关键引用 Laravel 的分页视图,这样它们的 Tailwind 类就不会被清除:
```js
content: [
'./resources/**/*.blade.php',
'./resources/**/*.js',
'./resources/**/*.vue',
'./vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],
```
## 基础用法
### 对查询构造器结果进行分页
有几种方法可以对结果进行分页,最简单的方法是在 [query builder](/docs/laravel/10.x/queries) 或 [Eloquent query](/docs/laravel/10.x/eloquent) 上使用 `paginate` 方法, `paginate` 方法根据用户查看的当前页面自动设置查询的「limit」和「offset」,默认情况下,通过 HTTP 请求中的 `page` 查询字符串参数的值检测当前页面,Laravel会自动检测这个值,它也会自动插入到分页器生成的链接中。
在下面的例子中,传递给 paginate
方法的唯一参数是你想要在一页中显示的记录数。在此例中,我们希望「每页」显示 15
条数据:
DB::table('users')->paginate(15)
]);
}
}
#### 简单分页
该 paginate
方法会在查询数据库之前先计算与查询匹配的记录总数,从而让分页器知道总共需要有多少个页面来显示所有的记录。不过,如果你不打算在界面上显示总页数的话,那么计算记录总数是没有意义的。
因此,如果你只需要显示一个简单的「上一页」和「下一页」链接的话, simplePaginate
方法是一个更高效的选择:
$users = DB::table('users')->simplePaginate(15);
### Eloquent ORM 分页
你也可以对 [Eloquent](/docs/laravel/10.x/eloquent) 查询结果进行分页. 在下面的例子中,我们将 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 的查询字符串中包含页码不同,基于游标的分页在查询字符串中放置一个「游标」字符串。游标是一个编码字符串,包含下一个分页查询应该开始分页的位置和它应该分页的方向:
```nothing
http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
```
你可以通过查询生成器提供的 `cursorPaginate` 方法创建基于游标的分页器实例。这个方法返回一个 `Illuminate\Pagination\CursorPaginator` 的实例:
$users = DB::table('users')->orderBy('id')->cursorPaginate(15);
检索到游标分页器实例后,你可以像使用 `paginate` 和 `simplePaginate` 方法时一样[显示分页结果](displaying-pagination-results)。更多游标分页器提供的实例方法请参考[游标分页器实例方法文档](#cursor-paginator-instance-methods).
> **注意**
> 你的查询必须包含「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` 不需要知道数据的总数。然而,你也无法通过 `Paginator` 获取最后一页的索引。而 `LengthAwarePaginator` 接受和 `Paginator` 几乎相同的参数,不过,它会计算数据的总数。
或者说,`Paginator` 相当于查询构造器或者 Eloquent ORM 分页的 `simplePaginate` 方法,而 `LengthAwarePaginator` 相当于 `paginate` 方法。
> **注意**
> 手动创建分页器实例时,你应该手动「切片」传递给分页器的结果数组。如果你不确定如何执行此操作,请查看 [array_slice](https://secure.php.net/manual/en/function.array-slice.php) 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](/docs/laravel/10.x/blade) 模板来显示数据、渲染分页链接等:
```blade