Hugo collections.Dictionary(dict)函数完全指南:从键值对到嵌套数据结构
Hugo collections.Dictionary(dict)函数完全指南:从键值对到嵌套数据结构
collections.Dictionary(模板别名 dict)是 Hugo 模板语言中最常用的集合函数之一,用于从一个或多个键值对创建 map[string]any 类型的映射结构。无论是为模板组织参数、构造前端配置数据,还是配合 index、merge、where、querify 等函数构建复杂的数据管道,dict 都是绕不开的基础工具。读完本文,你将掌握 dict 的全部调用形式、嵌套结构的构建原理、参数约束与错误场景,并了解其在 Hugo 源码中的实现机制。
函数概览与基本用法
collections.Dictionary 的官方签名与元信息如下(见 Dictionary.md):
- 签名:
collections.Dictionary [VALUE...] - 别名:
dict - 返回类型:
map[string]any - 历史路径:
/functions/dict(旧版文档地址)
调用时,将键值对作为逐个的独立参数传入。例如:
{{ $m := dict "a" 1 "b" 2 }}
上述表达式生成如下数据结构:
{
"a": 1,
"b": 2
}
dict 的典型应用场景包括:
- 为 partial 模板传参:
{{ partial "card.html" (dict "title" .Title "url" .Permalink) }}; - 在模板内构造临时数据对象,再配合
index取值、merge合并、where过滤; - 作为
querify、safeHTML等函数的输入,将结构化数据转换为查询串或页面内容。
使用 []string 键创建嵌套结构
dict 的 key 参数既可以是 string,也可以是 []string。当键为字符串切片时,切片中的每个元素会依次成为嵌套层级,这一特性非常适合构造深层数据结构。例如:
{{ $m := dict (slice "a" "b" "c") "value" }}
上述表达式生成如下嵌套结构:
{
"a": {
"b": {
"c": "value"
}
}
}
也就是说,[]string{"a", "b", "c"} 会被解释为路径 a → b → c,最终在 c 这个层级上存放值 "value"。若希望在同一个嵌套路径的不同叶子节点上分别赋值,可以多次传入相同的键前缀,例如:
{{ $m := dict (slice "a" "b") "v1" (slice "a" "c") "v2" }}
结果中 a 下同时存在 b 与 c 两个子键。这种能力让 dict 可以直接在模板中构建原本需要多层嵌套才能表达的配置对象。
创建空映射
当不传入任何参数时,dict 返回一个空映射:
{{ $m := dict }}
这在与 default 等函数配合时很有用。例如在 compare/Default.md 中展示的行为:{{ dict | default 42 }} 会得到 42,因为空映射在 Hugo 的布尔判定中被视为“空值”;而 {{ dict "k" "v" | default 42 }} 则保持 map[k:v] 不变。
源码实现:dict 的底层原理
collections.Dictionary 的实现位于 tpl/collections/collections.go#L157-L194。其核心逻辑可以概括为三步:
-
参数数量校验:所有参数必须成对出现,即参数总数必须为偶数。若
len(values)%2 != 0,函数直接返回错误"invalid dictionary call"。这保证了每个键都有对应的值。 -
键类型分支处理:
- 当键是
string时,直接作为当前层级的键名; - 当键是
[]string时,遍历切片中除最后一个元素外的所有元素,逐层向下创建或复用嵌套的map[string]any,最后把最后一个元素作为叶子键名; - 当键是其他类型(如数字、布尔值等)时,返回错误
"invalid dictionary key"。
- 当键是
-
写入值:将
values[i+1]写入最终定位到的键名下,循环处理所有键值对后返回根映射。
从源码结构看,嵌套的实现方式是“边遍历边创建中间 map 并就地复用”——如果某个中间层级已经存在(例如多次使用相同前缀的 []string 键),则继续在该层级下追加,而不会覆盖已有内容,这与 Go 中嵌套 map 的语义一致。
别名与注册机制
dict 是 collections.Dictionary 的官方别名,二者完全等价。注册逻辑位于 tpl/collections/init.go#L68-L71:
ns.AddMethodMapping(ctx.Dictionary,
[]string{"dict"},
[][2]string{},
)
AddMethodMapping 会将 Dictionary 方法及其别名 dict 同时注册到 Hugo 的模板函数命名空间中,因此在任何模板中都可以直接使用 {{ dict ... }},无需任何 import。这也是 dict 在 Hugo 生态中普及度极高的重要原因。
测试用例验证
dict 的行为在 tpl/collections/collections_test.go#L178-L213 中有系统的测试覆盖,主要用例包括:
| 输入 | 期望结果 |
|---|---|
"a", "b" |
map[string]any{"a": "b"} |
[]string{"a","b"}, "c" |
map[string]any{"a": map[string]any{"b": "c"}} |
[]string{"a","b"},"c", []string{"a","b2"},"c2", "b","c" |
{"a": {"b": "c", "b2": "c2"}, "b": "c"} |
"a", 12, "b", []int{4} |
{"a": 12, "b": []int{4}} |
5, "b"(非法键) |
返回错误 |
"a", "b", "c"(奇数参数) |
返回错误 |
其中两个错误用例恰好对应源码中的两类校验:非法键类型(数字键)与参数不成对(奇数个参数)。值本身可以是任意类型——数字、切片、甚至另一个 dict 产生的 map,均可作为值存储。
与其他集合函数的协同使用
dict 产出的 map[string]any 是 Hugo 集合函数体系中的通用数据结构,常与其他函数联动:
- 取值:配合
index读取嵌套值,例如 IndexFunction.md 中{{ index $m "c" "d" }}读取嵌套字典中的d键; - 合并:
merge可将多个dict合并,例如 Merge.md 中通过merge $m1 $m2 $m3实现逐层覆盖合并(深层键按层级递归合并); - 序列化:
querify可直接接收dict创建的结构化数据生成 URL 查询串,其源码 tpl/collections/querify.go#L38 中明确注释map[string]any: // created with collections.Dictionary,说明querify正是以dict的输出作为标准输入; - 格式化:
delimit配合dict与sort可实现对键值对的排序输出,参考 Delimit.md; - 过滤:与
where、sort等函数组合,可对字典数据做条件筛选与排序。
常见错误与注意事项
- 参数必须成对:
{{ dict "a" "b" "c" }}会触发"invalid dictionary call"错误,因为参数个数为奇数; - 键类型受限:键只能是
string或[]string,传入数字等类型会触发"invalid dictionary key"错误,需要先用string等函数转换; - 空切片键:若传入空的
[]string{},会因为没有可用的叶子键名而无法写入(实现上取v[len(v)-1]会越界),实际使用中应保证切片至少包含一个元素; - 结果类型固定:返回值恒为
map[string]any,模板中可放心用range、index等语法操作,无需类型断言。
小结
collections.Dictionary(dict)虽是一个基础函数,却是 Hugo 模板数据组织的基石:普通字符串键支持扁平键值对,<a href="https://link.gitcode.com/i/50cb6796b2e523f9c2d8a18f335102a3" target="_blank">]string 键支持任意深度的嵌套结构,空参数支持创建空映射。结合 [collections.go 的源码与 collections_test.go 的测试用例,可以清晰看到其参数校验、键类型处理和嵌套展开的全部细节。掌握 dict 之后,再配合 index、merge、querify、where 等集合函数,即可在模板中高效构建和消费复杂的数据结构。