TplFuncMap Documentation

January 11, 2026 · View on GitHub

简介 / Introduction

TplFuncMap 是一个全面的模板函数映射，提供了丰富的实用函数集合用于模板渲染。它包括时间操作、类型转换、字符串处理、编码/解码、数学运算等功能。

TplFuncMap is a comprehensive template function map that provides a rich set of utility functions for template rendering. It includes functions for time manipulation, type conversion, string processing, encoding/decoding, mathematical operations, and more.

快速开始 / Quick Start

import (
    "html/template"
    "github.com/webx-top/echo/middleware/tplfunc"
)

// Create template with TplFuncMap / 使用 TplFuncMap 创建模板
t := template.New("example")
t.Funcs(tplfunc.New())

// Use in template / 在模板中使用
{{ Now.Format "2006-01-02" }}
{{ ToFixed 100 2 }}
{{ "hello world" | ToUpper }}

函数分类 / Function Categories

1. Time Functions / 时间相关函数

函数名 Function	说明 Description	示例 Example
`Now`	当前时间 / Current time	`{{ Now }}`
`UnixTime`	Unix时间戳 / Unix timestamp	`{{ UnixTime }}`
`ElapsedMemory`	内存消耗 / Memory consumption	`{{ ElapsedMemory }}`
`TotalRunTime`	运行时长(从启动服务时算起) / Run time since service started	`{{ TotalRunTime }}`
`CaptchaForm`	验证码图片表单 / CAPTCHA image form	`{{ CaptchaForm }}`
`FormatByte`	字节数转为适合理解的格式 / Bytes to human-readable format	`{{ 1024 \| FormatByte }}`
`FormatBytes`	字节数转为适合理解的格式 / Bytes to human-readable format	`{{ 1024 \| FormatBytes }}`
`FriendlyTime`	友好的时间格式 / Human-friendly time format	`{{ 3600 \| FriendlyTime }}`
`FormatPastTime`	以前距离现在多长时间 / Time elapsed since past	`{{ 1609459200 \| FormatPastTime }}`
`DateFormat`	日期格式化 / Date format	`{{ 1609459200 \| DateFormat "2006-01-02" }}`
`DateFormatShort`	短日期格式 / Short date format	`{{ 1609459200 \| DateFormatShort }}`
`Ts2time`	时间戳数字转time.Time / Timestamp to time.Time	`{{ 1609459200 \| Ts2time }}`
`Ts2date`	时间戳数字转日期字符串 / Timestamp to date string	`{{ 1609459200 \| Ts2date "2006-01-02" }}`

2. Comparison Functions / 比较函数

函数名 Function	说明 Description	示例 Example
`Eq`	等值比较 / Equal comparison	`{{ Eq a b }}`
`Add`	加法 / Addition	`{{ Add 1 2 }}`
`Sub`	减法 / Subtraction	`{{ Sub 5 2 }}`
`Div`	除法 / Division	`{{ Div 10 2 }}`
`Mul`	乘法 / Multiplication	`{{ Mul 3 4 }}`
`IsNil`	检查是否为nil / Check if nil	`{{ IsNil value }}`
`IsEmpty`	检查是否为空 / Check if empty	`{{ IsEmpty value }}`
`NotEmpty`	检查是否不为空 / Check if not empty	`{{ NotEmpty value }}`
`IsNaN`	检查是否为非数字 / Check if NaN	`{{ IsNaN value }}`
`IsInf`	检查是否为无穷大 / Check if infinity	`{{ IsInf value 1 }}`

3. Type Conversion Functions / 类型转换函数

