Store
返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前页面。
这一页解决什么问题
模板本身是「函数式」的:局部变量在模板结束就没了,partial 之间也没法直接传值。.Store 提供一个页面作用域的键值存储,让短代码、渲染钩子、partial 之间可以传递数据——例如短代码收集了一组条目,父模板再取出来渲染目录。
它是 .Scratch 的正式替代品(v0.138.0 起 Scratch 成为 Store 的别名)。新代码写 .Store。
什么时候用,什么时候别用
该用:
- 短代码/渲染钩子里
Set,父模板里Get; - 用
Add累加(数字求和、字符串拼接、切片追加); - 用
SetInMap+GetSortedMapValues维护「有序映射」。
别用:
- 想跨页面共享 → 用
hugo.Store(全局)或SITE.Store(站点级); - 短代码内部共享 →
SHORTCODE.Store; - 只是一次性的临时变量 →
{{ $x := ... }}就够; - 想用页面参数(front matter)存配置 → 那是
.Params的领域。
作用域选择(上游):
| 作用域 | 方法或函数 |
|---|---|
| page | PAGE.Store |
| site | SITE.Store |
| global | hugo.Store |
| local | collections.NewScratch |
| shortcode | SHORTCODE.Store |
用法
用 Page 对象上的 Store 方法可以创建一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前页面。要创建其他作用域的数据结构,请参见下面的作用域一节。
方法
在数据结构上使用这些方法。
Set- 设置给定 key 的值。
go-html-template
{{ .Store.Set "greeting" "Hello" }} Get- (
any)获取给定 key 的值。go-html-template{{ .Store.Set "greeting" "Hello" }} {{ .Store.Get "greeting" }} → Hello Add- 把给定值加到给定 key 的现有值上。
对于单个值,
Add接受支持 Go 的+运算符的值。如果对某个 key 的第一次Add操作是数组或切片,后续的 add 会追加到该列表中。go-html-template{{ .Store.Set "greeting" "Hello" }} {{ .Store.Add "greeting" "Welcome" }} {{ .Store.Get "greeting" }} → HelloWelcomego-html-template{{ .Store.Set "total" 3 }} {{ .Store.Add "total" 7 }} {{ .Store.Get "total" }} → 10go-html-template{{ .Store.Set "greetings" (slice "Hello") }} {{ .Store.Add "greetings" (slice "Welcome" "Cheers") }} {{ .Store.Get "greetings" }} → [Hello Welcome Cheers] SetInMap- 接受
key、mapKey和value,并把由mapKey和value构成的映射加入给定的key。go-html-template{{ .Store.SetInMap "greetings" "english" "Hello" }} {{ .Store.SetInMap "greetings" "french" "Bonjour" }} {{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour] DeleteInMap- 接受
key和mapKey,并从给定的key中移除mapKey对应的映射。go-html-template{{ .Store.SetInMap "greetings" "english" "Hello" }} {{ .Store.SetInMap "greetings" "french" "Bonjour" }} {{ .Store.DeleteInMap "greetings" "english" }} {{ .Store.Get "greetings" }} → map[french:Bonjour] GetSortedMapValues- (
[]any)返回key中的值数组,按mapKey排序。go-html-template{{ .Store.SetInMap "greetings" "english" "Hello" }} {{ .Store.SetInMap "greetings" "french" "Bonjour" }} {{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] Delete- 移除给定的 key。
go-html-template
{{ .Store.Set "greeting" "Hello" }} {{ .Store.Delete "greeting" }}
作用域
用于创建该数据结构的方法或函数决定了它的作用域。例如,用 Page 对象上的 Store 方法创建的数据结构,其作用域就是该页面。
| 作用域 | 方法或函数 |
|---|---|
| page | PAGE.Store |
| site | SITE.Store |
| global | hugo.Store |
| local | collections.NewScratch |
| shortcode | SHORTCODE.Store |
确定值
Store 方法常用于在_短代码_模板、由_短代码_模板调用的_局部模板_,或_渲染钩子_模板中设置值。在这三种情况下,存储的值在 Hugo 渲染页面内容之前都是不确定的。
如果你需要从父模板访问某个已存储的值,而该父模板尚未渲染页面内容,可以通过把返回值赋给一个 noop 变量来触发内容渲染:
{{ $noop := .Content }}
{{ .Store.Get "mykey" }}你也可以用 ContentWithoutSummary、FuzzyWordCount、Len、Plain、PlainWords、ReadingTime、Summary、Truncated 和 WordCount 方法触发内容渲染。例如:
{{ $noop := .WordCount }}
{{ .Store.Get "mykey" }}完整示例:写入、累加、映射与删除
模板(layouts/_default/single.html):
{{ .Store.Set "total" 1 }}
{{ .Store.Add "total" 2 }}
<p>累加结果:{{ .Store.Get "total" }}</p>
{{ .Store.SetInMap "m" "b" 2 }}
{{ .Store.SetInMap "m" "a" 1 }}
<p>映射:{{ .Store.Get "m" }}</p>
<p>按 key 排序的值:{{ .Store.GetSortedMapValues "m" }}</p>
{{ .Store.Set "temp" 1 }}
{{ .Store.Delete "temp" }}
<p>删除后:{{ printf "%v" (.Store.Get "temp") }}</p>实测(Hugo 0.167.0):
<p>累加结果:3</p>
<p>映射:map[a:1 b:2]</p>
<p>按 key 排序的值:[1 2]</p>
<p>删除后:<nil></p>你应当看到什么:Set 之后再 Add 得到 3(不是 12,Add 是数值相加);SetInMap 建立的映射打印出来按 key 升序(map[a:1 b:2]);GetSortedMapValues 拿到按 mapKey 排序的值数组;Delete 之后 Get 返回 nil(打印为 <nil>)。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
Get 一个从未设置的 key |
nil(实测 .Store.Get "missing" → <nil>) |
否 |
Add 到不存在的 key |
以上一次为基准创建;数值相加、字符串拼接、切片追加(上游说明 + 实测整数相加) | 否 |
Add 到已删除的 key |
从零值重新开始 | 否 |
Delete 后 Get |
nil(实测) |
否 |
SetInMap / GetSortedMapValues |
映射按 mapKey 升序(实测 map[a:1 b:2]、[1 2]) |
否 |
.Scratch 与 .Store |
同一份存储,可互相读写(实测) | 否 |
| 作用域 | 仅当前页面;跨页面不可见 | 否 |
| 返回类型 | maps.Scratch |
否 |
更多排查入口见故障排查。