Params
返回前置元数据中定义的资源参数映射。
Params 方法用于page resource(页面资源),不适用于global resource(全局资源)或remote resource(远程资源)。
这一页解决什么问题
Params 让资源自己带着数据:alt 文本、版权、拍摄者、用途标签,都写在页面包的前置元数据里,模板只负责取出来。这样图片的说明文字与图片放在一起(同一个包),既不用散落到别处,也不会出现「改了图忘了改说明」。
它回答的问题是:这张图在前置元数据里被附加了哪些自定义信息?
取用方式有两种:.Params.alt(点号)或 index .Params "alt"(键名含特殊字符时更稳)。
什么时候用,什么时候别用
该用:
- 从页面包的前置元数据
[resources.params]里读自定义字段(alt、caption、credit等); - 遍历页面资源时按参数过滤或分组;
- 给
alt/loading之类可访问性属性提供内容。
别用:
- 资源是
assets/里的全局资源或远程资源 → 实测.Params是空映射(写法不报错,但什么也读不到)。全局资源的信息请放在data/、站点参数或页面前置元数据里; - 想读文件自身的元数据(Exif/GPS)→ 用
Meta; - 想读 HTTP 响应信息 → 用
Data; - 想要页面的参数 → 那是
.Params(页面对象上的),与资源无关,别混用。
用法
有如下内容结构:
tree
content/
├── posts/
│ ├── cats/
│ │ ├── images/
│ │ │ └── a.jpg
│ │ └── index.md
│ └── _index.md
└── _index.md以及如下前置元数据:
toml
title = 'Cats'
[[resources]]
src = 'images/a.jpg'
title = 'Felix the cat'
[resources.params]
alt = 'Photograph of black cat'
temperament = 'vicious'以及这个模板:
go-html-template
{{ with .Resources.Get "images/a.jpg" }}
<figure>
<img alt="{{ .Params.alt }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
<figcaption>{{ .Title }} is {{ .Params.temperament }}</figcaption>
</figure>
{{ end }}Hugo 渲染为:
html
<figure>
<img alt="Photograph of black cat" src="/posts/post-1/images/a.jpg" width="600" height="400">
<figcaption>Felix the cat is vicious</figcaption>
</figure>更多信息请参见页面资源一节。
完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows,最小站点。页面包 content/bundle/ 中,a.jpg 在前置元数据的 [[resources]] 条目里声明了 [resources.params],b.jpg 只是放在包里、没有声明。放进 layouts/_default/single.html:
layouts/_default/single.htmlgo-html-template
{{ with .Resources.Get "a.jpg" }}
<p>alt={{ .Params.alt }} temperament={{ .Params.temperament }}</p>
{{ end }}
{{ with .Resources.Get "b.jpg" }}
<p>b.jpg Params 为空:{{ not .Params }}</p>
{{ end }}Hugo 渲染为:
html
<p>alt=Photograph temperament=vicious</p>
<p>b.jpg Params 为空:true</p>你应当看到什么:参数只来自前置元数据里的 [resources.params]——a.jpg 写了就有,b.jpg 没写就是空映射(not .Params 为 true)。文件放在包里并不会自动带上参数。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
页面图片资源,声明了 [resources.params] |
该映射,实测 map[alt:Photograph temperament:vicious] |
否 |
| 页面图片资源,未声明 | 空映射(实测 not .Params 为 true) |
否 |
页面资源且类型为 page(包里的 .md) |
该片段页面的参数,实测 map[draft:false iscjklanguage:false title:Objectives] |
否 |
全局资源(resources.Get) |
空映射 | 否 |
读取不存在的键(.Params.nope) |
空值,with 判为假 |
否 |
resources.Get 找不到文件(nil) |
—— | 是:nil pointer evaluating resource.Resource.Params |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | alt 输出为空 |
资源在前置元数据里没有 [resources.params] 条目 |
按上游示例补 [[resources]] + src + [resources.params] |
| 没报错但结果不对 | 全局资源的 .Params 永远读不到 |
Params 只对页面资源有意义 |
把数据放在 data/、站点参数,或用页面前置元数据 |
| 没报错但结果不对 | 图片说明与图片不匹配 | 参数写在页面顶层,而不是 [resources.params] 下 |
参数必须嵌套在 [resources.params] 里 |
| 报错看不懂 | TOML 报结构错误 | [resources.params] 与 [[resources]] 的缩进/层级写错 |
对照上游示例:[[resources]] 是数组表,[resources.params] 是它的子表 |
更多排查入口见故障排查。