Page

Paginator

返回对上下文中收到的常规页面集合分页后得到的分页器。

签名
PAGE.Paginator
返回类型
page.Pager

这一页解决什么问题

.Paginator 是分页的最短写法:把当前列表页上下文里已有的页面集合切成多个分页器,返回当前这一页的那一个,.Pages 就是本页要显示的页面。

它不接受参数,也不能先过滤或排序;每页条数完全来自项目配置。所以「分页」这件事,先用 .Paginator 试试,一旦需要筛选就换成 .Paginate。

什么时候用,什么时候别用

该用:

  • section / 首页 / taxonomy / term 模板里,直接对上下文集合分页;
  • 只关心「第几页、共几页」和翻页链接。

别用:

  • 需要先 where 过滤或 .ByDate/.ByTitle 排序 → 用 .Paginate(上游也强烈推荐它);
  • 需要只为某一页改每页条数 → 用 .Paginate;
  • 在常规内容页上调用 → 实测报错 pagination not supported for this page。

两者对照(实测,测试站 pagerSize = 2):

场景 .Paginator .Paginate
集合来源 上下文里的常规页面集合,不可改 你传入的集合,可先 where/排序
每页条数 只能用配置值 可以传第二个参数覆盖
/posts/(10 个常规页面) TotalPages = 5,第一页 = post-1、post-2 传 3 时 TotalPages = 4

用法

分页(pagination)是指把一个列表页面拆分成两个或多个分页器(pager),每个分页器包含页面集合的一个子集,以及指向其他分页器的导航链接。

每个分页器上的元素个数由你的[项目配置][]决定,默认值为 10。

你可以在首页、section、分类法和术语模板中调用分页。这些模板都会在上下文中接收一个常规页面集合。调用 Paginator 方法时,它会对上下文中收到的页面集合进行分页。

layouts/section.htmlgo-html-template
{{ range .Paginator.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ partial "pagination.html" . }}

在上例中,内嵌的分页模板会在分页器之间创建导航链接。

完整示例:section 列表分页

测试站配置 pagerSize = 2,section 模板:

layouts/_default/list.htmlgo-html-template
{{ $pager := .Paginator }}
<ul>
  {{ range $pager.Pages }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>
<p>第 {{ $pager.PageNumber }} / {{ $pager.TotalPages }} 页,共 {{ $pager.TotalNumberOfElements }} 条</p>

实测(Hugo 0.167.0):

渲染的页面 TotalPages 第一页的 .Pages TotalNumberOfElements
/posts/ 5 /posts/post-1、/posts/post-2 10
/tags/alpha/(term 页) 2 /posts/post-1、/posts/post-3 3
/docs/(只有 1 个常规页面) 1 /docs/ref 1

你应当看到什么:TotalPages 是「总条数 ÷ 每页条数」向上取整(10 ÷ 2 = 5;3 ÷ 2 = 2;1 ÷ 2 → 1)。每页条数完全由配置决定——想改成 3 就必须用 .Paginate。

返回值边界(实测)

情况 结果 是否报错
列表页(home/section/taxonomy/term) page.Pager 否
集合为空 .TotalPages 为 0、.Pages 长度为 0(实测 .Paginate 空集合时如此;.Paginator 同为 0) 否
集合条数少于每页条数 .TotalPages 为 1 否
常规内容页 —— 是:error calling Paginator: pagination not supported for this page,构建退出码 1
先 .Paginator 再 .Paginate 分页已缓存,第二次调用不生效(上游已说明) 否
返回类型 page.Pager 否

更多排查入口见故障排查。