Params
返回给定页面前置元数据中定义的自定义参数映射。
这一页解决什么问题
.Params 是当前页面前置元数据的映射(maps.Params)。用它来读取作者在 front matter 里写的自定义字段,或者整体遍历它们(例如「把所有自定义字段渲染成表格」)。
注意它和 .Param 的两点差别:
.Params不会回退到站点参数,只看本页;.Params是映射,可以用range、index、.Params.a.b链式访问。
另外,映射里不只是 [params] 表的内容——实测它包含标准字段(title、date、draft、tags、weight 等)与页面参数,全部平铺在一起。
什么时候用,什么时候别用
该用:
- 读取页面前置元数据里的自定义字段(
.Params.author.name); - 遍历本页所有自定义字段(
range $k, $v := .Params); - 需要对
key做动态拼接时(index .Params $key)。
别用:
- 想要「页面没有就用站点配置」→ 用
.Param; - 想读站点参数 → 用
site.Params; - 想读分类法或菜单 → 那是
.GetTerms、.Site.Menus的活。
.Params 与 .Param 对照:
| 需求 | 用哪个 |
|---|---|
| 只看本页的 front matter | .Params |
| 页面缺失时回退到站点参数 | .Param "key" |
| 遍历本页全部自定义字段 | .Params |
| key 含连字符 | 两者都可以;.Params 必须用 index |
用法
举例来说,考虑下面这段前置元数据:
toml
title = 'Annual conference'
date = 2023-10-17T15:11:37-07:00
[params]
display_related = true
key-with-hyphens = 'must use index function'
[params.author]
email = 'jsmith@example.org'
name = 'John Smith'title 和 date 是标准的[前置元数据字段][],其余字段则由用户自定义。
go-html-template
{{ .Params.display_related }} → true
{{ .Params.author.email }} → jsmith@example.org
{{ .Params.author.name }} → John Smith在上面的模板示例中,每个 key 都是合法的标识符。例如,没有一个 key 含连字符。要访问不是合法标识符的 key,请使用 index 函数:
go-html-template
{{ index .Params "key-with-hyphens" }} → must use index function完整示例:读取嵌套参数与连字符 key
测试站 content/posts/post-1.md 的前置元数据:
toml
title = "第一篇"
date = 2024-01-01
weight = 10
tags = ["alpha", "beta"]
slug = "first-post"
key-with-hyphens = "must use index"
[params]
color = "red"
price = 42
[params.author]
email = "jsmith@example.org"
name = "John Smith"模板:
layouts/_default/single.htmlgo-html-template
<p>{{ .Params.color }}</p>
<p>{{ .Params.author.email }}</p>
<p>{{ index .Params "key-with-hyphens" }}</p>
<p>{{ .Params.price }} ({{ printf "%T" .Params.price }})</p>实测(Hugo 0.167.0)渲染 /posts/first-post/:
html
<p>red</p>
<p>jsmith@example.org</p>
<p>must use index</p>
<p>42 (int)</p>你应当看到什么:[params] 表里的值在 .Params 上直接可见(不需要写 .Params.params.color);[params.author] 变成了嵌套映射,可以链式访问;含连字符的 key 只能用 index;price 被解析成 int(TOML 里没加引号)。
实测 .Params 映射的实际内容(截取):
map[author:map[email:jsmith@example.org name:John Smith] categories:[news] color:red
date:2024-01-01 00:00:00 +0000 UTC draft:false key-with-hyphens:must use index
slug:first-post tags:[alpha beta] title:第一篇 weight:10]你应当看到什么:映射里同时有自定义字段(color、author、key-with-hyphens)和标准字段(title、date、draft、tags、weight)。所以 range .Params 会把它们一起列出来。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 访问不存在的 key | 返回 nil(用 with/default 兜底) |
否 |
| 访问嵌套映射的字段 | 正常(实测 .Params.author.email) |
否 |
| 连字符 key | 必须 index .Params "key-with-hyphens"(实测) |
否 |
| 标准字段 | 也在映射里(title、date、draft、tags、weight 等,实测) |
否 |
会把 [params] 表当成一层 |
不会:color 直接在顶层 |
否 |
| 站点参数 | 不包含(不会回退,这是与 .Param 的区别) |
否 |
| 返回类型 | maps.Params(可 range、可 index、可链式取值) |
否 |
更多排查入口见故障排查。