在 Go 的 html/template 中,当页面拆分为多个模板片段时,子模板的数据来源常常成为渲染结果异常的原因。define 用于声明一个命名模板,template 动作负责把该命名模板包含进来;但数据并不会因为包含关系而自动传递。很多情况下,开发者以为子模板已经拿到了页面数据,结果却发现标题为空、列表不显示,甚至执行时直接报 nil 指针错误。本文会从基础传参规则开始,说明如何显式、安全地把数据传给被包含的子模板,并延伸到复杂数据结构、作用域变化和 block 的使用。

子模板中的数据传递基础
在 html/template 中,子模板通过 {{define "名称"}}...{{end}} 定义,使用 {{template "名称" .}} 包含。第二个参数就是传给子模板的数据,常用点号表示当前上下文。例如父模板中定义整体布局,需要把标题传给头部子模板时,可以这样写:
package main
import (
"html/template"
"os"
)
const tpl = `{{define "layout"}}<!DOCTYPE html>
<html>
<head><title>{{.Title}}</title></head>
<body>
{{template "header" .}}
</body>
</html>
{{end}}
{{define "header"}}<h1>{{.Title}}</h1>{{end}}`
type Page struct {
Title string
}
func main() {
t := template.Must(template.New("page").Parse(tpl))
t.ExecuteTemplate(os.Stdout, "layout", Page{Title: "Go 模板"})
}
如果将第二个参数省略,写成 {{template "header"}},子模板内部的点号会被设置为 nil,这时访问 .Title 会在执行阶段报错。html/template 不会自动把父模板的点号带给子模板,必须显式写明。传入整个对象是最常见的做法,但也可以只传某个字段,例如 {{template "header" .Title}},这样子模板里可以直接用 {{.}} 输出字符串。
实际项目中建议先确定子模板需要哪些字段,再决定传入整个结构体还是单一字段。如果子模板依赖多个不相关数据,下一节会介绍更合适的数据包装方式。
传递结构体、map 和管道数据
在真实项目中,一个子模板可能需要多个数据。例如侧边栏需要导航项、当前用户、是否显示广告位等。这时可以把子模板设计为接收一个结构体或 map,子模板内部通过点号访问字段或键。最佳实践是在 Go 代码中定义专门的视图模型结构体,而不是依赖动态 map。结构体字段有类型检查,模板渲染时若字段拼错会在解析阶段报错;map 拼错只会在渲染时得到空值,不利于排查。
下面示例定义了一个 SidebarData 结构体,父模板调用子模板时传入 .Sidebar:
package main
import (
"html/template"
"os"
)
const tpl = `{{define "layout"}}{{template "sidebar" .Sidebar}}{{end}}
{{define "sidebar"}}{{.UserName}} has {{len .Items}} items.{{end}}`
type User struct {
Name string
}
type SidebarData struct {
UserName string
Items []string
}
type Page struct {
Sidebar SidebarData
}
func main() {
t := template.Must(template.New("page").Parse(tpl))
t.ExecuteTemplate(os.Stdout, "layout", Page{
Sidebar: SidebarData{UserName: "小明", Items: []string{"a", "b"}},
})
}
除了直接传结构体字段,管道和函数也可以参与数据传递。如果需要在传入前对数据做处理,可以在 template 动作的第二个参数位置使用管道表达式。例如 {{template "badge" (printf "%s 级" .Level)}},将格式化后的结果传给子模板。管道表达式的返回值会成为子模板的输入数据,类型要与子模板内部字段访问预期一致。
使用 map 时,子模板内部可以用 .UserName 访问键,但要求 map 的 key 类型是 string,value 类型是 interface{} 或具体类型。结构体的类型安全优势明显,更适合长期维护的项目。
作用域改变带来的数据遮蔽问题
范围动作 range、with 会改变点号指向。当父模板在 range 内部调用子模板时,如果仍然使用 {{template "item" .}},点号已经是当前遍历元素,而不是外层页面数据。此时如果子模板期望的是完整页面对象,就会拿错数据。类似的,with 会把点号替换为指定对象,内部的 . 不再是根数据。
解决方案是用模板变量在进入子作用域前保存外层上下文。语法为 {{$page := .}}。变量在定义后的作用域内可见,包括嵌套的 range、with 块。例如父模板遍历文章列表时,需要把每篇文章和当前登录用户一起传给子模板时,可以先保存页面数据再组合。下面演示用变量解决点号遮蔽:
package main
import (
"html/template"
"os"
)
const tpl = `{{define "layout"}}{{$page := .}}{{range $page.Articles}}{{template "article" .}}{{end}}{{end}}
{{define "article"}}{{.Title}} by {{.Author}}{{end}}`
type Article struct {
Title string
Author string
}
type Page struct {
Articles []Article
}
func main() {
t := template.Must(template.New("page").Parse(tpl))
t.ExecuteTemplate(os.Stdout, "layout", Page{
Articles: []Article{{Title: "Go 模板", Author: "张三"}},
})
}
如果子模板还需要同时访问外层用户数据,只传入当前元素就会遗漏字段。这时不能指望 {{template "article-card" .}} 同时携带多个对象,需要借助组合结构体或 map。无论如何,进入 range 或 with 之前利用 {{$root := .}} 保存原始数据,是避免作用域遮蔽影响传参的最直接方法。出现字段消失、空值或类型错误时,先检查点号指向是否已被动作修改。
使用 block 与模板函数优化传参
block 动作是 define 和 template 的简写形式,适合布局中提供默认内容并允许覆盖的场景。它同样遵守显式传参规则。例如基础布局中定义侧边栏默认内容,页面模板可以覆盖它;默认内容也需要数据时,写入 {{block "sidebar" .}}默认侧边栏,欢迎 {{.User.Name}}{{end}}。这里点号就是外部传入的数据,不会因为 block 的存在而自动继承父级上下文。
如果子模板依赖的数据需要从多个来源拼装,而模板中不能方便地创建结构体字面量,可以通过注册模板函数来解决。一个常见的做法是注册 dict 函数,接收键值对并返回 map。下面示例在 range 内部同时把当前文章和根数据中的用户一起传给子模板:
package main
import (
"html/template"
"os"
)
func dict(values ...interface{}) (map[string]interface{}, error) {
if len(values)%2 != 0 {
return nil, nil
}
m := make(map[string]interface{}, len(values)/2)
for i := 0; i < len(values); i += 2 {
key, ok := values[i].(string)
if !ok {
return nil, nil
}
m[key] = values[i+1]
}
return m, nil
}
const tpl = `{{define "layout"}}{{$page := .}}{{range .Articles}}{{template "article-card" (dict "Article" . "User" $page.User)}}{{end}}{{end}}
{{define "article-card"}}{{.User.Name}} 发布了 {{.Article.Title}}{{end}}`
type Article struct {
Title string
}
type User struct {
Name string
}
type Page struct {
Articles []Article
User User
}
func main() {
t := template.Must(template.New("page").Funcs(template.FuncMap{"dict": dict}).Parse(tpl))
t.ExecuteTemplate(os.Stdout, "layout", Page{
User: User{Name: "张三"},
Articles: []Article{{Title: "第一篇"}},
})
}
不过要注意,dict 函数返回 map 时,若键拼写错误,只会在渲染时得到空值,不会像结构体字段那样在解析时报错。生产环境建议把这类组合数据提前在 Go 代码中组装,减少模板中的逻辑。函数注册适合少量动态组装场景。使用 block 时同样可以传递组合数据,不必改变点号以外的规则。
正确传递数据到子模板的核心是记住模板引擎不会自动传递上下文,每个 template 或 block 动作都要显式提供第二个参数。对于简单场景传点号或字段即可;复杂场景借助结构体、map、管道和自定义函数。作用域变化时先用变量保存外层数据,避免点号遮蔽。掌握这些规则后,Go 的 html/template 视图组合会更加可靠。
Go html/template子模板传参模板数据传递修改时间:2026-11-03 12:53:48