collections.Sort
按指定的 key 与顺序重排给定集合,返回排序后的映射或切片。
这一页解决什么问题
模板要按某个字段排序时用它:按日期、标题、权重、价格排页面或 dict 列表。它有两种典型输入:
- 标量切片(
["b" "a" "c"]、[3 1 2]):默认升序,KEY可省略; - 映射或「映射构成的切片」(页面集合、
dict列表):必须给出KEY,Hugo 按该 key 的值排序。
最容易踩的一脚:想对标量切片降序时,不能只写 "desc"——那个位置是 KEY,实测会直接报错。正确写法是把字面量 value 作为 KEY 补上:sort $slice "value" "desc"。
什么时候用,什么时候别用
该用:
- 数据切片按字段排序(
dict列表、hugo.Data读入的数据); - 配置里的标量列表排序。
别用:
- 排序页面集合 → 优先用页面集合自带的排序方法(见
methods/pages),它们更贴合 Page,且能直接与分组、分页配合; - 想分组 → 用页面集合的分组方法(如
PAGES.GroupBy); - 只是想要「最近的 N 篇」而已 → 集合已排序时直接用
collections.First; - 想反转既有顺序 → 用
collections.Reverse,sort会重新比较,不是简单倒序。
用法
对切片做升序排序时 KEY 可以省略,其他情况则必填。排序切片时,请用字面量 value 代替 KEY。参见下面的示例。
ORDER 可以是 asc(升序)或 desc(降序)。默认排序顺序为升序。
排序切片
下面的示例假定项目配置为:
toml
[params]
grades = ['b','a','c']升序
用下面任一写法按升序对切片元素排序:
go-html-template
{{ sort site.Params.grades }} → [a b c]
{{ sort site.Params.grades "value" "asc" }} → [a b c]上面的示例中,value 就是代表切片元素值的 KEY。
降序
按降序对切片元素排序:
go-html-template
{{ sort site.Params.grades "value" "desc" }} → [c b a]上面的示例中,value 就是代表切片元素值的 KEY。
排序映射
下面的示例假定项目配置为:
toml
[params.authors.a]
firstName = 'Marius'
lastName = 'Pontmercy'
[params.authors.b]
firstName = 'Victor'
lastName = 'Hugo'
[params.authors.c]
firstName = 'Jean'
lastName = 'Valjean'升序
用下面任一写法按升序对映射对象排序:
go-html-template
{{ range sort site.Params.authors "firstname" }}
{{ .firstName }}
{{ end }}
{{ range sort site.Params.authors "firstname" "asc" }}
{{ .firstName }}
{{ end }}它们输出:
Jean Marius Victor降序
按降序对映射对象排序:
go-html-template
{{ range sort site.Params.authors "firstname" "desc" }}
{{ .firstName }}
{{ end }}输出:
Victor Marius Jean移除第一层 key
Hugo 在排序映射时会移除第一层的 key。
原始映射:
json
{
"felix": {
"breed": "malicious",
"type": "cat"
},
"spot": {
"breed": "boxer",
"type": "dog"
}
}排序之后:
json
[
{
"breed": "malicious",
"type": "cat"
},
{
"breed": "boxer",
"type": "dog"
}
]排序页面集合
在这个刻意构造的示例中,按 .Type 降序排序站点的普通页面:
go-html-template
{{ range sort site.RegularPages "Type" "desc" }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}完整示例:标量切片与 dict 列表
layouts/_partials/sorted.htmlgo-html-template
{{ $nums := slice 3 1 2 }}
<p>默认升序:{{ sort $nums }}</p>
<p>显式 asc:{{ sort $nums "value" "asc" }}</p>
<p>降序:{{ sort $nums "value" "desc" }}</p>
<p>大小写混合:{{ sort (slice "b" "A" "a") }}</p>
{{ $items := slice (dict "n" 2) (dict "n" 1) (dict "n" 3) }}
<p>按 n 升序:{{ sort $items "n" }}</p>
<p>按 n 降序:{{ sort $items "n" "desc" }}</p>Hugo 渲染为:
html
<p>默认升序:[1 2 3]</p>
<p>显式 asc:[1 2 3]</p>
<p>降序:[3 2 1]</p>
<p>大小写混合:[a A b]</p>
<p>按 n 升序:[map[n:1] map[n:2] map[n:3]]</p>
<p>按 n 降序:[map[n:3] map[n:2] map[n:1]]</p>你应当看到什么:标量切片省略 KEY 时按升序;降序必须写成 "value" "desc";dict 列表按 KEY 排序;字符串排序不区分大小写([a A b],大写不会整体排在小写后面)。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
标量切片,省略 KEY |
升序 | 否 |
标量切片,"value" "desc" |
降序(实测 [3 2 1]) |
否 |
标量切片,只写 "desc" |
—— | 是:error calling sort: desc is neither a struct field, a method nor a map element of type int |
| 输入是字符串 | —— | 是:error calling sort: can't sort string |
KEY 在元素里不存在 |
不报错,元素保持原顺序 | 否 |
输入是映射且省略 KEY |
返回按 key 排序后的值列表(第一层 key 被移除),实测 sort (dict "b" 2 "a" 1) 得 [1 2] |
否 |
输入是映射却写 "desc" |
—— | 是:error calling sort: desc is neither a struct field, a method nor a map element of type interface {} |
| 返回类型 | 与输入同类(签名写作 any);页面集合仍是页面集合 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | desc is neither a struct field, a method nor a map element |
对标量切片降序时漏了 KEY,"desc" 被当成字段名 |
写成 sort $slice "value" "desc" |
| 报错看不懂 | can't sort string |
把字符串当集合传了 | 先 split 成切片 |
| 没报错但结果不对 | 排序没有变化 | KEY 拼错或大小写不符(映射的 KEY 必须小写,上游已说明) |
先打印一个元素确认字段名 |
| 没报错但结果不对 | 排序结果里第一层 key 不见了 | 排序映射时 Hugo 会移除第一层 key(上游已说明) | 想保留 key 就改成对 dict 列表排序,或 range 自己拼 |
| 没报错但结果不对 | 页面顺序和 .ByDate 等方法不一致 |
页面集合应当优先用自带排序方法 | 改用 methods/pages 里的排序方法 |
更多排查入口见故障排查。