Pager

Pages

返回当前分页器中的页面。

签名
PAGER.Pages
返回类型
page.Pages

这一页解决什么问题

Pages 返回当前分页器里包含的页面集合——不是全站页面,也不是整个待分页集合。分页列表页的主体就是遍历它:第 1 页给前 3 条,第 2 页给第 4–6 条,以此类推。实测 7 条、每页 3 条时,/ 给 3 条、/page/2/ 给 3 条、/page/3/ 给 1 条。

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

该用:

  • 渲染当前这页的文章列表(分页列表页的主循环);
  • 把当前页的页面再交给 range、where、sort 处理。

别用:

  • 要全部页面、不分页 → 直接用 site.RegularPages、RegularPages 或 where 的结果;
  • 要全部 pager(数字页码条)→ 用 Pagers;
  • 想统计条数 → 用 NumberOfElements:实测普通分页下它与 len .Pages 一致,但按组分页时 .Pages 是空的,而 NumberOfElements 仍在计数。

基本用法

go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate $pages }}

{{ range $paginator.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

{{ partial "pagination.html" . }}

完整示例:首页文章列表

layouts/home.htmlgo-html-template
{{ $paginator := .Paginate (where site.RegularPages "Type" "posts") }}
<ul>
  {{ range $paginator.Pages }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

测量条件:Hugo 0.167.0 extended,7 篇 posts(日期 2024-01 至 2024-07),[pagination] pagerSize = 3,baseURL = "https://example.org/"。

/(第 1 页)渲染为(range 会留下空行,这里省略):

html
<ul>
    <li><a href="/posts/p7/">Post 7</a></li>
    <li><a href="/posts/p6/">Post 6</a></li>
    <li><a href="/posts/p5/">Post 5</a></li>
</ul>

/page/3/(最后一页)渲染为:

html
<ul>
    <li><a href="/posts/p1/">Post 1</a></li>
</ul>

你应当看到什么:7 = 3 + 3 + 1。第 1 页是最新的三篇(集合默认按日期倒序),最后一页只剩一条。总页数与本页条数可分别用 TotalPages、NumberOfElements 核对。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点,Windows。

情况 结果 是否报错
7 条、每页 3 条的普通分页 Pages(3);最后一页 Pages(1) 否
单页分页(7 条、每页 100) Pages(7),全部内容都在这一页 否
按组分页(.Paginate ($pages.GroupByDate "2006")) 空集合(len 为 0)——内容要从 PageGroups 取 否
空集合分页 空集合(len 为 0) 否
在 if / with 里判断 空集合判为假,可以据此隐藏列表 否
返回类型 page.Pages(页面集合),可继续交给 range、len、where 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 页面上条数和预期不符 拿到的是当前 pager 的子集,不是全站 用 TotalNumberOfElements 看总数、TotalPages 看页数
没报错但结果不对 按组分页时列表整块空白 按组分页的 pager 把内容放在 PageGroups 里,.Pages 为空 改用 PageGroups
没报错但结果不对 首页第一页内容不是最新的 待分页集合没有排序 在 Paginate 之前用 ByDate、ByWeight 等显式排序
报错看不懂 error calling Paginate: pagination not supported for this page 在普通内容页上调用 Paginate 只在 home / section / taxonomy / term 模板里分页

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