Thymeleaf中文网

深色模式

11.3 Thymeleaf仅原型注释块 ​

Thymeleaf 的「仅原型注释块（prototype-only comment blocks）」是一种反向的注释机制：静态预览（原型模式）时，内容以注释形式隐藏；Thymeleaf 处理模板时，注释标记被移除，内容变为正常标记执行。

简单来说：它让模板在浏览器直接打开时“隐藏”动态代码，Thymeleaf 解析时“激活”这些动态代码，兼顾原型的整洁性和动态渲染的正确性。

html
<span>hello!</span>
<!--/*/
  <!-- 静态预览时：这部分是注释（隐藏）；Thymeleaf 处理时：注释标记被移除，内容正常执行 -->
  <div th:text="${user.name}">用户名</div>
/*/-->
<span>goodbye!</span>

Thymeleaf 解析模板时，只会移除 <!--/*/ 和 /*/--> 这两个标记，保留中间的所有内容，因此上述代码会被解析为：

html
<span>hello!</span>
 
  <div th:text="${user.name}">用户名</div>
 
<span>goodbye!</span>

与解析级注释块一样，它的生效不依赖于任何特定的方言（你不需要在你的方言配置中启用或声明它，引擎在解析阶段就会直接处理它）。

核心特征对比 ​

为了更清晰区分三种注释，整理对比表如下：

注释类型语法格式静态预览（原型）Thymeleaf 处理后最终渲染结果
标准 HTML 注释<!-- ... -->内容隐藏内容原样保留（不解析）注释+内容原样输出
解析级注释块<!--/* ... */-->内容可见内容完全移除无残留
仅原型注释块<!--/*/ ... /*/-->内容隐藏注释标记移除，内容执行内容正常渲染（无注释标记）

典型使用场景 ​

  • 隐藏动态代码，让原型更简洁：模板中包含大量动态逻辑（如条件渲染、遍历），静态预览时不需要显示这些未渲染的占位符，用仅原型注释块包裹后，原型页面更整洁；
  • 兼容静态/动态两种模式：同一模板既可以作为静态原型预览，又能被 Thymeleaf 处理为动态页面，无需拆分文件；
  • 临时隐藏动态代码（调试）：开发时临时用该注释包裹动态代码，静态预览时只看静态内容，调试完成后无需删除注释（Thymeleaf 处理时会自动激活）。

关键注意事项 ​

  • 标记完整性：必须严格使用 <!--/*/ 开头、/*/--> 结尾，中间内容可任意换行，标记缺失会导致解析异常；
  • 内容执行性：包裹的内容在 Thymeleaf 处理时会完全执行（如 th:text、th:each 等），并非仅显示静态内容；
  • 方言无关：该特性是 Thymeleaf 核心解析器的功能，与使用的方言（如 Standard Dialect）无关，所有 Thymeleaf 模板都支持。

总结 ​

  1. 仅原型注释块 <!--/*/ ... /*/--> 的核心逻辑是“原型隐藏、解析激活”：静态预览时内容为注释（隐藏），Thymeleaf 处理时移除注释标记，内容正常执行；
  2. 与解析级注释块（原型可见、解析移除）是反向机制，分别解决“原型需要显示模拟数据”和“原型需要隐藏动态代码”的问题；
  3. 语法简单且方言无关，是兼顾静态原型整洁性和动态渲染正确性的实用工具。