函数名 Function	说明 Description	示例 Example
`Html`, `ToHTML`	转换为HTML / Convert to HTML	`{{ content \| ToHTML }}`
`Js`, `ToJS`	转换为JavaScript / Convert to JS	`{{ content \| ToJS }}`
`Css`, `ToCSS`	转换为CSS / Convert to CSS	`{{ content \| ToCSS }}`
`ToURL`	转换为URL / Convert to URL	`{{ url \| ToURL }}`
`ToHTMLAttr`	转换为HTML属性 / Convert to HTML attribute	`{{ attr \| ToHTMLAttr }}`
`ToHTMLAttrs`	转换为HTML属性集合 / Convert to HTML attributes	`{{ attrs \| ToHTMLAttrs }}`
`ToStrSlice`	转换为字符串切片 / Convert to string slice	`{{ ToStrSlice "a" "b" }}`
`ToDuration`	转换为时间间隔 / Convert to duration	`{{ ToDuration 60 "s" }}`
`Str`	转换为字符串 / Convert to string	`{{ 123 \| Str }}`
`Int`	转换为整数 / Convert to int	`{{ "123" \| Int }}`
`Int32`	转换为32位整数 / Convert to int32	`{{ "123" \| Int32 }}`
`Int64`	转换为64位整数 / Convert to int64	`{{ "123" \| Int64 }}`
`Uint`	转换为无符号整数 / Convert to uint	`{{ "123" \| Uint }}`
`Uint32`	转换为32位无符号整数 / Convert to uint32	`{{ "123" \| Uint32 }}`
`Uint64`	转换为64位无符号整数 / Convert to uint64	`{{ "123" \| Uint64 }}`
`Float32`	转换为32位浮点数 / Convert to float32	`{{ "3.14" \| Float32 }}`
`Float64`	转换为64位浮点数 / Convert to float64	`{{ "3.14" \| Float64 }}`
`Float2int`	浮点数转整数 / Float to int	`{{ 3.9 \| Float2int }}`
`Float2uint`	浮点数转无符号整数 / Float to uint	`{{ 3.9 \| Float2uint }}`
`Float2int64`	浮点数转64位整数 / Float to int64	`{{ 3.9 \| Float2int64 }}`
`Float2uint64`	浮点数转64位无符号整数 / Float to uint64	`{{ 3.9 \| Float2uint64 }}`
`ToFloat64`	转换为64位浮点数 / Convert to float64	`{{ "3.14" \| ToFloat64 }}`
`ToFixed`	格式化为固定位小数 / Format to fixed decimal	`{{ ToFixed 3.14159 2 }}`
`ToDecimal`	转换为 decimal.Decimal 类型 / Converts any numeric type to a decimal.Decimal	`{{ "3.14" \| ToDecimal }}`
`NumberMore`	数字格式化(如：99+) / Number format with max	`{{ 1000 \| NumberMore 99 }}` 大于99时显示为99+
`Math`	数学运算 / Math operations	`{{ Math "sqrt" 16 }}`
`NumberFormat`	数字格式化 / Number formatting	`{{ NumberFormat 1234567.89 2 }}`
`NumFormat`	数字格式化 / Number formatting	`{{ 1234567.89 \| NumFormat 2 }}`
`NumberTrim`	截断数字精度 / Trim number precision	`{{ NumberTrim 3.14159 2 }}`
`DurationFormat`	时间间隔格式化 / Duration formatting	`{{ 3600 \| DurationFormat "en" }}`
`DelimLeft`	模板标签左分隔符 / Template tag left delimiter	`{{ DelimLeft }}`
`DelimRight`	模板标签右分隔符 / Template tag right delimiter	`{{ DelimRight }}`
`TemplateTag`	模板标签 / Template tag	`{{ TemplateTag "name" }}`

4. String Functions / 字符串处理函数

字符串检查 / String Check

函数名 Function	说明 Description	示例 Example
`Contains`	检查子串 / Check substring	`{{ Contains "hello world" "world" }}`
`HasPrefix`	检查前缀 / Check prefix	`{{ HasPrefix "hello" "he" }}`
`HasSuffix`	检查后缀 / Check suffix	`{{ HasSuffix "hello" "lo" }}`
`InExt`	检查文件扩展名 / Check file extension	`{{ InExt "image.jpg" ".jpg" ".png" }}`

字符串修剪 / String Trimming

函数名 Function	说明 Description	示例 Example
`Trim`	去除空白 / Trim whitespace	`{{ " hello " \| Trim }}`
`TrimLeft`	去除左侧 / Trim left	`{{ " hello" \| TrimLeft }}`
`TrimRight`	去除右侧 / Trim right	`{{ "hello " \| TrimRight }}`
`TrimPrefix`	去除前缀 / Trim prefix	`{{ TrimPrefix "prefix_hello" "prefix_" }}`
`TrimSuffix`	去除后缀 / Trim suffix	`{{ TrimSuffix "hello_suffix" "_suffix" }}`

大小写转换 / Case Conversion

