Thymeleaf中文网

深色模式

4.5 片段表达式 ​

片段表达式是 Thymeleaf 中表示标记片段、并在模板间传递复用这些片段的便捷方式。通过它，我们可以复制标记片段、将片段作为参数传递给其他模板等。

片段表达式最常见的用途是结合 th:insert 或 th:replace 插入模板片段（这两个属性的详细用法会在后续章节讲解）：

html
<!-- 插入 commons 模板中名为 main 的片段 -->
<div th:insert="~{commons :: main}">...</div>

片段表达式也能像普通变量一样在任意位置使用，比如通过 th:with 定义片段变量，再插入使用：

html
<!-- 1. 定义片段变量：获取 footer 模板中 id 为 main 的元素的文本内容片段 -->
<!-- 2. 插入该片段变量 -->
<div th:with="frag=~{footer :: #main/text()}">
  <p th:insert="${frag}"></p>
</div>

注：本教程后续会有一整个章节讲解“模板布局（Template Layout）”，其中会深入解释片段表达式的所有高级用法。

核心语法解释 ​

  1. 片段表达式的基本格式： ~{模板名 :: 片段选择器}

    • 模板名：目标片段所在的模板文件名称（如 commons 对应 commons.html）；
    • 片段选择器：定位片段的规则，支持两种方式：
      • 命名片段：main（匹配通过 th:fragment="main" 定义的命名片段）；
      • 选择器片段：#main/text()（CSS 选择器语法，如 #main 匹配 id 为 main 的元素，/text() 仅提取其文本内容）。

  2. th:insert 的作用： 将片段表达式指定的标记片段，插入到当前标签的内部（保留当前标签）；而 th:replace 则会用目标片段替换当前标签（后续会详细对比）。

  3. 片段变量的价值： 通过 th:with 将片段赋值给变量（如 frag），可实现片段的复用、动态传递，尤其适合需要根据条件切换不同片段的场景（比如：th:insert="${isAdmin ? adminFrag : userFrag}"）。

简单示例：定义+引用命名片段 ​

先在 commons.html 中定义命名片段：

html
<!-- commons.html -->
<div th:fragment="main">
  <p>这是通用的主内容片段</p>
</div>

再在其他模板中引用该片段：

html
<!-- 首页引用 commons 中的 main 片段 -->
<div th:insert="~{commons :: main}">
  <!-- 静态占位内容，处理后会被片段替换 -->
  主内容区域
</div>

总结 ​

  1. 片段表达式 ~{...} 是 Thymeleaf 实现模板复用的核心语法，可定位并引用任意模板中的标记片段。
  2. 最常用场景是结合 th:insert/th:replace 插入命名片段，也可通过 th:with 定义为变量灵活使用。
  3. 片段选择器支持命名片段和 CSS 选择器两种方式，后续“模板布局”章节会讲解更多高级用法（如片段参数、布局复用等）。