Skip to content

TplFuncMap_Documentation.md

Latest commit

 

History

History
388 lines (314 loc) · 18.9 KB

TplFuncMap_Documentation.md

File metadata and controls

388 lines (314 loc) · 18.9 KB
Raw

TplFuncMap Documentation

简介 / 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

  1. 线程安全 / Thread Safety: TplFuncMap 是全局变量，在并发环境中使用是安全的。
    TplFuncMap is a global variable and is safe to use in concurrent environments.

  2. 错误处理 / Error Handling: 部分函数在遇到错误时会记录日志并返回默认值。
    Some functions log errors and return default values when errors occur.

  3. 性能考虑 / Performance Considerations: 频繁调用复杂函数（如 Math）可能影响性能，建议在控制器层处理复杂逻辑。
    Frequent calls to complex functions (like Math) may impact performance. Consider handling complex logic at the controller level.

  4. HTML安全 / HTML Security: 使用 ToHTML、ToJS、ToCSS 等函数时，确保内容是可信的，以避免XSS攻击。
    When using functions like ToHTML, ToJS, ToCSS, ensure the content is trusted to avoid XSS attacks.

  5. 日期格式 / 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

更多信息 / More Information