函数名 Function	说明 Description	示例 Example
`ToLower`	转小写 / To lowercase	`{{ "HELLO" \| ToLower }}`
`ToUpper`	转大写 / To uppercase	`{{ "hello" \| ToUpper }}`
`Title`	标题格式 / To title case	`{{ "hello world" \| Title }}`
`LowerCaseFirst`	首字母小写 / Lower first letter	`{{ "Hello" \| LowerCaseFirst }}`
`UpperCaseFirst`	首字母大写 / Upper first letter	`{{ "hello" \| UpperCaseFirst }}`
`CamelCase`	转驼峰命名 / To camel case	`{{ "hello_world" \| CamelCase }}`
`PascalCase`	转帕斯卡命名 / To pascal case	`{{ "hello_world" \| PascalCase }}`
`SnakeCase`	转蛇形命名 / To snake case	`{{ "HelloWorld" \| SnakeCase }}`

路径处理 / Path Handling

函数名 Function	说明 Description	示例 Example
`Dir`	目录路径 / Directory path	`{{ "/path/to/file.txt" \| Dir }}`
`Base`	基础名称 / Base name	`{{ "/path/to/file.txt" \| Base }}`
`Ext`	文件扩展名 / File extension	`{{ "file.txt" \| Ext }}`
`Dirname`	目录名 / Directory name	`{{ "path/to/file" \| Dirname }}`
`Basename`	基础名称 / Base name	`{{ "path/to/file" \| Basename }}`
`Extension`	扩展名 / Extension	`{{ "file.txt" \| Extension }}`

字符串操作 / String Operations

函数名 Function	说明 Description	示例 Example
`Concat`	连接字符串 / Concatenate strings	`{{ Concat "hello" "world" }}`
`Replace`	替换子串 / Replace substring	`{{ Replace "hello world" "world" "go" }}`
`Split`	分割字符串 / Split string	`{{ Split "a,b,c" "," }}`
`Join`	连接字符串 / Join strings	`{{ Join slice "," }}`
`JoinNumbers`	连接数字 / Join numbers	`{{ JoinNumbers slice "," }}`
`Substr`	子字符串 / Substring	`{{ Substr "hello" 0 3 }}`
`StripTags`	去除HTML标签 / Strip HTML tags	`{{ "<p>hello</p>" \| StripTags }}`
`Nl2br`	换行转 / Newline to	`{{ "line1\nline2" \| Nl2br }}`
`AddSuffix`	添加后缀 / Add suffix	`{{ AddSuffix "file.txt" "_new" }}` 输出 file_new.txt
`RandomString`	随机字符串 / Random string	`{{ RandomString 8 }}`
`Slugify`	转URL友好格式 / To slug	`{{ "Hello World" \| Slugify }}` 输出 hello-world
`SlugifyMaxWidth`	转URL友好格式(限制长度) / To slug with max width	`{{ "Hello World" \| SlugifyMaxWidth 20 }}`
`Reverse`	反转字符串 / Reverse string	`{{ "hello" \| Reverse }}` 输出 olleh

5. Encode & Decode Functions / 编码解码函数

函数名 Function	说明 Description	示例 Example
`JSONEncode`	JSON编码 / Encode to JSON	`{{ JSONEncode data " " }}`
`JSONDecode`	JSON解码 / Decode from JSON	{{ ``{"A":1}`` \| JSONDecode }}
`JSONDecodeSlice`	JSON解码为切片 / Decode JSON to slice	`{{ "[1,0.2,true]" \| JSONDecodeSlice }}`
`JSONDecodeStringSlice`	JSON解码为字符串切片 / Decode JSON to string slice	`{{ "[\"a\",\"b\",\"c\"]" \| JSONDecodeStringSlice }}`
`JSONDecodeUintSlice`	JSON解码为uint64切片 / Decode JSON to uint64 slice	`{{ "[1,2,3]" \| JSONDecodeUintSlice }}`
`URLEncode`	URL编码 / URL encode	`{{ "hello world" \| URLEncode }}`
`URLDecode`	URL解码 / URL decode	`{{ "hello%20world" \| URLDecode }}`
`RawURLEncode`	原始URL编码 / Raw URL encode	`{{ "hello world" \| RawURLEncode }}`
`RawURLDecode`	原始URL解码 / Raw URL decode	`{{ url \| RawURLDecode }}`
`Base64Encode`	Base64编码 / Base64 encode	`{{ "hello" \| Base64Encode }}`
`Base64Decode`	Base64解码 / Base64 decode	`{{ base64Str \| Base64Decode }}`
`UnicodeDecode`	Unicode解码 / Unicode decode	`{{ "\\u4f60\\u597d" \| UnicodeDecode }}`
`SafeBase64Encode`	安全Base64编码 / Safe Base64 encode	`{{ "hello" \| SafeBase64Encode }}`
`SafeBase64Decode`	安全Base64解码 / Safe Base64 decode	`{{ base64Str \| SafeBase64Decode }}`
`Hash`	哈希字符串 / Hash string	`{{ Hash "password" "salt" }}`
`Unquote`	去除引号 / Unquote string	`{{ "'hello'" \| Unquote }}`
`Quote`	添加引号 / Quote string	`{{ hello \| Quote }}`

