Pages

Limit

返回给定页面集合中的前 N 个页面。

签名
PAGES.Limit N
返回类型
page.Pages

这一页解决什么问题

从集合里取前 N 个:首页「最新 5 篇」、「热门 3 条」这类场景。

它取的是集合当前顺序的前 N 个,所以通常先排序再限量:

.Pages.ByDate.Reverse | first 5      ← 逻辑上的「最新 5 篇」
.Pages.ByDate.Reverse.Limit 5        ← 写法之一

N 大于集合长度时返回整个集合(不报错);N 为 0 时返回空集合;N 为负数会直接让构建失败(实测)。

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

该用:

  • 「只要前几条」的摘要区,避免在模板里写计数器;
  • 与大集合配合减少渲染量(.RegularPages 上千页时尤其实用)。

别用:

用法

go-html-template
{{ range .Pages.Limit 3 }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

完整示例:排序后取前几条

示例沿用本章首页的示例站点结构(posts 的默认顺序是 alpha bravo charlie delta)。

layouts/_default/list.htmlgo-html-template
默认顺序取 2:{{ range .Pages.Limit 2 }}{{ .LinkTitle }} {{ end }}
最新 2 篇:{{ range .Pages.ByDate.Reverse.Limit 2 }}{{ .LinkTitle }} {{ end }}
取 0 条:{{ range .Pages.Limit 0 }}{{ .LinkTitle }} {{ end }}
超出长度:{{ range .Pages.Limit 100 }}{{ .LinkTitle }} {{ end }}

Hugo 渲染为:

html
默认顺序取 2:alpha bravo 
最新 2 篇:delta bravo 
取 0 条:
超出长度:alpha bravo charlie delta 

你应当看到什么:第一行是默认顺序的前两条(alpha、bravo);第二行先 ByDate.Reverse 再限量,拿到真正的最新两篇(delta、bravo);Limit 0 输出为空(不报错);Limit 100 返回全部四页(不报错)。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'en-US'、timeZone = 'UTC'),Windows。

情况 结果 是否报错
Limit 2(集合 4 页) 默认顺序的前两页 否
Limit 0 空集合:range 无输出,Len 为 0 否
Limit 100(超出长度) 整个集合(4 页全给) 否
Limit -1 —— 是:error calling Limit: runtime error: slice bounds out of range [:-1]
N 是字符串(Limit "2") —— 是:expected integer; found "2"
N 是小数(Limit 2.5) —— 是:expected integer; found 2.5
空集合上 Limit 3 空集合,无输出 否
返回类型 page.Pages(可继续 Reverse、range) 否

常见坑

类别 症状 真因 怎么修
报错看不懂 slice bounds out of range [:-1] N 是负数(常见于由变量算出来的值) 先兜底:{{ $n := cond (gt $n 0) $n 1 }},再传给 Limit
报错看不懂 expected integer; found "2" N 从配置/参数里来,是字符串 用 cast.ToInt 转换
没报错但结果不对 「最新 5 篇」不是最新的 忘了先排序,取的是集合默认顺序 先 .ByDate.Reverse(或 .ByWeight)再 Limit
没报错但结果不对 列表在分页第 2 页时内容重复 Limit 与分页器混用 分页交给分页器;Limit 只用于「就取前几条」

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