文档章节
函数
在模板与原型中使用的全部函数与方法。
开始之前,你需要
- 知道 Go 模板的基本语法(
{{ }}、变量、if/range/with),否则先读模板简介。 - 手边有一个能构建的站点,遇到函数时可以立刻放进模板里试一次。
读完之后你能
- 按包(
strings、collections、transform、urls等)找到需要的函数,而不是靠翻页; - 分清函数与方法:什么时候写
strings.Truncate,什么时候写$page.Title; - 看懂管道写法
{{ $x | f a }}与嵌套写法{{ f a $x }}为什么等价; - 判断一个函数拿到空值、
nil或不符类型时会返回什么,而不是假设它一定会报错。
本章导读
模板的能力来自函数(function)与方法(method)。本目录按包(package)分组收录 Hugo 内建的全部函数,例如 collections、strings、transform、urls;函数名与参数、返回值都保持英文原样,不译。
这个目录有 300 多页,不要从头读。正确用法是:先知道自己要做什么,再按下面的方法定位。
怎么找函数
| 你要做的事 | 去哪 |
|---|---|
| 处理字符串(截断、替换、大小写、前后缀) | strings |
| 筛选、排序、分组页面或切片 | collections、methods/pages |
| 处理时间与日期 | time、methods/time |
| 处理图片(缩放、裁剪、滤镜) | images、methods/resource |
| 生成 URL、比较路径 | urls、path |
| 编译样式与脚本 | css、js |
| 读配置、拿站点级数据 | hugo、site、os |
| 不确定名字,只记得大概 | 用函数速查按命名空间列出的全表反查 |
怎么读函数签名
每页顶部有一行签名,形如:
strings.Truncate SIZE [ELLIPSIS] STRING读法是:大写的是参数名(按位置传入),方括号表示可选,空格分隔参数顺序,签名下方另标返回类型。
于是 strings.Truncate 10 "…" $s 表示:第 1 个参数 SIZE 是 10,可选参数 ELLIPSIS 是 "…",最后一个参数是待处理的内容。
调用写法:嵌套还是管道
同一个函数有两种等价写法:
go-html-template
{{ sub 3 2 }} {{/* 嵌套:函数名在前,参数依次跟上 */}}
{{ 3 | sub 2 }} {{/* 管道:左侧结果作为最后一个参数传入 */}}管道在「一串处理接连做」时更好读,因为它按数据流动的方向从左到右写:
go-html-template
{{ $s := "前前后后" | strings.TrimPrefix "前" | strings.TrimSuffix "后" }}注意管道的传参位置:a | f b 等价于 f b a——被管道传入的值永远是最后一个参数。不知道参数顺序时先看签名,不要猜。
函数与方法怎么选
- 需要处理一份数据(字符串、切片、图片)→ 用函数,写法是
strings.Truncate …; - 需要从对象上取信息(页面标题、资源尺寸、站点参数)→ 用方法,写法是
$page.Title。
两者常有同名者(例如 strings.Truncate 与页面标题的截断需求),方法收录在方法一章。
本站被引用最多的函数
站内页面互链次数排名(越靠前说明越多页面在依赖它,通常也是你最常需要的):
| 函数 | 用途 |
|---|---|
css.Sass |
把 SCSS / Sass 编译成 CSS |
images.Filter |
给图片套滤镜链 |
time.Format |
格式化时间(注意与 .Format 方法的差异) |
resources.GetRemote |
抓取远程资源 |
css.TailwindCSS |
用 Tailwind CLI 生成样式 |
collections.Where |
按条件筛选页面集合 |
strings.Truncate |
按单词边界截断文本 |
transform.Markdownify |
把 Markdown 片段渲染成 HTML |
partials.IncludeCached |
缓存局部模板的渲染结果 |
reflect.IsImageResourceProcessable |
判断资源能否做图像处理 |
同名函数与方法的差别、以及命名空间(如 hugo.、site.、strings.)的含义,见方法一章与各页说明。
本章内容
- 类型转换函数 使用这些函数把值从一种数据类型转换为另一种。 (今天)
- 集合函数 用这些函数操作与查询映射(map)、切片(slice)和字符串。 (今天)
- 比较函数 使用这些函数比较两个或多个值。 (今天)
- 加密函数 生成加密哈希与 HMAC 签名:md5、sha1、sha256,以及带密钥的 hmac。 (今天)
- CSS 函数 用这些函数处理 CSS 与 Sass 文件。 (今天)
- 调试函数 把模板里的中间值打出来:dump、timer、visualizeSpaces,排查「拿到的值不对」或「构建变慢」。 (今天)
- 图表函数 在构建时把 Mermaid 图表渲染成 SVG:用 diagrams.Goat 生成图表标记,配合代码块渲染钩子。 (今天)
- 编码函数 用这些函数对数据做编码与解码。 (今天)
- 格式化输出函数 使用这些函数在模板中输出字符串,或向终端输出消息。 (今天)
- 全局函数 在任何模板里直接取页面或站点对象:page 与 site 两个全局函数。 (今天)
- Go 模板函数与语句 用这些函数与语句编写条件判断、循环及其它模板逻辑。 (今天)
- 哈希函数 生成非加密哈希,用于短指纹与缓存键:hash.FNV32a 与 hash.XxHash。 (今天)
- Hugo 函数 用这些函数获取 Hugo 应用程序与当前运行环境的信息。 (今天)
- 图像函数 创建图像滤镜、把滤镜链应用到图片上,以及读取图像信息:亮度、对比度、色彩、模糊、遮罩、叠加、二维码等。 (今天)
- 词形变化函数 英语名词的单复数与大小写形态转换:Humanize、Pluralize、Singularize。 (今天)
- JavaScript 函数 用这些函数处理 JavaScript 与 TypeScript 文件。 (今天)
- 语言函数 使用这些函数让站点满足语言与地区方面的要求。 (今天)
- 数学函数 使用这些函数执行数学运算。 (今天)
- OpenAPI 函数 把 OpenAPI 3 定义(JSON/YAML)反序列化成可遍历的数据结构:openapi3.Unmarshal。 (今天)
- 操作系统函数 使用这些函数与操作系统交互。 (今天)
- 局部模板函数 使用这些函数调用局部模板(partial)。 (今天)
- 路径函数 用这些函数处理文件路径。 (今天)
- 反射函数 用这些函数判断一个值的数据类型。 (今天)
- 资源函数 用这些函数处理资源。 (今天)
- 安全函数 使用这些函数在 Go 的 html/template 包的上下文中把值声明为安全。 (今天)
- 字符串函数 用这些函数处理字符串。 (今天)
- 模板函数 查询模板系统自身:判断模板是否存在、取当前模板名,以及在局部模板里拿到调用方内容。 (今天)
- 时间函数 使用这些函数处理时间值。 (今天)
- 转换函数 用这些函数把取值从一种格式转换为另一种格式。 (今天)
- URL 函数 用这些函数处理 URL。 (今天)