Gin 框架中的模板引擎使用指南

在构建 Web 应用时，服务端渲染 HTML 是一种常见的需求。Go 语言的 Gin 框架提供了对 Go 内置 html/template 的支持，使得开发者能够轻松地实现动态页面生成。本文将详细介绍如何在 Gin 中配置、加载、使用模板文件，以及如何利用模板继承和自定义函数来增强功能。

---

一、基础配置：加载模板文件

要在 Gin 中使用模板引擎，首先需要加载模板文件。Gin 提供了两种方法来加载模板：

1. LoadHTMLGlob（推荐）

此方法通过通配符匹配多个模板文件，适用于批量加载模板目录下的所有模板文件。

r := gin.Default()
// 加载 templates 目录下所有后缀为 .tmpl 的文件
r.LoadHTMLGlob("templates/**/*.tmpl")

2. LoadHTMLFiles

指定具体的模板文件路径，适合少量模板的情况。

// 或加载指定文件
r.LoadHTMLFiles("templates/index.tmpl", "templates/user.tmpl")

---

二、模板文件中使用模板语法

Gin 默认使用 Go 内置的 html/template 语法，支持变量插入、循环、条件判断等功能。

示例模板 (templates/index.tmpl)：

<!DOCTYPE html>
<html>
<head>
    <title>{{.Title}}</title>
</head>
<body>
    <h1>{{.Message}}</h1>
    <!-- 循环示例 -->
    {{range .Items}}
        <p>{{.}}</p>
    {{end}}
</body>
</html>

在这个例子中，.Title, .Message, 和 .Items 都是从处理器传递给模板的数据。

---

三、在处理器中渲染模板

通过 c.HTML() 方法可以渲染模板，并向其传递数据。

示例代码：

r.GET("/", func(c *gin.Context) {
    // 准备模板数据
    data := gin.H{
        "Title":   "Gin模板示例",
        "Message": "Hello Gin Template!",
        "Items":   []string{"Item 1", "Item 2", "Item 3"},
    }
    // 渲染模板（第一个参数是状态码，第二个是模板文件名，第三个是数据）
    c.HTML(http.StatusOK, "index.tmpl", data)
})

注意：这里的 "index.tmpl" 对应于模板文件的名称，而不是其所在的完整路径。

---

四、模板继承与布局

Gin 支持模板继承，允许你创建一个基础布局并让子模板继承它，从而减少重复代码。

1. 定义基础布局 (templates/layouts/base.tmpl)：

{{define "base"}}
<!DOCTYPE html>
<html>
<head>
    <title>{{block "title" .}}默认标题{{end}}</title>
</head>
<body>
    <header>网站头部</header>
    <main>
        {{block "content" .}}默认内容{{end}}
    </main>
    <footer>网站底部</footer>
</body>
</html>
{{end}}

2. 子模板继承基础布局 (templates/index.tmpl)：

{{template "base" .}}

{{block "title" .}}
    {{.Title}}
{{end}}

{{block "content" .}}
    <h1>{{.Message}}</h1>
{{end}}

加载时仍使用 LoadHTMLGlob("templates/**/*.tmpl")，渲染时指定子模板名即可。

---

五、自定义模板函数

你可以通过 SetFuncMap 方法为模板注册自定义函数，例如格式化日期。

示例代码：

import (
    "github.com/gin-gonic/gin"
    "html/template"
    "time"
)

func formatDate(t time.Time) string {
    return t.Format("2006-01-02")
}

func main() {
    r := gin.Default()
    // 注册自定义函数
    r.SetFuncMap(template.FuncMap{
        "formatDate": formatDate,
    })
    r.LoadHTMLGlob("templates/**/*.tmpl")

    r.GET("/", func(c *gin.Context) {
        c.HTML(http.StatusOK, "index.tmpl", gin.H{
            "Now": time.Now(),
        })
    })

    r.Run(":8080")
}

在模板中使用自定义函数：

<p>当前日期：{{.Now | formatDate}}</p>

---

六、总结

Gin 对模板引擎的支持简洁高效，核心流程包括：

• 加载模板文件 ：使用 LoadHTMLGlob 或 LoadHTMLFiles。
• 定义模板内容：支持 Go 模板语法和继承。
• 在处理器中通过 c.HTML() 渲染并传递数据。

这种方式既保留了 Go 原生模板的强大功能，又通过 Gin 的封装简化了使用流程，非常适合需要服务端渲染 HTML 的场景。

无论你是开发简单的静态页面还是复杂的动态应用，Gin 的模板系统都能提供强大的支持。希望这篇文章能帮助你更好地理解和使用 Gin 中的模板引擎！