page
返回当前页面的 Page 对象,在任何上下文中都可访问。
这一页解决什么问题
模板越往深处走(局部模板、渲染钩子、被 range 包住的代码),越容易拿不到当前页面的 Page 对象。全局 page 函数让「当前页面」在任何位置都能取到:{{ page.Title }}、{{ page.Params.xxx }}。
但它的语义有个关键前提:page 返回的是传入顶层模板的那个 Page 对象,而不是「正在迭代的那个页面」。所以它既能在嵌套模板里救急,也能在循环里给出「错误」的答案——本页「示例」演示的正是后者。
什么时候用,什么时候别用
该用:
- 深层局部模板 / 渲染钩子里需要当前页面,但上下文里没有
.; - 顶部模板里用
page让写法统一(page.Params.x与.Params.x等价)。
别用:
- 在
range循环里想取「当前被迭代的页面」→ 用.(迭代元素本身),page会一直返回顶层页面; - 在短代码、被短代码调用的局部模板、以及
partialCached缓存的局部模板里 → 上游明确要求不要用(缓存会导致结果错乱); - 多主机(multihost)的 sitemap 模板 → 上游指出这是顶层模板不传
Page的唯一例外。
用法
在上下文接收 Page 对象的模板顶层,以下写法等价:
{{ .Params.foo }}
{{ .Page.Params.foo }}
{{ page.Params.foo }}当上下文里没有 Page 对象时,可以使用全局 page 函数:
{{ page.Params.foo }}Hugo 几乎总是将 Page 作为数据上下文传给顶层模板(例如 baseof.html)。唯一的例外是多主机(multihost)的 sitemap 模板。这意味着你可以在模板中用 . 访问当前页面。
然而,当模板深度嵌套在局部模板或渲染钩子中时,访问 Page 对象并不总是可行或方便。
使用全局 page 函数可以在任何模板的任何位置访问 Page 对象。
示例
以下示例演示使用全局 page 函数时常见的陷阱。
注意顶层上下文
全局 page 函数访问的是传入顶层模板的 Page 对象。
有这样的内容结构:
content/
├── posts/
│ ├── post-1.md
│ ├── post-2.md
│ └── post-3.md
└── _index.md <-- title is "My Home Page"以及 home 模板中的这段代码:
{{ range site.Sections }}
{{ range .Pages }}
{{ page.Title }}
{{ end }}
{{ end }}渲染输出将会是:
My Home Page
My Home Page
My Home Page在上面的示例中,全局 page 函数访问的是传入 home 模板的 Page 对象,而不是被迭代页面的 Page 对象。
注意缓存
不要在以下位置使用全局 page 函数:
- 短代码
- 由短代码调用的局部模板
- 被
partialCached函数缓存的局部模板
Hugo 会缓存渲染后的短代码。如果在短代码中使用全局 page 函数,而页面内容要在两个或更多模板中渲染,那么缓存的短代码可能是不正确的。
看看这个 section 模板:
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ end }}当你调用 Summary 方法时,Hugo 会渲染页面内容,其中包括短代码。此时,在短代码内部,全局 page 函数访问的是 section 页面的 Page 对象,而不是内容页面的。
如果 Hugo 先渲染 section 页面再渲染内容页面,缓存的已渲染短代码就会不正确。由于并发的原因,你无法控制渲染顺序。
完整示例(实测)
最小站点:title = "Teach Test",content/posts/post-1.md、post-2.md 两篇文章。
{{ page.Title }}
{{ range site.RegularPages }}{{ page.Title }}/{{ .Title }}; {{ end }}Hugo 0.167.0 实测渲染:
Teach Test
Teach Test/Post Two; Teach Test/Post One; 你应当看到什么:第一行是首页标题;循环里 page.Title 每一轮都还是首页标题(Teach Test),只有 .Title 才依次是 Post Two、Post One。这就是上游「注意顶层上下文」一节要提醒的陷阱。
在局部模板里也一样——实测从 layouts/index.html 调用的局部模板中,page.Title 与 .Title 都取到首页:
PAGE-IN-PARTIAL: page=Teach Test dot=Teach Test返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 顶层模板上下文是页面 | page 与该页面对象相同(page.Title 与 .Title 一致) |
否 |
在 range 循环内 |
仍返回顶层页面(实测两轮都得到首页标题) | 否 |
| 在普通局部模板内 | 返回顶层页面对象 | 否 |
在短代码 / 短代码调用的局部模板 / partialCached 缓存的局部模板内 |
上游要求不要使用(缓存结果可能不正确) | 否(但结果可能错) |
| 返回类型 | page.Page |
否 |