如何在Go Template中向子模板传递多个参数？

Go 的 text/template 和 html/template 在服务端渲染、配置文件生成等场景中非常常见。模板嵌套复用能把页头、页脚、卡片等公共片段抽离出来，但当子模板需要同时接收多个数据时，事情往往变得不那么顺手。标准语法里 {{template "name" .}} 只有一个点号上下文，如果想把用户名、未读消息数和导航高亮状态一起传进去，直接写多个参数是不被支持的。下面会从上下文传递机制开始，拆解几种实用的传参方案。

一、为什么 template 只能传一个参数

在 Go 模板的执行模型中，子模板调用动作的语法是 {{template "name" pipeline}}，其中 pipeline 是一个管道表达式，它最终只会产生一个值作为子模板的点号上下文。也就是说，模板引擎不会像普通函数调用那样支持 {{template "name" .User .Count}} 这种写法。如果你尝试这样做，解析阶段就会报错，因为模板语法根本没有预留多参数位置。

这个设计源于 Go 模板把数据上下文和展示逻辑分离的思路。父模板传递给子模板的应该是已经组织好的数据，而不是让模板负责参数的收集和重排。不过实际项目中，页面数据结构往往按页面组织，组件字段分散在多个父级字段里，直接传根对象虽然可以让子模板用 {{.User.Name}} 和 {{.Unread}} 访问到所有数据，但会让子模板紧密依赖根数据结构，复用性下降。因此需要在模板层或数据层做一些轻量适配。

一个最典型的失败示例如下：父模板想同时传标题和数量给卡片子模板，但只能传一个字符串。

package main

import (
    "os"
    "text/template"
)

const tpl = `{{define "card"}}
<div class="card">
    <h2>{{.}}</h2>
    <span>{{.}}</span>
</div>
{{end}}

{{template "card" .Title}}
`

func main() {
    data := map[string]interface{}{
        "Title": "Go Template",
        "Count": 42,
    }
    t := template.Must(template.New("main").Parse(tpl))
    t.Execute(os.Stdout, data)
}

这段代码中，卡片模板里的 {{.}} 只能拿到 .Title 的值，Count 根本没有进入子模板。要解决这个问题，核心思路就是想办法把多个字段打包成一个值，再通过那个唯一的点号传进去。

二、注册 dict 函数动态构造 map

最灵活的方式是在模板中临时构造一个 map。Go 标准模板引擎本身没有提供 dict 函数，但可以通过 FuncMap 注册一个自定义函数，让它接收任意数量的键值对并返回 map。这样在父模板里可以先拼装参数，再传给子模板。

下面是一个 dict 函数的简单实现，它会检查参数个数是否为偶数，并将奇数位参数作为字符串键、偶数位参数作为值写入 map。

package main

import (
    "errors"
    "os"
    "text/template"
)

func dict(values ...interface{}) (map[string]interface{}, error) {
    if len(values)%2 != 0 {
        return nil, errors.New("dict requires even number of arguments")
    }
    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, errors.New("dict key must be string")
        }
        m[key] = values[i+1]
    }
    return m, nil
}

const tpl = `{{define "card"}}
<div class="card">
    <h2>{{.title}}</h2>
    <span>{{.count}}</span>
</div>
{{end}}

{{$args := dict "title" .Title "count" .Count}}
{{template "card" $args}}
`

func main() {
    data := map[string]interface{}{
        "Title": "Go Template",
        "Count": 42,
    }
    t := template.Must(template.New("main").Funcs(template.FuncMap{
        "dict": dict,
    }).Parse(tpl))
    t.Execute(os.Stdout, data)
}

这里的关键在于先声明变量 $args，用 dict 函数把标题和数量包成 map，再把这个 map 作为唯一上下文交给子模板。子模板内部使用 {{.title}} 和 {{.count}} 访问 map 的键。由于模板不能直接写 map 字面量，dict 函数实际上承担了数据字面量的角色。如果你不想自己实现，也可以直接使用 Sprig 模板函数库，其中已经内置了 dict、list 等工具函数。

这种方案最大的好处是灵活，模板里可以按需组合任何字段，不用提前修改 Go 数据结构。但也有代价：map 是动态类型，字段名没有编译期检查；dict 每次渲染都会分配新的 map，高频渲染会带来少量内存开销；如果键写错，例如 .Title 写成 .title 但传参时键用 title，可能因大小写不一致导致空值。因此它更适合原型阶段或字段变动频繁的场景。

三、用结构体或 map 在数据层预组装参数

