Param
返回给定 key 对应的站点参数。
这一页解决什么问题
Param 用一个字符串去查站点参数。相比直接写 .Site.Params.foo,它多解决三件事:
- key 可以来自变量(循环、partial 参数、数据文件),不必写死在模板里;
- key 不是合法标识符时也能取(例如
copyright-year含连字符); - 可以用点号访问嵌套参数:
.Site.Param "author.name"。
它返回的值类型取决于配置里写的是什么(any),所以取不到时不报错,只得到空值。
什么时候用,什么时候别用
该用:
- key 是动态的:
{{ range $key := slice "subtitle" "tagline" }}{{ $.Site.Param $key }}{{ end }}; - key 含连字符或点号等不能直接用链式语法的情况;
- 想用一个统一的调用点去读「站点参数 + 页面参数」——页面上的
Param方法语义相同(见 methods/page)。
别用:
- key 固定且是合法标识符 → 直接写
.Site.Params.subtitle,少一层间接,拼错时也更容易发现; - 读页面自己的参数 → 用页面的
.Params/.Param; - 期待「取不到就报错」→ 实测返回
nil(打印为空),拼错 key 的模板会静默失去内容。
用法
Site 对象上的 Param 方法是一个便捷方法,用于返回项目配置中某个用户自定义参数的值。
toml
[params]
display_toc = truego-html-template
{{ .Site.Param "display_toc" }} → true上面的写法等价于下面任意一种:
go-html-template
{{ .Site.Params.display_toc }}
{{ index .Site.Params "display_toc" }}完整示例(实测)
配置:
toml
[params]
display_toc = true
copyright-year = '2023'
[params.author]
email = 'jsmith@example.org'
name = 'John Smith'模板:
layouts/_partials/meta.htmlgo-html-template
<p>display_toc:{{ .Site.Param "display_toc" }}</p>
<p>嵌套值:{{ .Site.Param "author.name" }}</p>
<p>带连字符的 key:{{ .Site.Param "copyright-year" }}</p>
<p>写错的 key:[{{ .Site.Param "display_tocs" }}]</p>Hugo 渲染为:
html
<p>display_toc:true</p>
<p>嵌套值:John Smith</p>
<p>带连字符的 key:2023</p>
<p>写错的 key:[]</p>你应当看到什么:点号可以一路取到嵌套映射(author.name),带连字符的 key 也能直接传字符串;而拼错的 key 不报错,只是渲染成空——把结果放进方括号或配合 with / default 使用,能让这类错误显形。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,配置如上,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
布尔参数(display_toc) |
true(bool) |
否 |
字符串参数(copyright-year) |
'2023'(string) |
否 |
嵌套 key("author.name") |
John Smith,点号可用 |
否 |
取整个嵌套映射("author") |
map[email:jsmith@example.org name:John Smith] |
否 |
| 不存在的 key | nil(打印为空,with 判为假) |
否 |
| 返回值类型 | any(实际类型随配置而定) |
否 |
传入非字符串 key(如 1) |
nil(打印为空),不报错 |
否 |