pager() 函数用于处理 [分页记录](../../extend/database/pagination.md) (第一个参数)。它返回一个包含记录详细信息的对象，其中包括页码和下一页/上一页链接。当被视为字符串时，它将渲染默认的 HTML 标记。
一旦你检索到结果，你可以显示结果并渲染页面链接，使用 pager() Twig 函数。
<div class="container">
{% for user in users %}
{{ user.name }}
{% endfor %}
</div>
{{ pager(users) }}支持以下可配置选项（第二个参数）。
| Option | Description |
|---|---|
| template | specify a default template or view name. Example: app::my-custom-view |
| partial | specify a partial name in the theme (CMS only). Example: my-partial |
| withQuery | include any existing query parameters with the generated links. Default: false |
| appends | an optional array of values to include in the query parameters. |
| fragment | an optional fragment string to include in the URLs. |
使用 withQuery 来保留 URL 中现有的查询字符串。
{{ pager(records, { withQuery: true }) }}您可以使用 appends 方法将查询字符串添加到分页链接中。例如，要将 &sort=votes 附加到每个分页链接，您应该对 appends 进行如下调用。
{{ pager(records, { appends: { sort: 'votes' } }) }}如果您希望向分页 URL 附加“哈希片段”，可以使用 fragment 方法。例如，要将 #foo 附加到每个分页链接的末尾，请对 fragment 方法进行以下调用。
{{ pager(records, { fragment: 'foo' }) }}将 pager() 函数设置为一个变量会从分页查询中提取分页链接和元数据。这在 构建 API 端点 (JSON) 时特别有用，但它也可以用于访问 Twig 中的变量。
从分页集合开始。
{% set records = postModel.paginate(3) %}该 pager() 函数将返回一个提取出的对象。
{% set paginator = pager(records) %}每个变量可以在何处被访问。
<a href="{{ paginator.links.first }}"></a>返回的对象被分为 链接 和 元数据 具有以下属性。
| Attribute | Description |
|---|---|
| links.first | URL to the first page |
| links.last | URL to the last page |
| links.prev | URL to the previous page |
| links.next | URL to the next page |
| meta.path | URL to the current page |
| meta.per_page | Number of records per page |
| meta.total | Total records found |
| meta.current_page | The current page number |
| meta.last_page | The last page number |
| meta.from | Starting record number |
| meta.to | Ending record number |
一个 JSON 格式的示例。
{
"links": {
"first": "https://yoursite.tld/api/blog/posts?page=1",
"last": "https://yoursite.tld/api/blog/posts?page=1",
"prev": null,
"next": null
},
"meta": {
"path": "https://yoursite.tld/api/blog/posts",
"per_page": 3,
"total": 2,
"current_page": 1,
"last_page": 1,
"from": 1,
"to": 2
}
}当直接渲染 pager() 函数时，以字符串形式访问它，它将渲染一个用于显示分页链接的默认系统模板。
{{ pager(records) }}对应的 ajaxPager() 函数将渲染一个支持 AJAX 的分页模板（请参阅下面的 AJAX 模板）。理想情况下，这应该在 AJAX 部分 内部使用。
{{ ajaxPager(records) }}default 模板渲染默认的分页模板。它默认与数据库查询上的 paginate() 方法一起使用。
<ul class="pagination">
<li class="page-item first">
<span class="page-link">←</span>
</li>
<li class="page-item">
<a class="page-link" href="?page=1">1</a>
</li>
<li class="page-item last">
<a class="page-link" href="?page=2">→</a>
</li>
</ul>文件位置：~/modules/system/views/pagination/default.htm
simple 模板仅渲染带有上一页和下一页按钮的分页。它默认配合数据库查询的 simplePaginate() 方法使用。
<ul class="pagination">
<li class="page-item first">
<span class="page-link">←</span>
</li>
<li class="page-item last">
<a class="page-link" href="?page=2">→</a>
</li>
</ul>文件位置: ~/modules/system/views/pagination/simple.htm
ajax 模板渲染 AJAX 分页记录。它默认与数据库查询上的 paginate() 方法和 ajaxPager() 函数一起使用。
<ul class="pagination">
<li class="page-item first">
<span class="page-link">←</span>
</li>
<li class="page-item">
<a
class="page-link"
data-request="onAjax"
data-request-data="{ page: 1 }"
data-request-update="{ _self: true }">1</a>
</li>
<li class="page-item last">
<a
class="page-link"
data-request="onAjax"
data-request-data="{ page: 2 }"
data-request-update="{ _self: true }">→</a>
</li>
</ul>文件位置: ~/modules/system/views/pagination/ajax.htm
访问 分页功能文章 以了解如何使用自定义分页标记。
:::