Data
为每种页面种类返回各自特有的数据对象。
这一页解决什么问题
Data 是分类法页与术语页专属的附加数据对象:这两类页面用它取得「当前是哪个分类法、哪个术语」,分类法页还能拿到全部术语及其页面数。写分类法相关模板时,这些值只能从这里取。
什么时候用,什么时候别用
该用:
- 分类法页需要列出所有术语(
.Data.Terms)并按页面数排序; - 术语页需要知道「当前术语是什么」「属于哪个分类法」(
.Data.Term/.Data.Singular/.Data.Plural)。
别用:
- 在普通内容页上取
.Data→ 实测返回nil,with判为假;要页面参数请用.Params/.Param; - 需要页面集合 → 在分类法 / 术语模板里优先用
Pages、RegularPages、RegularPagesRecursive;上游也提示不要再用老式的.Data.Pages; - 需要分类法对象的排序与计数 → 先用
.Data.Terms取到Taxonomy对象,再用分类法方法。
用法
Page 对象上的 Data 方法为每种页面种类返回各自特有的数据对象。
下面的示例基于如下项目配置:
toml
[taxonomies]
genre = 'genres'
author = 'authors'内容结构如下:
tree
content/
├── books/
│ ├── and-then-there-were-none.md --> genres: suspense
│ ├── death-on-the-nile.md --> genres: suspense
│ └── jamaica-inn.md --> genres: suspense, romance
│ └── pride-and-prejudice.md --> genres: romance
└── _index.md在分类法模板中
在分类法模板中的 Data 对象上使用这些方法。
Singular- (
string)返回分类法的单数名称。
go-html-template
{{ .Data.Singular }} → genrePlural- (
string)返回分类法的复数名称。
go-html-template
{{ .Data.Plural }} → genresTerms- (
page.Taxonomy)返回Taxonomy对象,它由术语映射以及各术语关联的加权页面组成。
go-html-template
{{ $taxonomyObject := .Data.Terms }}进一步了解分类法模板。
在术语模板中
在术语模板中的 Data 对象上使用这些方法。
Singular- (
string)返回分类法的单数名称。
go-html-template
{{ .Data.Singular }} → genrePlural- (
string)返回分类法的复数名称。
go-html-template
{{ .Data.Plural }} → genresTerm- (
string)返回术语名称。
go-html-template
{{ .Data.Term }} → suspense进一步了解术语模板。
完整示例:术语页与分类法页各取一次
最小站点:hugo.toml 使用默认的 tags 分类法;content/docs/guide/alpha.md 的前置元数据写 tags = ['hugo', 'docs']。
术语页模板 layouts/_default/term.html:
layouts/_default/term.htmlgo-html-template
{{ .Data.Term }}|{{ .Data.Plural }}|{{ .Data.Singular }}hugo --source <站点目录> --ignoreCache 构建后,/tags/hugo/ 输出:
html
hugo|tags|tag分类法页模板 layouts/_default/terms.html:
layouts/_default/terms.htmlgo-html-template
{{ range .Data.Terms.ByCount }}{{ .Term }}:{{ .Count }} {{ end }}/tags/ 输出:
html
docs:2 hugo:2 你应当看到什么:Singular 是单数名(tag),Plural 是配置里的键名(tags),Term 是当前术语的原始值(小写 hugo);.Data.Terms.ByCount 已按页面数排好序,可以直接遍历。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;默认 tags 分类法,两个术语各关联 2 个页面。
| 调用位置 | 结果 | 是否报错 |
|---|---|---|
分类法页 /tags/ |
.Data.Singular = tag、.Data.Plural = tags、.Data.Terms 可用 |
否 |
术语页 /tags/hugo/ |
额外有 .Data.Term = hugo;.Data.Pages 仍可用 |
否 |
| 普通内容页 | nil,with .Data 判为假 |
否 |
| 首页 | 非 nil(with 为真),但没有分类法相关的字段 |
否 |
| 返回类型 | page.Data |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但什么都没有 | 普通内容页上 with .Data 不执行 |
.Data 在普通页面上为 nil |
分类法相关取值只放在 taxonomy / term 模板里 |
| 没报错但结果不对 | .Data.Term 的写法与前置元数据不一致 |
Hugo 会把术语规范化为 URL 形式(小写、连字符) | 用 .Data.Term 的返回值,不要自行 lower 或 title |
| 主题很老 | .Data.Pages 能用但已过时 |
上游已建议改用 Pages / RegularPages |
改用 Pages 等方法 |
更多排查入口见故障排查。