更符合 Go 工程习惯的做法是在进入模板之前就把子模板需要的数据组合好。定义一个结构体，字段与子模板展示内容一一对应，父模板只负责把它传给子模板。这样的模板逻辑非常干净，字段名也有类型约束。

例如我们可以把卡片信息定义成一个 Card 结构体，并在页面数据里直接携带它。

package main

import (
    "os"
    "text/template"
)

type Card struct {
    Title string
    Count int
}

type PageData struct {
    Card Card
}

const tpl = `{{define "card"}}
<div class="card">
    <h2>{{.Title}}</h2>
    <span>{{.Count}}</span>
</div>
{{end}}

{{template "card" .Card}}
`

func main() {
    t := template.Must(template.New("main").Parse(tpl))
    t.Execute(os.Stdout, PageData{
        Card: Card{
            Title: "Go Template",
            Count: 42,
        },
    })
}

这个例子中，子模板通过 {{.Title}} 和 {{.Count}} 访问结构体字段，语义直观。如果不是结构体，而是嵌套的 map，同样可以在 Go 代码里组织成 map[string]interface{}，模板里的访问方式完全一样。与 dict 方案相比，预组装的字段名和类型在编译期就能被发现，尤其是结构体字段拼写错误会直接导致模板执行报错。

当然，这种方案的缺点是模板与数据结构耦合更紧密。当子模板需要的字段发生变化时，通常要同步修改 Go 结构体和模板两处。另外，如果页面有很多个组件，数据层会变得比较啰嗦。但对于长期维护的项目来说，显式的结构体通常比动态 map 更容易理解和调试，推荐优先使用。

四、用切片和 index 按位置传参

如果几个参数的类型一致，或者参数数量很少且顺序固定，还可以用切片来传递。子模板中使用 Go 模板内置的 index 函数按位置读取数据。

比如页面数据中有一个 CardArgs 字段，它是 []interface{}{"Go Template", 42}。父模板把整个切片传给子模板，子模板通过 {{index . 0}} 和 {{index . 1}} 取值。

package main

import (
    "os"
    "text/template"
)

const tpl = `{{define "card"}}
<h2>{{index . 0}}</h2>
<span>{{index . 1}}</span>
{{end}}

{{template "card" .CardArgs}}
`

func main() {
    data := struct {
        CardArgs []interface{}
    }{
        CardArgs: []interface{}{"Go Template", 42},
    }
    t := template.Must(template.New("main").Parse(tpl))
    t.Execute(os.Stdout, data)
}

如果希望像 dict 那样在模板内临时构造切片，可以注册一个 list 函数，例如 Sprig 中的 list，然后书写 {{template "card" (list .Title .Count)}}。但标准库并不提供这个函数，需要自己注册或者引入第三方函数库。

切片方案的优点是非常轻量，不需要定义结构体，也不需要额外的 map 键。缺点是参数位置没有语义，一旦顺序调整，所有用到该子模板的地方都可能出错；而且 index 按位置访问对阅读者不够友好。因此它适合那种参数只有两三个、作用域很小、顺序约定明确的内部模板片段，不建议在大型模板体系中广泛使用。

五、方案对比与避坑建议

如果从工程化角度选型，三者的优先级可以这样排：数据层预组装结构体最常见，适合页面数据结构清晰的场景；dict 函数适合需要快速试错或组件字段经常变动的模板；切片按位置传参只适合极小范围的私有模板。无论选择哪种，核心原则都是让父模板只负责传递已经归组好的数据，子模板只关心自己需要的字段，不要把整个根对象到处传递。

使用 html/template 时还需要注意安全转义问题。子模板接收到的 map 或结构体字段如果包含用户输入，html/template 会根据上下文自动转义。但这并不意味着可以放松输入校验，尤其是通过 dict 临时拼装的字符串，一旦拼接了未经验证的 HTML 片段，仍然可能破坏页面结构。对于复杂组件，建议在 Go 数据层提前完成数据清洗和类型转换。

另外，模板函数的错误处理也要留意。像 dict 函数返回 error 时，模板变量赋值默认会忽略第二个返回值，如果参数个数写错，渲染可能得到 nil 而不是明确报错。如果你希望更严格，可以显式声明两个变量：{{$args, $err := dict "title" .Title}}，并在错误分支里输出提示，这样便于定位问题。最后，不必过度追求模板层能力，Go 的设计哲学更倾向于在数据层完成数据组装，模板保持简单的展示逻辑，这样的代码往往更稳。

Go Template子模板参数传递修改时间：2026-09-19 04:59:20