Thymeleaf中文网

深色模式

8 模板布局 ​

8.1 包含模板片段 ​

定义和引用片段 ​

在模板开发中，我们经常需要复用其他模板中的部分内容（比如页脚、页眉、导航菜单等）。

要实现这一点，Thymeleaf 要求我们先把这些可复用的内容定义为“片段（fragment）”，具体通过 th:fragment 属性来完成。

假设我们要给所有生鲜电商页面添加统一的版权页脚，首先创建 /WEB-INF/templates/footer.html 文件，用 th:fragment 定义名为 copy 的片段：

html
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
  <body>
    <!-- 定义名为 copy 的模板片段 -->
    <div th:fragment="copy">
      &copy; 2011 The Good Thymes Virtual Grocery
    </div>
  </body>
</html>

定义好片段后，就可以在首页等其他模板中通过 th:insert 或 th:replace 属性引入这个片段，核心语法是片段表达式 ~{...}：

html
<body>
  <!-- 页面主体内容 -->
  ...

  <!-- 引入 footer.html 中名为 copy 的片段 -->
  <div th:insert="~{footer :: copy}"></div>
</body>

需要注意的是，th:insert 接收一个片段表达式（~{...}）—— 这是一种会返回片段内容的表达式。

核心语法说明 ​

  1. 片段表达式格式：~{模板名 :: 片段名}

    • footer：片段所在的模板文件名（无需写路径后缀，Thymeleaf 会自动匹配 /WEB-INF/templates/ 下的 footer.html）；
    • :: copy：指定要引入的片段名称（即 th:fragment 定义的 copy）；
    • 片段表达式 ~{...} 是 th:insert/th:replace 的必填参数，其作用是定位到具体的模板片段。

  2. 简化写法（可选）： Thymeleaf 允许省略片段表达式的包裹符 ~{}，直接写 模板名 :: 片段名，效果完全一致：

    html
    <!-- 简化写法，与 ~{footer :: copy} 等价 -->
<div th:insert="footer :: copy"></div>

关键注意点 ​

  • th:insert 的作用是将片段内容插入到当前标签内（比如上面的示例中，copy 片段的 <div> 会被插入到当前 <div th:insert="..."> 内部）；
  • 后续会讲到的 th:replace 则是用片段内容替换当前标签（两者是最常用的片段引入方式，核心区别见后续章节）；
  • 片段文件的路径：如果片段不在 /WEB-INF/templates/ 根目录，需要写相对路径（比如 common/footer :: copy 对应 /WEB-INF/templates/common/footer.html）。

总结 ​

  1. 用 th:fragment="片段名" 可以在模板中定义可复用的内容片段；
  2. 用 th:insert="~{模板名 :: 片段名}" 可以引入其他模板中的片段，片段表达式 ~{...} 是定位片段的核心；
  3. 模板片段是实现页面布局复用的基础，适合抽离页眉、页脚、导航等通用内容。