6. Map & Slice Functions / 映射和切片函数

函数名 Function	说明 Description	示例 Example
`MakeMap`	创建映射 / Create map	`{{ MakeMap "key1" "value1" "key2" "value2" }}`
`MakeSlice`	创建切片 / Create slice	`{{ MakeSlice "a" "b" "c" }}`
`InSet`	检查是否在集合中 / Check in set	`{{ InSet "value" set }}`
`InSlice`	检查是否在切片中 / Check in slice	`{{ InSlice "value" slice }}`
`InSlicex`	检查是否在切片中(interface) / Check in slice (interface)	`{{ InSlicex "value" slice }}`
`Set`	设置值 / Set value	`{{ Set renderArgs "key" "value" }}`
`Append`	追加到切片 / Append to slice	`{{ Append renderArgs "key" "value" }}`
`InStrSlice`	检查是否在字符串切片中 / Check in string slice	`{{ InStrSlice slice "value" }}`
`SearchStrSlice`	在字符串切片中搜索 / Search in string slice	`{{ SearchStrSlice slice "value" }}`
`URLValues`	创建URL值 / Create URL values	`{{ URLValues "key1" "value1" }}`
`ToSlice`	转换为切片 / Convert to slice	`{{ ToSlice 1 2 3 }}`
`StrToSlice`	字符串转切片 / String to slice	`{{ StrToSlice "a,b,c" "," }}`
`GetByIndex`	按索引获取 / Get by index	`{{ GetByIndex list 0 }}`
`ToParamString`	转换为参数字符串 / Convert to param string	`{{ "value" \| ToParamString }}`

7. RegExp Functions / 正则表达式函数

函数名 Function	说明 Description	示例 Example
`Regexp`	编译正则表达式 / Compile regexp	`{{ $r := Regexp "^[a-z]+$" }}`
`RegexpPOSIX`	编译POSIX正则表达式 / Compile POSIX regexp	`{{ $r := RegexpPOSIX "^[[:alpha:]]+$" }}`

8. Other Functions / 其他函数

函数名 Function	说明 Description	示例 Example
`Ignore`	忽略值 / Ignore value	`{{ value \| Ignore }}`
`Default`	默认值 / Default value	`{{ value \| Default "default" }}`
`WithURLParams`	带参数的URL / URL with params	`{{ WithURLParams "/path" "key" "value" }}`
`FullURL`	完整URL / Full URL	`{{ FullURL "https://example.com" "/path" }}` 输出 https://example.com/path
`IsFullURL`	检查是否为完整URL / Check if full URL	`{{ "https://example.com" \| IsFullURL }}`
`If`	条件判断 / Conditional	`{{ If condition yes no }}`

使用示例 / Usage Examples

时间处理 / Time Handling

// 获取当前时间 / Get current time
{{ Now.Format "2006-01-02 15:04:05" }}

// 时间戳转换 / Timestamp conversion
{{ 1609459200 | DateFormat "2006-01-02" }}

// 友好时间格式 / Friendly time format
{{ 86400 | FriendlyTime }}  // 1天 / 1 day

// 时间间隔格式化 / Duration formatting
{{ 3600 | DurationFormat "en" }}  // 1 hour

数学运算 / Mathematical Operations

// 基本运算 / Basic operations
{{ Add 10 20 }}        // 30
{{ Sub 50 20 }}        // 30
{{ Mul 6 7 }}         // 42
{{ Div 100 4 }}        // 25

// 数学函数 / Math functions
{{ Math "sqrt" 16 }}   // 4
{{ Math "pow" 2 10 }}  // 1024
{{ Math "abs" -5 }}    // 5

// 数字格式化 / Number formatting
{{ ToFixed 3.14159 2 }}           // "3.14"
{{ NumberFormat 1234567.89 2 }}    // "1,234,567.89"
{{ 1000 | NumberMore 99 }}           // "99+"

字符串处理 / String Processing

// 大小写转换 / Case conversion
{{ "hello world" | Title }}          // "Hello World"
{{ "hello" | ToUpper }}              // "HELLO"
{{ "HELLO" | ToLower }}              // "hello"

