集合函数 on Hugo 中文文档

collections.After

Fri, 02 Oct 2026 00:00:00 +0800

基本用法

下面演示 after 与 slice 函数配合使用：

{{ $data := slice "one" "two" "three" "four" }}
<ul>
  {{ range after 2 $data }}
    <li>{{ . }}</li>
  {{ end }}
</ul>

上面的模板渲染为：

<ul>
  <li>three</li>
  <li>four</li>
</ul>

与 first 配合使用

你可以把 after 与 first 函数以及 Hugo 强大的排序方法组合使用。假设你在 example.org/articles 有一个 section 页面，共有 10 篇文章，但希望模板只显示两行：

collections.Append

Fri, 02 Oct 2026 00:00:00 +0800

该函数会把除最后一个参数之外的所有元素追加到最后一个参数上。这样就可以使用下面所示的管道写法。

向切片追加单个元素：

{{ $s := slice "a" "b" }}
{{ $s }} → [a b]

{{ $s = $s | append "c" }}
{{ $s }} → [a b c]

向切片追加两个元素：

collections.Apply

Fri, 02 Oct 2026 00:00:00 +0800

apply 函数接收三个或更多参数，具体数量取决于要应用到切片元素上的函数。

第一个参数是切片本身，第二个参数是函数名，其余参数会传给该函数，其中字符串 "." 代表切片元素。

collections.Complement

Fri, 02 Oct 2026 00:00:00 +0800

要找出存在于 $c3 但不存在于 $c1 或 $c2 中的元素：

{{ $c1 := slice 3 }}
{{ $c2 := slice 4 5 }}
{{ $c3 := slice 1 2 3 4 5 }}

{{ complement $c1 $c2 $c3 }} → [1 2]

{{ $c3 | complement $c1 $c2 }} → [1 2]

complement 函数也可以用于页面集合。假设你的站点有五种内容类型：

collections.D

Fri, 02 Oct 2026 00:00:00 +0800

（0.149.0 新增）

collections.D 函数使用给定的 SEED 值，返回半开区间 [0, HIGH) 内一组已排序且互不重复的随机整数。结果切片的元素个数为 N 与 HIGH 中较小的那个。

N 和 H 必须是闭区间 [0, 1000000] 内的整数
SEED 必须是闭区间 [0, 2^64 - 1] 内的整数

返回值

条件	返回值
`N <= HIGH`	使用 J. S. Vitter 的 Method D 做顺序随机抽样，得到大小为 `N` 的有序随机样本
`N > HIGH`	完整的已排序区间 `[0, HIGH)`，大小为 `HIGH`
`N == 0`	空切片
`N < 0`	错误
`N > 10^6`	错误
`HIGH == 0`	空切片
`HIGH < 0`	错误
`HIGH > 10^6`	错误
`SEED < 0`	错误

示例

{{ collections.D 6 7 42 }} → [4, 9, 10, 20, 22, 24, 41]

上面的示例每次调用都会生成_相同_的随机数。要在同一区间内生成_不同_的一组 7 个随机数，请修改 seed 值。

collections.Delimit

Fri, 02 Oct 2026 00:00:00 +0800

连接切片：

{{ $s := slice "b" "a" "c" }}
{{ delimit $s ", " }} → b, a, c
{{ delimit $s ", " " and "}} → b, a and c

连接映射：

{{ $m := dict "b" 2 "a" 1 "c" 3 }}
{{ delimit $m ", " }} → 1, 2, 3
{{ delimit $m ", " " and "}} → 1, 2 and 3

collections.Dictionary

Fri, 02 Oct 2026 00:00:00 +0800

把键值对作为一个个独立参数传入：

{{ $m := dict "a" 1 "b" 2 }}

上面会生成如下数据结构：

{
  "a": 1,
  "b": 2
}

注意 key 既可以是 string，也可以是 []string。后者可用于创建深层嵌套的结构，例如：

collections.First

Fri, 02 Oct 2026 00:00:00 +0800

