GroupBy
返回给定页面集合按指定字段升序分组后的结果。
这一页解决什么问题
把页面集合分组:按某个字段的取值切成若干组,每组带一个 .Key(组名)和自己的 .Pages(组内页面集合)。按月归档、按分区列目录、按类型分栏都用它。
返回类型是 page.PagesGroup,range 出来的是 page.PageGroup 对象(实测类型 page.PageGroup),它的 .Key 是 string,.Pages 是 page.Pages。
FIELD 是页面上的字段名(Section、Type、Kind 等),不是任意参数名——要按自定义参数分组请用 GroupByParam。
什么时候用,什么时候别用
该用:
- 按
Section、Type、Kind这类内置字段做分栏/归档; - 需要「组名 + 组内页面」的两层结构。
别用:
- 按日期分组 → 用
GroupByDate及同族的GroupByLastmod/GroupByExpiryDate/GroupByPublishDate(它们能把一个时间点格式化成2024-01这样的组名); - 按自定义参数分组 → 用
GroupByParam(注意:缺少该参数的页面会被丢掉); - 只想排序 → 用
ByWeight等; - 只想筛选 → 用
collections.Where。
用法
可选的排序顺序用 asc 指定升序,或用 desc 指定降序。
go-html-template
{{ range .Pages.GroupBy "Section" }}
<p>{{ .Key }}</p>
<ul>
{{ range .Pages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}要把各组改为降序排列:
go-html-template
{{ range .Pages.GroupBy "Section" "desc" }}
<p>{{ .Key }}</p>
<ul>
{{ range .Pages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}完整示例:按 Section 分组
示例沿用本章首页的示例站点结构。在首页模板里用 site.RegularPages 才能同时拿到 books 与 posts 两个分区(在 posts 的 section 模板里,.Pages 全是 posts,只会得到一组):
layouts/index.htmlgo-html-template
{{ range site.RegularPages.GroupBy "Section" }}{{ .Key }}({{ .Pages.Len }}):{{ range .Pages }}{{ .LinkTitle }} {{ end }}|{{ end }}Hugo 渲染为:
html
books(2):book-one book-two |posts(4):alpha bravo charlie delta |你应当看到什么:两组,组名分别是 books、posts(升序);.Pages.Len 给出组内数量(2 与 4);组内顺序沿用页面集合的默认顺序。把 "desc" 传进去,两组顺序变成 posts、books。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'en-US'、timeZone = 'UTC'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
GroupBy "Section"(两个分区) |
2 组,升序 books、posts;组内 .Pages 可继续接排序方法 |
否 |
| 元素类型 | 组对象是 page.PageGroup;.Key 是 string;.Pages 是 page.Pages |
否 |
传 "desc" |
组顺序反转(posts、books) |
否 |
传其它字符串("up") |
不报错,按默认(升序)处理(实测与不传一致) | 否 |
字段名不存在(GroupBy "nope") |
—— | 是:error calling GroupBy: reflect: Elem of invalid type page.Page |
GroupBy "Kind" |
可用:一页一组名为 page 的组(实测 6 页同组) |
否 |
| 空集合 | 得到空的分组切片;range 无输出,在 if 里判为假 |
否 |
| 某组内只有一个页面 | 正常,.Pages.Len 为 1 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | reflect: Elem of invalid type page.Page |
FIELD 写的不是页面字段名(例如写成了 "nope",或用它去分自定义参数) |
只用页面上的字段名;自定义参数改用 GroupByParam |
| 没报错但结果不对 | 只有一个组,组名是当前 section | 用 .Pages 分组时集合只含本 section 的页面 |
需要跨分区就用 site.RegularPages 或 site.Pages |
| 没报错但结果不对 | 传了拼错的排序词却没报错,顺序也没变 | 无法识别的排序值被忽略,退回默认顺序 | 只写 asc / desc,写错不会提示 |
| 没报错但结果不对 | 组内页面顺序不是自己想要的 | 分组只决定「怎么分组」,组内顺序沿用原集合 | 在 .Pages 上再调排序方法,例如 range .Pages.ByTitle |
更多排查入口见故障排查。