模板传值必须用ctx.viewdata，而非ctx.set；viewdata是请求级map[string]interface{}，需配合ctx.view调用，键名大小写敏感且struct字段须首字母大写；复用布局需提前调用ctx.viewlayout并使用{{template "content" .}}；不可在同个handler中混用ctx.view与ctx.json。
模板传值用 ctx.ViewData，不是 ctx.Set 或全局变量
很多人一上来就用 ctx.Set("title", "首页") 想把值塞进模板，结果渲染时全为空——ctx.Set 是给中间件或后续 handler 用的，跟模板渲染完全无关。Iris 的模板引擎（html/template 或 jet 等）只认 ctx.ViewData 这个 map[string]interface{} 类型的字段。
正确做法是：在 handler 里直接往 ctx.ViewData 写键值对，然后调用 ctx.View("path/to/template.html")：
func IndexHandler(ctx iris.Context) {
ctx.ViewData("Title", "用户列表")
ctx.ViewData("Users", []User{{ID: 1, Name: "张三"}, {ID: 2, Name: "李四"}})
ctx.View("admin/user.html")
}
-
ViewData是每次请求独立的，无需担心并发写冲突 - 键名大小写敏感，模板里必须用
{{.Title}}，不能写{{.title}} - 如果传 struct，字段必须首字母大写（即 exported），否则模板里读不到
ViewData 和 ViewLayout 配合才能复用头部/尾部
单独传值只能解决“内容区”，但真实项目里 header、footer、sidebar 都要复用。这时候必须配合 ctx.ViewLayout 设置布局文件，且布局中要用 {{template "content" .}} 显式声明内容插槽。
比如你有 views/layout.html：
<title>{{.Title}}</title><header>这里是公共头部</header>
{{template "content" .}}
<footer>© 2026</footer>
然后在 handler 中同时设 layout 和 data：
func AdminHandler(ctx iris.Context) {
ctx.ViewLayout("layout.html") // 必须在 View 前调用
ctx.ViewData("Title", "后台管理")
ctx.ViewData("ActiveMenu", "user")
ctx.View("admin/user.html")
}
-
ViewLayout必须在View之前调用，否则无效 - 布局文件里的
{{.}}指向的是当前ViewData，不是 layout 自己的数据 - 如果某个页面不想用 layout，显式调用
ctx.ViewLayout("")清空即可
前后端数据绑定靠前端框架，Iris 不做双向绑定
Iris 本身是服务端框架，它不提供 Vue 或 React 那种响应式双向绑定。所谓“绑定”，实际是两件事：后端吐 HTML 时把初始数据写进模板（静态注入），前端再用 JS 框架接管后续交互。
常见错误是试图让 {{.Username}} 在用户输入时自动更新——这不可能。Iris 渲染完 HTML 就结束了，后续 DOM 变化完全由前端控制。
- 正确姿势：后端用
ViewData注入初始状态（如表单默认值、用户信息），前端用 Vue 的v-model绑定 input，并通过 fetch 提交变更 - 如果强行想“服务端响应式”，得上 WebSockets 或 Server-Sent Events，但那就超出 Iris 模板能力范围了
- 注意 XSS：不要直接
{{.RawHTML}}，要用{{.RawHTML | safeHTML}}，且确保来源可信
JSON API 场景下别混用 ViewData 和 JSON
同一个 handler 里既调 ctx.View 又调 ctx.JSON 是典型错误。Iris 会 panic 报错：http: multiple response.WriteHeader calls。因为两者都尝试写 HTTP 头和 body。
判断标准很简单：返回 HTML 页面走 View + ViewData；返回结构化数据（如 AJAX 接口、移动端）走 JSON / XML / Text，此时 ViewData 完全无效。
- 前后端分离项目中，99% 的接口应该用
ctx.JSON，模板只用于 SSR 页面（如管理后台首页） - 如果路由需要两种行为，必须拆成两个 handler，或用
Accept请求头判断（但不推荐，增加复杂度） -
ctx.JSON传的 struct 字段也必须首字母大写，否则序列化出来是空对象
text/html 且没有 panic 日志。
