Go 模板函数与语句 on Hugo 中文文档

and

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

关于真值与假值

假值包括 false、0、任何 nil 指针或接口值、任何长度为零的数组、切片、映射或字符串，以及零值 time.Time。

其余一切值都是真值。

用法

and 函数从左到右依次求值，一旦结果可以确定就立即返回。

block

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

用法

block 是「定义模板」的简写：

{{ define "name" }} T1 {{ end }}

随后在当前位置执行它：

{{ template "name" pipeline }}

典型用法是先定义一组根模板，再通过重新定义其中的 block 模板来定制它们。

layouts/baseof.html

<body>
  <main>
    {{ block "main" . }}
      {{ print "default value if 'main' template is empty" }}
    {{ end }}
  </main>
</body>

layouts/page.html

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

layouts/section.html

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

更多信息参见 Go 的 text/template 文档。

break

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

用法

这段模板代码：

{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
  {{ if eq . "bar" }}
    {{ break }}
  {{ end }}
  <p>{{ . }}</p>
{{ end }}

渲染结果为：

<p>foo</p>

更多信息参见 Go 的 text/template 文档。

continue

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

用法

这段模板代码：

{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
  {{ if eq . "bar" }}
    {{ continue }}
  {{ end }}
  <p>{{ . }}</p>
{{ end }}

渲染结果为：

<p>foo</p>
<p>baz</p>

更多信息参见 Go 的 text/template 文档。

define

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

用法

与 block 语句配合使用：

{{ block "main" . }}
  {{ print "default value if 'main' template is empty" }}
{{ end }}

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
{{ end }}

与 partial 函数配合使用：

{{ partial "inline/foo.html" (dict "answer" 42) }}

{{ define "_partials/inline/foo.html" }}
  {{ printf "The answer is %v." .answer }}
{{ end }}

与 template 语句配合使用：

else

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

用法

与 if 语句配合使用：

{{ $var := "foo" }}
{{ if $var }}
  {{ $var }} → foo
{{ else }}
  {{ print "var is falsy" }}
{{ end }}

与 with 语句配合使用：

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ else }}
  {{ print "var is falsy" }}
{{ end }}

与 range 语句配合使用：

end

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

用法

与 if 语句配合使用：

{{ $var := "foo" }}
{{ if $var }}
  {{ $var }} → foo
{{ end }}

与 with 语句配合使用：

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ end }}

与 range 语句配合使用：

{{ $var := slice 1 2 3 }}
{{ range $var }}
  {{ . }} → 1 2 3
{{ end }}

与 block 语句配合使用：

if

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

关于真值与假值

假值包括 false、0、任何 nil 指针或接口值、任何长度为零的数组、切片、映射或字符串，以及零值 time.Time。

其余一切值都是真值。

用法

{{ $var := "foo" }}
{{ if $var }}
  {{ $var }} → foo
{{ end }}

与 else 语句配合使用：

len

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

用法

字符串：

{{ "ab" | len }} → 2
{{ ""   | len }} → 0

切片：

{{ slice "a" "b" | len }} → 2
{{ slice         | len }} → 0

映射：

{{ dict "a" 1 "b" 2 | len }} → 2
{{ dict             | len }} → 0

集合：

{{ site.RegularPages | len }} → 42

也可以用下面的写法统计集合中的页面数量：

not

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

用法

与 and、or 运算符不同，not 运算符总是返回布尔值。

{{ not true }} → false
{{ not false }} → true

{{ not 1 }} → false
{{ not 0 }} → true

{{ not "x" }} → false
{{ not "" }} → true

连续两次使用 not 运算符，可以把任意值转换为布尔值。例如：

or

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

关于真值与假值

假值包括 false、0、任何 nil 指针或接口值、任何长度为零的数组、切片、映射或字符串，以及零值 time.Time。

其余一切值都是真值。

用法

or 函数从左到右依次求值，一旦结果可以确定就立即返回。

range

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

用法

集合可以是切片、映射或整数。

{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
  {{ . }} → foo bar baz
{{ end }}

与 else 语句配合使用：

{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
  <p>{{ . }}</p>
{{ else }}
  <p>The collection is empty</p>
{{ end }}

在 range 代码块内：

return

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

用法

return 语句是对 Go text/template 包的非标准扩展。它只终止当前模板的执行，调用它的模板会继续执行。在 局部模板（partial）中使用时，return 语句还可以向调用方返回一个值。

template

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

用法

用 template 语句执行一个已定义的模板：

{{ template "foo" (dict "answer" 42) }}

{{ define "foo" }}
  {{ printf "The answer is %v." .answer }}
{{ end }}

上面的例子可以改写为使用内联 局部模板：

{{ partial "inline/foo.html" (dict "answer" 42) }}

{{ define "_partials/inline/foo.html" }}
  {{ printf "The answer is %v." .answer }}
{{ end }}

上面两个例子的主要区别是：

内联 局部模板 的作用域是全局的。也就是说，在一个模板中定义的内联 局部模板 可以从任何模板中调用。
调用内联 局部模板 时借助 partialCached 函数，可以通过缓存结果来优化性能。
内联 局部模板 可以 return 返回任意数据类型的值，而不只是渲染出字符串。

更多信息参见 Go 的 text/template 文档。

try

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

（0.141.0 新增）

try 函数是对 Go text/template 包的非标准扩展。它引入了一种在模板中处理错误的机制，模仿其它编程语言中的 try-catch 结构。

方法

在 TryValue 对象上使用以下方法。

urlquery

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

用法

这段模板代码：

{{ $u := urlquery "https://" "example.com" | safeURL }}
<a href="https://example.org?url={{ $u }}">Link</a>

渲染结果为：

<a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a>

更多信息参见 Go 的 text/template 文档。

with

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

关于真值与假值

假值包括 false、0、任何 nil 指针或接口值、任何长度为零的数组、切片、映射或字符串，以及零值 time.Time。

其余一切值都是真值。

用法

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ end }}

与 else 语句配合使用：