Prev
返回页面集合中相对于给定页面的上一个页面。
这一页解决什么问题
做「上一篇 / 下一篇」导航。它是页面集合上的方法,参数是「当前页」,返回集合里与它相邻的另一个页面。
先记住这个反直觉的事实(实测):Prev 返回的是集合里后一个元素(下标 +1),Next 返回的是前一个元素(下标 −1)。所以在一个「按 weight 升序」的列表里,Prev 指向列表的下一项、Next 指向上一项。
到边界时返回 nil,不报错:集合的最后一个元素没有 Prev。模板里必须用 with 包住。
什么时候用,什么时候别用
该用:
- 文章底部的「上一篇 / 下一篇」;
- 只需要相邻页面、不需要位置信息时。
别用:
- 需要「第 N 篇 / 共 M 篇」→ 用
IndexOf; - 想限定在同一个 section 内 → 用页面级的
PrevInSection/NextInSection; - 想按自定义顺序导航 → 先把集合排成目标顺序再调
Prev。
用法
Hugo 按以下排序层级对页面集合排序,据此确定_下一个_和_上一个_页面:
| 字段 | 优先级 | 排序方向 |
|---|---|---|
weight |
1 | 降序 |
date |
2 | 降序 |
linkTitle |
3 | 降序 |
path |
4 | 降序 |
用于确定_下一个_和_上一个_页面的这个已排序页面集合独立于其他页面集合,因此可能导致意外的行为。
例如,有如下内容结构:
tree
content/
├── pages/
│ ├── _index.md
│ ├── page-1.md <-- front matter: weight = 10
│ ├── page-2.md <-- front matter: weight = 20
│ └── page-3.md <-- front matter: weight = 30
└── _index.md以及这些模板:
layouts/section.htmlgo-html-template
{{ range .Pages.ByWeight }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}layouts/page.htmlgo-html-template
{{ $pages := .CurrentSection.Pages.ByWeight }}
{{ with $pages.Prev . }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with $pages.Next . }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}当你访问 page-2 时:
Prev方法指向 page-3Next方法指向 page-1
要反转_下一个_和_上一个_的含义,可以把 Reverse 方法链式接在页面集合的定义后面:
layouts/page.htmlgo-html-template
{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}
{{ with $pages.Prev . }}
<a href="{{ .RelPermalink }}">Previous</a>
{{ end }}
{{ with $pages.Next . }}
<a href="{{ .RelPermalink }}">Next</a>
{{ end }}完整示例:链式 Reverse 让方向符合直觉
示例沿用本章首页的示例站点结构。集合 .CurrentSection.Pages 的顺序是 alpha bravo charlie delta。
layouts/_default/single.htmlgo-html-template
{{ $pages := .CurrentSection.Pages }}
<p>Prev:{{ with $pages.Prev . }}{{ .LinkTitle }}{{ else }}(无){{ end }}</p>
<p>Next:{{ with $pages.Next . }}{{ .LinkTitle }}{{ else }}(无){{ end }}</p>
{{ $reversed := .CurrentSection.Pages.ByWeight.Reverse }}
<p>反转后 Prev:{{ with $reversed.Prev . }}{{ .LinkTitle }}{{ else }}(无){{ end }}</p>
<p>反转后 Next:{{ with $reversed.Next . }}{{ .LinkTitle }}{{ else }}(无){{ end }}</p>post-2(bravo)渲染为:
html
<p>Prev:charlie</p>
<p>Next:alpha</p>
<p>反转后 Prev:alpha</p>
<p>反转后 Next:charlie</p>你应当看到什么:同一个页面,集合反转后 Prev/Next 的结果互换了(charlie ↔ alpha);post-1(alpha)在未反转时 Next 为空、post-4(delta)在未反转时 Prev 为空——首尾的 nil 由 with 兜住。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'en-US'、timeZone = 'UTC'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 集合中间的页面 | 返回相邻的单个页面(printf "%T" 实测为页面类型,不是集合) |
否 |
| 集合的最后一个元素 | nil → with 走 else |
否 |
集合的第一个元素(Prev) |
返回第二个元素 | 否 |
| 传入的页面不在该集合里 | nil(实测用别的 section 的页面查询得到空) |
否 |
| 空集合 | nil |
否 |
对返回值用 len |
—— | 是:len of type nil pointer / len of type hugolib.pageState |
参数不是页面(Prev "x") |
—— | 是:can't handle "x" for arg of type page.Page |
| 返回类型 | 签名写 page.Pages,实测是单个页面(与 Next 一致) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 末页渲染出空链接 <a href=""> |
没用 with 包住 nil |
{{ with $pages.Prev . }}…{{ end }} |
| 没报错但结果不对 | 「上一篇」指向了后面的文章 | Prev 指向集合的下一个元素 |
换算方向或链 .Reverse,见完整示例 |
| 报错看不懂 | len of type nil pointer |
对返回值用了 len(返回的是单个页面) |
用 with;要位置信息用 IndexOf |
| 报错看不懂 | can't handle "x" for arg of type page.Page |
参数传成了字符串 | 传当前页面 . |
| 没报错但结果不对 | 导航跨越了不同 section | .CurrentSection.Pages 只含本 section,改用 site.RegularPages 就是全站范围 |
先想清楚「相邻」的范围,再选集合 |
更多排查入口见故障排查。