模板函数

相关源文件

• tpl/collections/collections.go
• tpl/collections/collections_test.go
• tpl/collections/complement.go
• tpl/collections/complement_test.go
• tpl/collections/init.go
• tpl/collections/merge.go
• tpl/collections/merge_test.go
• tpl/collections/querify.go
• tpl/collections/querify_test.go
• tpl/collections/reflect_helpers.go
• tpl/collections/symdiff.go
• tpl/collections/symdiff_test.go
• tpl/collections/where.go
• tpl/collections/where_test.go
• tpl/template.go
• tpl/template_test.go

模板函数是 Hugo 模板系统的一个核心组件，它扩展了 Go 内置模板引擎的功能。这些函数提供了广泛的实用工具，用于数据操作、内容转换和模板流程控制，这些对于使用 Hugo 构建动态网站至关重要。

概述与架构

Hugo 中的模板函数被组织成逻辑命名空间，将相关功能分组在一起。每个命名空间都提供了一套针对特定操作类别的函数，例如处理集合、处理字符串或处理 URL。

来源

• tpl/template.go14-38
• tpl/collections/init.go22-209

函数注册系统

Hugo 的模板函数通过一个结构化的系统进行注册，该系统将 Go 方法映射到模板函数名。每个命名空间都用自己的上下文进行初始化，并通过 AddMethodMapping 机制注册其函数。

来源

• tpl/collections/init.go24-209
• tpl/template.go33-38

主要函数命名空间

Hugo 提供了全面的模板函数命名空间，每个命名空间都具有专业的功能

命名空间	目的	示例函数
合集	数组、切片和映射操作	after, first, where, sort
字符串	字符串操作和格式化	lower, trim, replace
数学	数学运算	add, mul, round
URL	URL 操作和构造	absURL, relURL, urlize
数据	数据访问和操作	getJSON, getCSV
资源	资源处理	resources.Get, resources.Copy
页面	页面集合操作	site.Pages, .Sections
网站	全站数据和配置	site.Title, site.Params
文件	文件系统操作	readDir, readFile
时间	日期和时间操作	now, dateFormat

来源

• tpl/collections/init.go29-203
• tpl/collections/collections.go14-687

集合命名空间

集合命名空间是 Hugo 中最广泛和最常用的函数集之一。它提供了用于处理数组、切片和映射的强大函数。

关键集合函数

功能	目的	示例用法
after	返回前 n 个元素之后的项	{{ after 1 (slice "a" "b" "c") }} → ["b","c"]
first	返回前 n 个元素	{{ first 2 .Pages }}
where	根据条件过滤集合	{{ where .Pages "Section" "post" }}
slice	从提供的参数创建切片	{{ slice "a" "b" "c" }}
dict	从键值对创建字典（映射）	{{ dict "name" "value" }}
sort	对集合进行排序	{{ sort .Pages "Date" }}
in	检查元素是否在集合中	{{ if in .Params.tags "hugo" }}
delimit	使用分隔符连接元素	{{ delimit .Tags ", " }}
union	合并两个数组/切片而不重复	{{ union (slice 1 2) (slice 2 3) }}
intersect	返回集合之间的公共元素	{{ intersect .Tags site.Params.featuredTags }}

来源

• tpl/collections/collections.go58-686
• tpl/collections/where.go28-540
• tpl/collections/init.go34-185

Where 函数

where 函数对于过滤集合特别强大。它支持各种比较运算符和嵌套属性访问。

支持的运算符包括

• =, ==, eq (等于)
• !=, <>, ne (不等于)
• >, gt (大于)
• >=, ge (大于等于)
• <, lt (小于)
• <=, le (小于等于)
• in (包含)
• not in (不包含)
• intersect (有共同元素)

来源

• tpl/collections/where.go28-486
• tpl/collections/where_test.go398-434

函数参数和返回值

Hugo 中的模板函数通常遵循一致的模式来处理参数和返回值

1. 函数接受可变数量的参数（可变参数）
2. 参数可以是不同类型，并根据需要进行转换
3. 大多数函数返回两个值：结果和错误
4. 在模板中，错误会自动处理（导致构建失败或渲染空结果）

例如，collections.Merge 的函数签名

来源

• tpl/collections/merge.go30-46
• tpl/collections/collections.go59-77

模板函数实现

模板函数作为命名空间结构上的方法实现。每个命名空间都是使用提供了对 Hugo 环境访问的依赖项上下文创建的。

来源

• tpl/collections/collections.go36-51
• tpl/collections/init.go26-205

辅助函数和实用工具

模板函数系统包含一些用于处理反射和类型转换的辅助工具，这些对于处理模板数据的动态性至关重要

1. 类型转换函数 - 在不同数据类型之间进行转换
2. 反射助手 - 使用 Go 的反射系统来操作值
3. 集合实用工具 - 以类型安全的方式帮助操作集合

来源

• tpl/collections/reflect_helpers.go30-216
• tpl/template.go102-134

在模板中使用模板函数

模板函数使用熟悉的语法在 Go 模板中访问

{{ functionName arg1 arg2 }}

函数可以链式调用

{{ "Hello, World!" | lower | truncate 10 }}

并且可以在控制结构中使用

{{ range where .Site.Pages "Section" "post" }}
  {{ .Title }}
{{ end }}

通过自定义函数进行扩展

虽然未在提供的代码中直接体现，但 Hugo 允许站点开发者通过 Hugo 模块系统或构建自定义 Hugo 二进制文件来添加自定义模板函数。

模板函数上下文

Hugo 中的模板函数可以通过 tpl 包中定义的 Context 变量访问上下文。这使得函数能够访问有关当前页面、站点和渲染上下文的信息。

来源

• tpl/template.go57-81

函数注册示例

以下是集合命名空间中模板函数的注册方式

注册包括

1. 要调用的 Go 方法
2. 模板函数名（别名）
3. 示例用法和预期输出

来源

• tpl/collections/init.go34-185

错误处理

大多数模板函数返回错误值以及结果。这些错误由模板系统处理，它将：

1. 停止构建并显示错误消息（在正常构建模式下）
2. 在开发服务器模式下显示错误
3. 在某些上下文中渲染空结果

这使得模板函数的用法更加健壮，同时仍能提供良好的调试信息。

来源

• tpl/collections/collections.go59-77
• tpl/collections/where.go28-57

模板函数构成了 Hugo 强大模板系统的基础，使站点开发者能够使用干净、可维护的模板代码创建动态、复杂的网站。