// 命名转换 / Naming convention conversion
{{ "hello_world" | CamelCase }}      // "helloWorld"
{{ "hello_world" | PascalCase }}     // "HelloWorld"
{{ "HelloWorld" | SnakeCase }}       // "hello_world"

// 字符串操作 / String operations
{{ Contains "hello world" "world" }}   // true
{{ "file.txt" | Ext }}                   // ".txt"
{{ Concat "hello" "world" }}          // "helloworld"

// 路径处理 / Path handling
{{ "/path/to/file.txt" | Dir }}      // "/path/to"
{{ "/path/to/file.txt" | Base }}     // "file.txt"
{{ "file.txt" | Ext }}              // ".txt"

编码解码 / Encoding & Decoding

// JSON / JSON
{{ JSONEncode mapData "  " }}
{{ jsonStr | JSONDecode }}

// Base64 / Base64
{{ "hello" | Base64Encode }}         // "aGVsbG8="
{{ "aGVsbG8=" | Base64Decode }}     // "hello"

// URL / URL
{{ "hello world" | URLEncode }}      // "hello%20world"
{{ "hello%20world" | URLDecode }}   // "hello world"

// Unicode / Unicode
{{ "\\u4f60\\u597d" | UnicodeDecode }}  // "你好"

类型转换 / Type Conversion

// 数字转换 / Number conversion
{{ "3.14" | ToFloat64 }}    // 3.14
{{ ToFixed 3.14159 2 }}     // "3.14"
{{ "123" | Int }}           // 123

// 安全类型转换 / Safe type conversion
{{ value | Default "N/A" }}     // Return "N/A" if empty
{{ value | IsNil }}             // Check if nil
{{ value | IsEmpty }}           // Check if empty

条件判断 / Conditional Logic

// 条件输出 / Conditional output
{{ If user.LoggedIn "Welcome" "Please login" }}

// 空值处理 / Empty value handling
{{ user.Name | Default "Anonymous" }}
{{ If (NotEmpty user.Email) "Email provided" "No email" }}

数据结构操作 / Data Structure Operations

// 创建Map / Create map
{{ MakeMap "name" "John" "age" 30 }}

// 创建Slice / Create slice
{{ MakeSlice "apple" "banana" "orange" }}

// 检查元素 / Check element
{{ InSlice "apple" fruits }}        // true
{{ InStrSlice names "John" }}       // true
{{ SearchStrSlice names "John" }}  // 0

注意事项 / Notes

线程安全 / Thread Safety: TplFuncMap 是全局变量，在并发环境中使用是安全的。
TplFuncMap is a global variable and is safe to use in concurrent environments.
错误处理 / Error Handling: 部分函数在遇到错误时会记录日志并返回默认值。
Some functions log errors and return default values when errors occur.
性能考虑 / Performance Considerations: 频繁调用复杂函数（如 Math）可能影响性能，建议在控制器层处理复杂逻辑。
Frequent calls to complex functions (like Math) may impact performance. Consider handling complex logic at the controller level.
HTML安全 / HTML Security: 使用 ToHTML、ToJS、ToCSS 等函数时，确保内容是可信的，以避免XSS攻击。
When using functions like ToHTML, ToJS, ToCSS, ensure the content is trusted to avoid XSS attacks.
日期格式 / Date Format: Go使用特定的日期格式参考时间 "2006-01-02 15:04:05"，而不是常用的格式字符串。
Go uses a specific reference date "2006-01-02 15:04:05" for date formatting instead of common format strings.

常见问题 / FAQ

Q: 如何自定义函数 / How to add custom functions? / A: 可以通过 `New()` 函数创建新的 `FuncMap` 并添加自定义函数：

customFuncs := tplfunc.New()
customFuncs["customFunc"] = func(s string) string {
    return "custom: " + s
}
template.New("example").Funcs(customFuncs)

Q: 时间格式化字符串是什么意思 / What do the date format strings mean? / A: Go使用特定的参考时间 `Mon Jan 2 15:04:05 MST 2006` 来定义格式：

2006 - 年 / Year
01 - 月 / Month
02 - 日 / Day
15 - 时(24小时制) / Hour (24-hour)
04 - 分 / Minute
05 - 秒 / Second

Q: 如何处理空值 / How to handle empty values? / A: 使用 `Default` 函数提供默认值：

{{ user.Name | Default "Guest" }}

许可证 / License

Apache License 2.0