{{ slice "a" "b" "c" | first 1 }} → [a]
{{ slice "a" "b" "c" | first 2 }} → [a b]

由于字符串实际上就是只读的字节切片，该函数可用于返回字符串开头指定数量的字节：

{{ "abc" | first 1 }} → a
{{ "abc" | first 2 }} → ab

注意一个_字符_可能由多个_字节_组成：

collections.Group

Fri, 02 Oct 2026 00:00:00 +0800

{{ $new := .Site.RegularPages | first 10 | group "New" }}
{{ $old := .Site.RegularPages | last 10 | group "Old" }}
{{ $groups := slice $new $old }}
{{ range $groups }}
  <h3>{{ .Key }}{{/* 输出 "New"、"Old" */}}</h3>
  <ul>
    {{ range .Pages }}
      <li>
        <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
        <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
      </li>
    {{ end }}
  </ul>
{{ end }}

从 group 得到的页面组，与 Hugo 内置 group 方法返回的类型相同。上面的示例可以分页。

collections.In

Fri, 02 Oct 2026 00:00:00 +0800

{{ $s := slice "a" "b" "c" }}
{{ in $s "b" }} → true

{{ $s := "abc" }}
{{ in $s "b" }} → true

collections.Index

Fri, 02 Oct 2026 00:00:00 +0800

被索引的每一项都必须是映射或切片：

{{ $s := slice "a" "b" "c" }}
{{ index $s 0 }} → a
{{ index $s 1 }} → b

{{ $m := dict "a" 100 "b" 200 }}
{{ index $m "b" }} → 200

使用两个或更多 key 可访问嵌套值：

collections.Intersect

Fri, 02 Oct 2026 00:00:00 +0800

一个有用的例子是把它与 where 组合起来，当作 AND 过滤器使用：

{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}

上面的代码会取出类型不是 page 或 about 的普通页面，除非它们被 pin 了。最后，我们排除掉所有未在 Page 参数中设置 images 的页面。

collections.IsSet

Fri, 02 Oct 2026 00:00:00 +0800

例如，考虑下面这份项目配置：

[params]
showHeroImage = false

如果 showHeroImage 的值是 true，我们可以用 if 或 with 检测到它存在：

{{ if site.Params.showHeroImage }}
  {{ site.Params.showHeroImage }} → true
{{ end }}

{{ with site.Params.showHeroImage }}
  {{ . }} → true
{{ end }}

然而，如果 showHeroImage 的值是 false，就无法用 if 或 with 检测其是否存在。这种情况下必须使用 isset 函数：

collections.KeyVals

Fri, 02 Oct 2026 00:00:00 +0800

该函数的主要用途，是为传给 Pages 对象上 Related 方法的 options 映射定义 namedSlices 值。

参见相关内容。

{{ $kv := keyVals "foo" "a" "b" "c" }}

得到的数据结构为：

{
  "Key": "foo",
  "Values": [
    "a",
    "b",
    "c"
  ]
}

要取出 key 和 values：

{{ $kv.Key }} → foo
{{ $kv.Values }} → [a b c]

collections.Last

Fri, 02 Oct 2026 00:00:00 +0800

{{ slice "a" "b" "c" | last 1 }} → [c]
{{ slice "a" "b" "c" | last 2 }} → [b c]

由于字符串实际上就是只读的字节切片，该函数可用于返回字符串末尾指定数量的字节：

{{ "abc" | last 1 }} → c
{{ "abc" | last 2 }} → bc

注意一个_字符_可能由多个_字节_组成：

collections.Merge

Fri, 02 Oct 2026 00:00:00 +0800

返回从左到右合并两个或多个映射的结果。如果 key 已存在，merge 会更新它的值；如果 key 不存在，merge 会在新 key 下插入该值。

key 的处理不区分大小写。

下面的示例使用这些映射定义：

collections.NewScratch

Fri, 02 Oct 2026 00:00:00 +0800

