文档章节
局部模板函数
使用这些函数调用局部模板(partial)。
这一页解决什么问题
模板里总会有反复出现的片段:<head>、页脚、导航、卡片。Go 模板本身没有「包含另一个文件」的语法,Hugo 的答案是局部模板(partial):把片段写进 layouts/_partials/,再用本节的两个函数调用它。
本节只有两个函数,区别只有一条——要不要缓存渲染结果:
partials.Include(别名partial):每次都重新渲染;partials.IncludeCached(别名partialCached):同一个「变体」只渲染一次,之后复用缓存。
什么时候用,什么时候别用
| 你的情况 | 用哪个 |
|---|---|
| 片段输出依赖当前页面,每页都不同 | partials.Include(partial) |
| 片段在一批页面里输出完全相同,且渲染代价高 | partials.IncludeCached(partialCached) |
| 需要从片段里「取值」而不是取 HTML | 两者都能配合 return 语句,见 partials.Include |
把片段放在子目录里,想用 ./、../ 引用同级文件 |
partials.Include,见其「相对路径」一节 |
别用:
- 想复用内容(Markdown 正文片段)而不是模板 → 用短代码(shortcode);
- 只想把一段 HTML 从模板里挪出去,但仍要逐页重新渲染 → 用普通
partial就够了,加缓存只会引入「缓存键选错」的风险; - 想按页面类型自动挑选模板文件 → 那是模板查找顺序,与 partial 无关。
完整示例:一个普通 partial 与一个缓存 partial
站点里放两个局部模板——一个把上下文里传进来的数字求平均,一个只用来观察「渲染了几次」:
layouts/_partials/average.htmlgo-html-template
{{ $sum := 0 }}
{{ range . }}{{ $sum = math.Add $sum . }}{{ end }}
{{ return math.Div $sum (len .) }}layouts/_partials/footer.htmlgo-html-template
<footer>Teach demo footer</footer>layouts/_partials/count.htmlgo-html-template
{{ math.Counter }}在首页模板里这样调用:
layouts/index.htmlgo-html-template
A1=[{{ partial "average.html" (slice 1 6 7 42) }}] type={{ printf "%T" (partial "average.html" (slice 1 6 7 42)) }}
A2=[{{ partial "footer.html" }}] type={{ printf "%T" (partial "footer.html") }}
A5=[{{ partialCached "count.html" . }}][{{ partialCached "count.html" . }}][{{ partialCached "count.html" . "A" }}][{{ partialCached "count.html" . "A" }}][{{ partialCached "count.html" . "B" }}]Hugo 0.167.0 渲染为:
html
A1=[14] type=int64
A2=[<footer>Teach demo footer</footer>
] type=template.HTML
A5=[1
][1
][2
][2
][3
]你应当看到什么:
A1说明带return的 partial 可以返回任意类型——这里math.Div返回int64,所以printf "%T"不是template.HTML;A2说明没有return时返回template.HTML,而且局部模板文件末尾的换行会一起进入结果(所以输出里有换行);A5是缓存的关键:同一变体连续调用两次都是1(第二次直接命中缓存,math.Counter没有被再次求值);换成变体"A"才重新渲染得到2,变体"B"得到3。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。细则见两个函数页,这里给出容易踩的几条:
| 情况 | 结果 | 是否报错 |
|---|---|---|
局部模板里没有 return |
返回 template.HTML 字符串(不是普通 string) |
否 |
局部模板里有 return |
返回该表达式的类型(实测 math.Div 得到 int64) |
否 |
NAME 指向不存在的模板 |
构建失败:partial "missing.html" not found |
是 |
从非局部模板调用 partial "./x.html" |
构建失败:can only be used from within a partial |
是 |
省略 CONTEXT(partial "x.html") |
允许;模板里 . 为 nil |
否 |
partialCached 只传 LAYOUT |
构建失败:wrong number of args for partialCached |
是 |
读完本章你应该能够
- 说清
partial与partialCached的唯一区别,以及缓存键(变体参数)是怎么决定的 - 用
dict给 partial 传多个参数,并用return从 partial 取回非 HTML 的值 - 在 partial 内部用
./、../引用同级或上级局部模板 - 判断一个片段该不该加缓存,以及变体参数该选什么
阅读顺序
- partials.Include —— 先掌握调用、上下文与相对路径;
- partials.IncludeCached —— 再学缓存与变体参数。
更多排查入口见故障排查。
本章内容
- partials.Include 执行给定模板,可选择性地传入上下文。若局部模板包含 return 语句,则返回该语句的值,否则返回渲染输出。 (今天)
- partials.IncludeCached 执行给定模板并缓存结果,可选择性地传入一个或多个变体键。若局部模板包含 return 语句,则返回该语句的值,否则返回渲染输出。 (今天)