templui

templUI 和 shadcn-templ

先确定生成版本

在选择示例或安装依赖前，检查 go.mod、组件导入、.templui.json、components.json 和本地组件源码。复制的 v1 组件可能没有模块依赖；如果没有对应的架构和来源信息，仅凭 components.json 并不足以判断。

• 旧版： github.com/templui/templui、.templui.json、v1 组件源码，或原始 templUI Pro/goilerplate v1–v2 区块。修改依赖这些内容的部分前，先询问用户是否要升级。
• 当前版： github.com/axadrn/shadcn-templ/v2 或 shadcn-templ v2 配置/源码。请阅读 shadcn-templ.md；下方的 v1 示例不一定适用。
• 混合/未知： 检查实际 API，并询问目标版本。

每当新任务中遇到旧版用法时，都要询问：

此项目使用旧版 templUI v1。你想升级到 shadcn-templ，还是在此任务中继续使用 v1？

如果有可用的当前界面提问功能，请使用并等待回答，再进行依赖该回答的编辑。只读检查可以继续。尊重用户在本任务中已经明确作出的选择；后续任务再次遇到旧版用法时，重新询问。如果要升级，请说明组件、CSS 和 JavaScript 的变更，并在编辑前确认迁移范围。不要将 UI 升级解读为允许使用 goilerplate 重新生成应用。

对于新项目，推荐 shadcn-templ，并核实其当前发布状态（v2 文档目前将其标为 beta）。如果用户选择 v1，请使用下方的旧版参考资料。不要通过较旧的脚手架模板悄然引入 v1。

原有的 222 个高级区块已冻结在 v1 中，与新的公开版 shadcn-templ 区块不同。如果有已安装的私有 templui-pro 技能可用，请用它查阅授权的旧版目录。否则，请向用户索取其授权使用的本地库；不要臆造高级版源码，也不要将其打包进此插件。

旧版 v1 指南

仅在用户选择当前任务继续使用 v1 后，才使用以下内容。

重要：templUI 使用原生 JavaScript（不使用 JS 框架）

根据 templui.io：“不使用 JS 框架——纯原生，快速至上。” templUI 组件通过 Script() 模板使用原生 JavaScript 实现所有交互功能（弹出层、下拉菜单、对话框、选项卡等）。它们不依赖 Alpine.js、React、Vue 或其他任何框架。

早期版本的 templUI 集成了 Alpine.js。现在这一依赖已移除。 如果你发现文档或代码在 templUI 组件中引用了 x-data/x-show/x-if 指令，那就是过时内容。

前端技术栈

工具	用途	适用场景
templUI	预构建 UI 组件（原生 JS）	下拉菜单、对话框、选项卡、侧边栏、弹出层、折叠面板
HTMX	服务端驱动的交互	AJAX、表单提交、局部页面更新、实时搜索
Alpine.js (可选)	轻量级客户端状态管理	切换、动画、客户端筛选、过渡效果——与 templUI 搭配使用，而非与其集成。如果除 HTMX + Script() 提供的功能外不需要响应式状态层，则无需使用。
Floating UI	定位基础组件（templUI 内部使用）	工具提示、弹出层、下拉菜单——通常对用户透明

---

参考文件

阅读相关文件，了解详细模式、代码示例和故障排查方法：

htmx-alpine-integration.md — HTMX + Alpine.js（可选，与 templUI 分开）

适用于选择在 templUI 之外添加 Alpine.js 作为客户端状态层的应用。仅在实际使用 Alpine 时阅读。内容包括：何时使用 HTMX、Alpine 或两者结合；用于在交换内容期间保留状态的 Alpine-Morph 扩展；在 Alpine 条件语句中使用 htmx.process()；从 Alpine 触发 HTMX。如果应用使用 templUI + HTMX + Script()，而不使用 Alpine，则跳过此文件——这是 templUI 推荐的配置。

templ-interpolation.md — 关键：JavaScript 中的 Templ 插值

Go 表达式 { value } 在 <script> 标签内不会进行插值。可用以下五种模式解决：

1. 数据属性（推荐）——data-* 属性 + this.dataset
2. templ.JSFuncCall——自动进行 JSON 编码，防止 XSS
3. 双花括号——在 <script> 标签内使用 {{ value }}
4. templ.JSONString——通过属性或 templ.JSONScript 处理复杂结构体/映射
5. templ.OnceHandle——确保脚本在循环中只渲染一次

包含使用场景对照表和常见错误。

templui-cli.md — templUI CLI 工具

安装、初始化、添加组件、强制更新以及查看可用组件。选择与现有项目匹配的模块导入或 CLI 复制工作流；两者使用不同的导入路径。

script-templates.md — Script() 模板（必需）

包含 JavaScript 的组件需要在基础布局 <head> 中调用 Script()。列出所有 Script() 导入项（popover、dropdown、dialog、accordion、tabs、carousel、toast、clipboard）、组件依赖关系表，以及组件无法正常工作时的故障排查方法。

conversion-and-audit.md — 网站转换与审查

将 HTML/React/Vue 转换为 Go/Templ：流程、语法映射、包结构。Templ 语法速查（属性、条件、循环、组合）。Script() 调用、CLI 安装、一致性、暗色模式、响应式设计的审查清单。导入模式和故障排查指南。templUI、HTMX+Alpine 和 templ 文档的资源链接。