用 collections.NewScratch 函数创建一个局部作用域的持久化数据结构，用于存储和操作带 key 的值。要创建其他作用域的数据结构，请参见下文的作用域一节。

方法

在该数据结构上使用以下方法。

Set

设置给定 key 的值。

{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}

Get

（any）获取给定 key 的值。

{{ $s := newScratch }}
{{ $s.Set "greeting" "Hello" }}
{{ $s.Get "greeting" }} → Hello

Add

把给定的值加到给定 key 的现有值上。

对于单个值，Add 接受支持 Go + 运算符的值。如果某个 key 第一次 Add 的是数组或切片，那么后续的 Add 都会追加到该列表上。

collections.Querify

Fri, 02 Oct 2026 00:00:00 +0800

把键值对指定为映射、切片，或者一串标量值。例如下面几种写法等价：

{{ collections.Querify (dict "a" 1 "b" 2) }}
{{ collections.Querify (slice "a" 1 "b" 2) }}
{{ collections.Querify "a" 1 "b" 2 }}

要在 URL 后追加查询字符串：

{{ $qs := collections.Querify (dict "a" 1 "b" 2) }}
{{ $href := printf "https://example.org?%s" $qs }}

<a href="{{ $href }}">Link</a>

Hugo 会把它渲染成：

collections.Reverse

Fri, 02 Oct 2026 00:00:00 +0800

{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]

collections.Seq

Fri, 02 Oct 2026 00:00:00 +0800

{{ seq 2 }} → [1 2]
{{ seq 0 2 }} → [0 1 2]
{{ seq -2 2 }} → [-2 -1 0 1 2]
{{ seq -2 2 2 }} → [-2 0 2]

一个刻意构造的遍历整数序列的示例：

{{ $product := 1 }}
{{ range seq 4 }}
  {{ $product = mul $product . }}
{{ end }}
{{ $product }} → 24

collections.Shuffle

Fri, 02 Oct 2026 00:00:00 +0800

{{ collections.Shuffle (slice "a" "b" "c") }} → [b a c]

结果每次构建都会不同。

要从页面集合中渲染 5 个随机页面的无序列表：

<ul>
  {{ $p := site.RegularPages }}
  {{ range $p | collections.Shuffle | first 5 }}
    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
  {{ end }}
</ul>

（0.149.0 新增）

用 collections.D 函数完成同样的任务会快得多。

collections.Slice

Fri, 02 Oct 2026 00:00:00 +0800

{{ $s := slice "a" "b" "c" }}
{{ $s }} → [a b c]

要创建空切片：

{{ $s := slice }}

collections.Sort

Fri, 02 Oct 2026 00:00:00 +0800

对切片做升序排序时 KEY 可以省略，其他情况则必填。排序切片时，请用字面量 value 代替 KEY。参见下面的示例。

ORDER 可以是 asc（升序）或 desc（降序）。默认排序顺序为升序。

collections.SymDiff

Fri, 02 Oct 2026 00:00:00 +0800

示例：

{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]

另见 https://en.wikipedia.org/wiki/Symmetric_difference。

collections.Union

Fri, 02 Oct 2026 00:00:00 +0800

基本用法

用 union 函数合并两个切片，并去掉重复元素：

{{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5]
{{ union (slice 1 2 3) nil }}           → [1 2 3]
{{ union nil (slice 1 2 3) }}           → [1 2 3]
{{ union nil nil }}                     → []

where 查询中的 OR 过滤

与 where 组合使用时，它也可以当作 OR 过滤器：

collections.Uniq

Fri, 02 Oct 2026 00:00:00 +0800

{{ slice 1 3 2 1 | uniq }} → [1 3 2]

collections.Where

Fri, 02 Oct 2026 00:00:00 +0800

用法

where 函数返回给定切片，并移除不满足比较条件的元素。比较条件由 KEY、OPERATOR 和 VALUE 三个参数构成：

collections.Where SLICE KEY [OPERATOR] VALUE
                        --------------------
                        比较条件

如果不提供 OPERATOR 参数，Hugo 会按相等进行比较。例如：