templ 快速入门：从零创建一个简单的 templ 组件并渲染 HTML

开发工具代码生成后端【免费下载链接】templA language for writing HTML user interfaces in Go.项目地址https://gitcode.com/gh_mirrors/te/templ点击查看免费下载导读本文基于 templ 官方快速入门指南编写带你从初始化一个 Go 项目开始逐步创建第一个 templ 组件理解templ generate如何把.templ文件编译为纯 Go 代码并最终通过io.Writer将组件渲染为 HTML 输出。读完本文你将掌握 templ 组件的定义语法、生成流程与渲染机制并能将组件输出到标准输出、文件乃至 HTTP 响应等任意实现了io.Writer的目标。templ 是一种在 Go 中编写 HTML 用户界面的语言组件是其中最小的复用单元本仓库的 examples/hello-world-ssr 与 examples/hello-world-static 正是与本文步骤一一对应的完整示例。准备工作安装 templ CLI在开始之前需要先安装 templ 命令行工具具体安装方式参见 官方安装文档。在已安装 Go 1.24 或更高版本的前提下最简单的全局安装方式是go install github.com/a-h/templ/cmd/templlatest也可以作为项目本地工具安装Go 1.24 的 tool directive 特性go get -tool github.com/a-h/templ/cmd/templlatest安装完成后本地安装场景下用go tool templ代替templ执行命令。本文后续命令均假设templ已在 PATH 中。第一步初始化 Go 项目首先创建一个新目录存放我们的项目mkdir hello-world进入目录并初始化 Go 模块然后拉取 templ 依赖cd hello-world go mod init github.com/a-h/templ-examples/hello-world go get github.com/a-h/templgo mod init会生成go.mod文件模块名这里以github.com/a-h/templ-examples/hello-world为例可以替换为你自己的仓库地址go get github.com/a-h/templ则会把 templ 运行时依赖写入模块供生成后的 Go 代码引用。第二步创建 templ 组件文件在项目根目录创建一个hello.templ文件内容如下package main templ hello(name string) { divHello, { name }/div }hello.templ本身就是一个标准的 Go 包package main其中templ hello(name string) { ... }定义了一个组件Component。组件的本质是包含 templ 元素、标记markup以及 Go 表达式、if、switch、for等控制语句的函数。这里需要注意几点组件函数名小写hello与普通 Go 函数一样遵循可见性规则参数name string是普通 Go 参数用于向组件内部传值大括号内的{ name }是表达式插值语法运行时会输出参数name的值。组件内部可以编排任意复杂的结构嵌套元素、属性、条件渲染、循环、CSS 样式与脚本等但本文聚焦最简形态其余语法可参考 基本语法文档。第三步用 templ generate 生成 Go 代码在项目目录执行templ generatetempl 会扫描项目从源码看cmd/templ/generatecmd/cmd.go 会递归遍历目录并逐个处理.templ文件为每个模板生成一个同名的_templ.go文件。对本例而言生成的是hello_templ.go其中包含一个名为hello的函数它接收name参数返回一个实现了templ.Component接口、能够渲染 HTML 的组件func hello(name string) templ.Component { // ... }仓库中 examples/hello-world-ssr/hello_templ.go 就是这份代码的真实完整形态摘录核心部分如下// Code generated by templ - DO NOT EDIT. package main import github.com/a-h/templ import templruntime github.com/a-h/templ/runtime func hello(name string) templ.Component { return templruntime.GeneratedTemplate(func(templ_7745c5c3_Input templruntime.GeneratedComponentInput) (templ_7745c5c3_Err error) { // ... templ_7745c5c3_Err templruntime.WriteString(templ_7745c5c3_Buffer, 1, divHello, ) // ... templ_7745c5c3_Var2, templ_7745c5c3_Err templ.JoinStringErrs(name) // ... _, templ_7745c5c3_Err templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var2)) // ... templ_7745c5c3_Err templruntime.WriteString(templ_7745c5c3_Buffer, 2, /div) // ... return nil }) }这段生成代码揭示了几个值得注意的实现细节文件头部带有// Code generated by templ - DO NOT EDIT.标记不要手动修改生成文件改模板后重新运行templ generate即可模板里的字面量 HTMLdivHello,与/div被拆成两段静态字符串写入插值表达式{ name }先经templ.JoinStringErrs(name)转为字符串再通过templ.EscapeString做 HTML 转义后写入这正是 templ 默认防 XSS 的机制详见下文若渲染中出错错误对象会携带模板文件的文件名、行号与列号如Line: 4, Col: 19方便定位到.templ源文件的出错位置。第四步编写程序将组件渲染到标准输出创建main.gopackage main import ( context os ) func main() { component : hello(John) component.Render(context.Background(), os.Stdout) }流程非常直观先调用生成的hello(John)得到一个templ.Component再调用其Render方法完成渲染。Render接收两个参数context.Context用于在渲染期间传递上下文状态例如子组件、脚本去重、CSP nonce 等详见 runtime.goio.Writer渲染结果的输出目标。第五步运行程序执行go run .控制台将输出divHello, John/div至此你已经完成了一个最小可用的 templ 组件从定义、生成到渲染的完整闭环。深入理解Component 接口与 io.Writer 抽象templ.Component是 templ 生态中最核心的接口定义在仓库根目录的 runtime.go 中// Component is the interface that all templates implement. type Component interface { // Render the template. Render(ctx context.Context, w io.Writer) error }也就是说任何 templ 组件本质都是一个Render(ctx, w) error函数。这一点在 runtime/runtime.go 中体现得更为直接——生成代码通过templruntime.GeneratedTemplate把内部渲染函数包装成标准组件func GeneratedTemplate(f func(GeneratedComponentInput) error) templ.Component { return templ.ComponentFunc(func(ctx context.Context, w io.Writer) error { return f(GeneratedComponentInput{ctx, w}) }) }明白了接口定义就不难理解原文档最后一段的表述传给Render的不一定是os.Stdout任何实现了io.Writer接口的类型都可以包括文件os.Create(out.html)返回的*os.File内存缓冲bytes.Buffer可用于后续字符串拼接或http.ResponseWriter包装HTTP 响应http.ResponseWriter本身就实现了io.Writer。利用这一点templ 组件可以被复用到多种输出场景生成静态 HTML 文件渲染结果写入文件后可托管到 S3 桶、Google Cloud Storage 等静态托管服务对应本仓库 examples/hello-world-static 与 静态渲染文档服务端渲染SSR在 HTTP handler 中直接渲染到http.ResponseWriter。仓库 examples/hello-world-ssr/main.go 展示了更完整的做法——通过templ.Handler(component)直接挂载到net/httpfunc main() { component : hello(John) http.Handle(/, templ.Handler(component)) fmt.Println(Listening on :3000) if err : http.ListenAndServe(:3000, nil); err ! nil { log.Fatalf(server error: %v, err) } }导出内容把组件渲染结果送入 PDF 转换流程或作为邮件 HTML 正文发送。安全机制默认的 HTML 转义生成代码中调用templ.EscapeString并非多余步骤。查看 runtime.go 的实现// EscapeString escapes HTML text within templates. func EscapeStringT ~string string { return html.EscapeString(string(s)) }它委托给 Go 标准库html.EscapeString会把、、、、等字符转义为 HTML 实体。这意味着插值表达式中的用户输入默认是安全的。例如把name换成scriptalert(xss)/script渲染输出会被转义成纯文本而不是被浏览器当作脚本执行。如果需要输出不受转义的原始 HTML必须显式使用templ.Raw之类的受控手段见 runtime.go 中Raw的注释警告——它只应接收可信来源的 HTML。小结回顾整个流程创建并使用一个 templ 组件只需要四步go mod initgo get github.com/a-h/templ初始化项目编写hello.templ定义组件templ generate生成_templ.go代码调用组件并Render(ctx, w)到任意io.Writer。templ 的价值在于.templ文件保持模板的可读性而生成出的纯 Go 代码完全类型安全、可编译、可测试且与标准库context、io无缝协作。在此基础上你可以继续学习 基本语法、组件与组合、模板生成机制 等进阶主题或直接运行 hello-world-ssr 示例 体验服务端渲染的完整形态。赞分享开发工具代码生成后端【免费下载链接】templA language for writing HTML user interfaces in Go.项目地址https://gitcode.com/gh_mirrors/te/templ点击查看免费下载相关推荐使用a-h/templ项目创建简单组件的快速入门指南使用a h/templ项目创建简单组件的快速入门指南 前言 在现代Web开发中组件化开发模式已经成为主流。a h/templ项目为Go语言开发者提供了一种高效开发工具代码生成后端templ Elements 深度指南在 Go 组件中渲染 HTML 元素templ Elements 深度指南在 Go 组件中渲染 HTML 元素 templ 是一种用 Go 编写 HTML 用户界面的语言。在 templ 组件中开发工具代码生成后端使用 templ 构建静态博客站点从 Markdown 渲染到纯静态 HTML 文件使用 templ 构建静态博客站点从 Markdown 渲染到纯静态 HTML 文件 这篇指南以 templ 仓库中的静态博客示例为核心完整演示如何用 te开发工具代码生成后端上一篇解决Video-Downloader常见问题下载失败看这篇就够了下一篇CodingInterviews图论基础树的遍历与路径查找实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考