分页器()pager() 函数用于处理 分页记录 （第一个参数）. 它返回一个对象，其中包含有关记录的详细信息，包括页码以及下一页/上一页链接。当被视为字符串时，它将渲染默认的 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 端点](../../cms/resources/building-apis.md) (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) }}此 默认 模板渲染默认分页模板。它默认与 分页() 方法一起用于数据库查询。
<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
访问 分页功能文章 以了解如何使用自定义分页标记。
:::