文档章节

函数

在模板与原型中使用的全部函数与方法。

难度
参考
预计用时
按需查阅;通读约 30 分钟

开始之前,你需要

  • 知道 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。 (今天)