在 Java Web 开发中模板引擎是连接后端数据与前端页面的重要桥梁而Thymeleaf凭借其自然模板特性、对 Web 标准的良好支持以及与 Spring 生态的无缝整合成为了 Spring Boot 官方推荐的模板引擎。它摒弃了 JSP 的脚本式开发以优雅的属性式语法实现前后端数据绑定同时让模板文件可直接作为静态原型在浏览器中运行极大提升了开发与设计团队的协作效率。本文基于 Thymeleaf 3.0.9.RELEASE 官方文档从核心概念、语法体系、常用功能到高级特性全面解析 Thymeleaf 的使用方法带你从入门到精通轻松掌握企业级开发所需的核心技能。一、Thymeleaf 核心认知1.1 什么是 ThymeleafThymeleaf 是一款现代的服务端 Java 模板引擎支持处理 HTML、XML、JavaScript、CSS 甚至纯文本等多种模板类型核心目标是提供优雅、高可维护性的模板创建方式。其最大特色是自然模板Natural Templates模板文件无需处理即可作为静态 HTML 原型在浏览器中运行Thymeleaf 的逻辑通过自定义属性注入浏览器会自动忽略这些未识别的属性实现了设计原型与开发模板的统一解决了设计与开发团队的协作鸿沟。同时Thymeleaf 从设计之初就遵循 Web 标准尤其是 HTML5可创建完全符合规范的模板文件兼顾开发性与规范性。1.2 六大模板模式Template ModeThymeleaf 原生支持六种模板模式覆盖不同的开发场景分为标记型、文本型和无操作型三类表格模板模式类型适用场景核心特点HTML标记型Web 页面开发主流支持 HTML5/4/XHTML不做格式校验最大程度保留模板结构XML标记型XML 文档处理要求格式良好无未闭合标签、无未引号属性格式错误会抛出异常TEXT文本型纯文本模板如邮件、文档使用特殊语法将 HTML/XML 作为纯文本处理不解析标签JAVASCRIPT文本型JavaScript 文件处理支持在 JS 中使用后端模型数据提供 JS 专属的转义与自然脚本支持CSS文本型CSS 文件处理支持在 CSS 中绑定后端数据实现样式的动态化RAW无操作型静态资源引入不处理模板内容直接原样输出适用于引入外部不受控的 HTML 资源1.3 方言Dialect与标准方言Thymeleaf 是高度可扩展的模板引擎其核心处理逻辑通过方言Dialect定义。方言由一系列处理器Processor组成处理器负责对模板中的标记标签、文本、注释应用具体的处理逻辑。Thymeleaf 核心库提供了标准方言Standard Dialect满足绝大多数开发需求本文所有语法均基于标准方言。而与 Spring 整合时会使用SpringStandard Dialectspring3/4 整合包提供它对标准方言做了轻量适配将 OGNL 表达式替换为 SpringEL其余用法完全一致。标准方言的处理器以属性处理器为主这也是 Thymeleaf 能实现自然模板的关键 —— 浏览器会忽略未知的th:*属性让模板可直接运行。二、Thymeleaf 环境搭建与核心初始化2.1 核心依赖Spring Boot 场景Spring Boot 对 Thymeleaf 做了自动配置引入以下依赖即可快速集成无需手动配置模板引擎xmldependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency默认情况下Spring Boot 会自动配置模板解析器、模板引擎默认的模板文件目录为src/main/resources/templates/静态资源目录为src/main/resources/static/。2.2 原生环境模板引擎初始化非 Spring Boot 环境下需要手动初始化 Thymeleaf 的核心组件模板解析器TemplateResolver和模板引擎TemplateEngine核心步骤如下创建模板解析器指定模板存储位置、模板模式、前缀 / 后缀等配置模板引擎绑定模板解析器完成引擎初始化创建上下文Context封装后端模型数据与本地化信息处理模板通过模板引擎将模板与上下文数据结合输出结果。核心代码示例Servlet 环境java运行// 1. 创建Servlet上下文模板解析器 ServletContextTemplateResolver templateResolver new ServletContextTemplateResolver(servletContext); templateResolver.setTemplateMode(TemplateMode.HTML); // 模板模式 templateResolver.setPrefix(/WEB-INF/templates/); // 模板前缀 templateResolver.setSuffix(.html); // 模板后缀 templateResolver.setCacheTTLMs(3600000L); // 模板缓存有效期1小时 templateResolver.setCacheable(true); // 开启模板缓存生产环境推荐 // 2. 初始化模板引擎并绑定解析器 TemplateEngine templateEngine new TemplateEngine(); templateEngine.setTemplateResolver(templateResolver); // 3. 创建Web上下文封装数据支持request/session/application WebContext ctx new WebContext(request, response, servletContext, request.getLocale()); ctx.setVariable(today, Calendar.getInstance()); // 放入模型数据 // 4. 处理模板输出到响应流 templateEngine.process(home, ctx, response.getWriter());2.3 模板缓存机制Thymeleaf 默认开启模板缓存解析后的模板会以事件序列的形式存储在内存中避免重复的文件读取与解析大幅提升性能。缓存相关配置可在模板解析器中设置setCacheable(true/false)全局开启 / 关闭缓存开发环境可关闭方便热更setCacheTTLMs(long)设置缓存有效期毫秒getCacheablePatternSpec()为指定模板路径配置缓存规则。生产环境建议开启缓存若需手动刷新缓存可通过模板引擎的clearTemplateCache()清空所有或clearTemplateCacheFor(String templateName)清空指定模板方法实现。三、Thymeleaf 标准表达式语法表达式是 Thymeleaf 的核心所有后端数据与前端页面的绑定、逻辑判断均通过表达式实现。Thymeleaf 标准方言提供了丰富的表达式类型支持嵌套与组合满足各种复杂场景。3.1 六大核心表达式表格表达式类型语法核心用途变量表达式${...}绑定后端模型数据支持 OGNL/SpringEL 语法如${user.name}、${list[0]}选择变量表达式*{...}基于th:object的对象选择表达式简化对象属性访问如*{name}等价于${obj.name}消息表达式#{...}国际化消息绑定配合.properties文件实现多语言如#{home.welcome}链接 URL 表达式{...}生成标准化的 URL支持路径参数、上下文根自动拼接如{/user/detail(id${id})}片段表达式~{...}引用模板片段实现页面复用如~{commons :: header}字面量表达式直接书写支持文本xxx、数字123、布尔true/false、空null字面量3.2 表达式基础操作Thymeleaf 支持在表达式中进行各种运算与拼接语法简洁且贴近 Java核心操作如下文本操作拼接如Hello ${user.name}字面量替换|...|如|Hello ${user.name}!|等价于拼接更简洁算术运算、-、*、/、%支持别名div/、mod%布尔运算and、or非运算!/not比较运算、、、、、!支持别名gt、lt、ge、le、eq、ne避免 XML 中/转义问题条件运算三目运算(条件) ? 结果1 : 结果2如${user.age 18} ? 成年 : 未成年默认值运算Elvis 运算符值 ?: 默认值如${user.name} ?: 匿名用户值为 null 时取默认值无操作符_表示不做任何操作使用原型文本如${user.name} ?: _3.3 表达式内置对象Thymeleaf 提供了一系列内置基础对象和工具对象无需手动封装即可直接在表达式中使用极大提升开发效率。3.3.1 基础对象以#开头#ctx上下文对象包含#locale本地化、#request请求、#session会话等子对象#locale当前本地化信息如${#locale.country}获取国家编码param请求参数映射如${param.username[0]}多值参数取第一个session会话属性映射如${session.user}application应用上下文属性映射如${application.appName}。3.3.2 核心工具对象以#开头Thymeleaf 提供了针对常用类型的工具对象封装了大量实用方法核心如下#dates/#calendars日期 / 日历处理如格式化${#dates.format(date, yyyy-MM-dd)}#strings字符串处理如判空${#strings.isEmpty(str)}、转大写${#strings.toUpperCase(str)}#numbers数字格式化如货币${#numbers.formatCurrency(num)}、百分比${#numbers.formatPercent(num)}#lists/#sets/#maps集合处理如判空${#lists.isEmpty(list)}、获取大小${#maps.size(map)}#aggregates集合聚合如求和${#aggregates.sum(list)}、平均值${#aggregates.avg(list)}#bools布尔处理如${#bools.isTrue(obj)}。四、Thymeleaf 核心属性用法Thymeleaf 的逻辑实现主要通过 **th:*系列属性 ** 完成这些属性可直接作用于 HTML 标签实现数据绑定、逻辑控制、页面复用等功能核心属性按用途可分为以下几类。4.1 文本与属性绑定4.1.1 文本绑定th:text转义文本绑定将表达式结果作为标签文本内容自动转义 HTML 特殊字符如转为lt;防止 XSSth:utext非转义文本绑定直接输出表达式结果保留 HTML 标签如th:utext#{home.welcome}消息中包含b标签时会生效。示例html预览p th:text${user.name}原型用户名/p p th:utextHello b ${user.name} /b原型文本/p4.1.2 属性绑定th:attr通用属性绑定可设置任意 HTML 属性如th:attrsrc{/img/logo.png},title#{logo}专属属性绑定针对常用 HTML 属性提供的简化绑定如th:href、th:src、th:value、th:class、th:title等比th:attr更简洁th:alt-title/th:lang-xmllang批量属性绑定分别同时设置alt/title、lang/xml:langth:attrappend/th:attrprepend属性值追加 / 前置如th:attrappendclass activeth:classappend/th:styleappend样式类 / 样式的追加专为 CSS 设计避免覆盖原有值。示例html预览!-- 专属属性绑定 -- a hrefdetail.html th:href{/user/detail(id${user.id})}查看详情/a img srclogo.png th:src{/img/logo.png} th:alt-title#{logo} !-- 样式追加 -- div classbox th:classappend${user.active} ? active : /div4.1.3 布尔属性绑定对于 HTML 布尔属性如checked、disabled、selectedThymeleaf 提供了专属的th:*属性表达式结果为true时渲染属性false时不渲染。核心布尔属性th:checked、th:disabled、th:selected、th:readonly、th:required等。示例html预览input typecheckbox th:checked${user.agree} select option th:selected${user.gender male}男/option option th:selected${user.gender female}女/option /select4.2 逻辑控制4.2.1 循环遍历th:each用于遍历集合、数组、Map 等可迭代对象核心语法th:each迭代变量, 状态变量 : 可迭代对象。状态变量包含遍历的核心信息可省略默认名为迭代变量Stat属性如下index索引从 0 开始count计数从 1 开始size可迭代对象总大小current当前遍历对象even/odd是否为偶数 / 奇数行first/last是否为第一个 / 最后一个元素。示例html预览table tr th:eachuser, userStat : ${userList} th:class${userStat.odd} ? odd-row : td th:text${userStat.count}/td td th:text${user.name}/td td th:text${user.age}/td /tr /table4.2.2 条件判断th:if/th:unless单条件判断th:unless是th:if的反义表达式为false时渲染示例html预览div th:if${user.age 18}成年用户/div div th:unless${user.isEmpty()}用户信息非空/divth:switch/th:case多条件分支判断类似 Java 的switchth:case*表示默认分支示例html预览div th:switch${user.role} p th:caseadmin管理员/p p th:caseuser普通用户/p p th:case*未知角色/p /div4.3 局部变量与属性优先级4.3.1 局部变量th:with用于在模板中定义局部变量仅在当前标签及其子标签中生效核心语法th:with变量1值1, 变量2值2。示例html预览div th:withdfyyyy-MM-dd, today${#dates.format(Calendar.getInstance(), df)} p th:text|今天日期${today}|/p /div4.3.2 属性优先级当一个标签上存在多个th:*属性时Thymeleaf 会按固定优先级执行而非按属性书写顺序核心优先级从高到低如下片段包含th:insert/th:replace循环遍历th:each条件判断th:if/th:unless/th:switch/th:case对象选择th:object/ 局部变量th:with通用属性修改th:attr/th:attrappend专属属性修改th:href/th:src等文本绑定th:text/th:utext片段指定th:fragment片段移除th:remove。4.4 片段复用与页面布局片段复用是 Thymeleaf 实现页面模块化的核心通过片段定义和片段引入实现核心属性为th:fragment定义、th:insert/th:replace引入。4.4.1 片段定义th:fragment在模板中定义可复用的片段支持指定参数核心语法html预览!-- 无参片段commons.html -- footer th:fragmentfooter copy; 2025 我的网站 /footer !-- 有参片段commons.html -- div th:fragmentheader(title, links) h1 th:text${title}默认标题/h1 div th:replace${links}/div /div4.4.2 片段引入th:insert将片段插入到当前标签中保留当前标签th:replace将片段替换当前标签不保留当前标签引用语法模板名 :: 片段名(参数)模板名为this时表示当前模板参数可省略无参时。示例html预览!-- 引入无参片段 -- div th:insertcommons :: footer/div !-- 引入有参片段传递普通值/片段作为参数 -- div th:replacecommons :: header(~{::title}, ~{::link}) title首页/title link relstylesheet th:href{/css/index.css} /div !-- 引用当前模板的片段 -- div th:replacethis :: nav/div4.4.3 片段移除th:remove用于移除模板中的指定片段适用于原型模板中的测试内容核心值all移除当前标签及其所有子标签body移除当前标签的所有子标签保留自身tag移除当前标签保留所有子标签all-but-first移除除第一个子标签外的所有子标签none不做移除。示例html预览!-- 移除原型测试行 -- tr th:eachuser : ${userList} td th:text${user.name}/td /tr tr th:removeall原型测试行/tr五、Thymeleaf 高级特性5.1 内联表达式内联表达式允许直接在 HTML 文本 / JS/CSS 中书写 Thymeleaf 表达式无需通过th:*属性核心语法[[...]]转义内联等价于th:text[(...)]非转义内联等价于th:utext。注意内联表达式会破坏自然模板的特性静态运行时显示表达式代码建议谨慎使用。示例html预览!-- 文本内联 -- pHello, [[${user.name}]]!/p !-- 关闭内联避免[[...]]被解析 -- p th:inlinenone这是普通的[[1,2,3]]数组/p5.1.1 JS/CSS 内联通过th:inlinejavascript/th:inlinecss开启 JS/CSS 内联支持在脚本 / 样式中绑定后端数据Thymeleaf 会自动进行 JS/CSS 转义保证语法正确性。示例javascript运行script th:inlinejavascript // 绑定后端数据自动转义并加引号 var username [[${user.name}]]; var user /*[[${user}]]*/ null; // 自然模板静态运行时取null动态运行时替换为用户对象 /scriptcssstyle th:inlinecss .[[${cssClass}]] { text-align: [[${align}]]; } /style5.2 国际化i18nThymeleaf 通过消息表达式#{...}配合 **.properties国际化文件 ** 实现多语言核心步骤创建国际化文件按basename_语言_国家.properties命名如messages_zh_CN.properties、messages_en_US.properties默认文件messages.properties配置本地化解析器Spring Boot 中可通过spring.messages.basename指定文件基础名页面绑定国际化消息通过#{...}绑定支持参数传递。示例properties# messages_zh_CN.properties home.welcome欢迎你{0}! btn.submit提交 # messages_en_US.properties home.welcomeWelcome, {0}! btn.submitSubmithtml预览!-- 绑定国际化消息并传递参数 -- p th:utext#{home.welcome(${user.name})}Welcome, Sebastian!/p button th:value#{btn.submit}Submit/button5.3 解耦模板逻辑Thymeleaf 支持将模板逻辑th:*属性与标记HTML完全解耦实现纯 HTML 的模板文件逻辑通过单独的*.th.xml文件定义适用于设计与开发高度分离的场景。核心步骤创建纯 HTML 模板无任何th:*属性如home.html创建逻辑文件与模板同目录命名为模板名.th.xml通过thlogic/attr标签注入逻辑开启解耦逻辑模板解析器中设置setUseDecoupledLogic(true)。示例html预览!-- home.html纯HTML模板 -- table iduserTable tr td classname原型用户名/td td classage原型年龄/td /tr /tablexml!-- home.th.xml逻辑文件 -- ?xml version1.0? thlogic attr sel#userTable th:removeall-but-first attr seltr[0] th:eachuser : ${userList} attr seltd.name th:text${user.name} / attr seltd.age th:text${user.age} / /attr /attr /thlogic5.4 模板解析器链Thymeleaf 支持配置多个模板解析器形成解析器链当第一个解析器无法找到模板时自动使用下一个解析器适用于模板分散存储的场景。通过setOrder(int)设置解析器优先级数字越小优先级越高示例java运行// 类加载器解析器优先级1 ClassLoaderTemplateResolver classLoaderResolver new ClassLoaderTemplateResolver(); classLoaderResolver.setOrder(1); classLoaderResolver.setPrefix(templates/); classLoaderResolver.setSuffix(.html); // Servlet上下文解析器优先级2 ServletContextTemplateResolver servletResolver new ServletContextTemplateResolver(servletContext); servletResolver.setOrder(2); servletResolver.setPrefix(/WEB-INF/templates/); servletResolver.setSuffix(.html); // 绑定到模板引擎 TemplateEngine templateEngine new TemplateEngine(); templateEngine.addTemplateResolver(classLoaderResolver); templateEngine.addTemplateResolver(servletResolver);六、Thymeleaf 与 Spring Boot 最佳实践6.1 核心配置项Spring Boot 中通过application.yml配置 Thymeleaf核心配置项如下yamlspring: thymeleaf: prefix: classpath:/templates/ # 模板前缀 suffix: .html # 模板后缀 mode: HTML # 模板模式 encoding: UTF-8 # 编码 cache: false # 关闭缓存开发环境 servlet: content-type: text/html # 响应类型 check-template-location: true # 检查模板位置是否存在6.2 常用技巧开启驼峰命名自动映射Spring Boot 中配置 MyBatis 时配合mybatis.configuration.map-underscore-to-camel-casetrue实现数据库下划线字段与 Java 驼峰属性的自动映射静态资源访问静态资源CSS/JS/ 图片放入src/main/resources/static/页面中通过{/资源路径}访问如{/css/index.css}页面跳转通过Controller返回模板名无需加后缀如return index对应templates/index.html异常页面定制创建templates/error/404.html、templates/error/500.htmlSpring Boot 会自动映射到对应的 HTTP 异常状态码片段复用最佳实践将公共头部、尾部、导航抽离为单独的模板如commons.html通过th:replace引入实现页面统一维护。七、总结Thymeleaf 作为一款现代化的模板引擎以自然模板、优雅语法、强 Web 标准支持和Spring 生态无缝整合成为了 Java Web 开发的主流选择。它摒弃了 JSP 的繁琐与侵入性实现了设计原型与开发模板的统一大幅提升了团队协作效率。本文从核心概念、环境搭建、标准表达式、核心属性到高级特性全面解析了 Thymeleaf 的使用方法其核心要点可总结为掌握六大模板模式和标准表达式这是 Thymeleaf 的基础熟练使用 **th:*核心属性 **实现数据绑定、逻辑控制、页面复用合理利用内置对象和工具方法简化日常开发借助片段复用和解耦模板逻辑实现页面模块化与高可维护性结合 Spring Boot 的自动配置快速集成并优化 Thymeleaf 的使用。Thymeleaf 的学习曲线平缓语法贴近 Java 和 HTML只要掌握核心用法就能轻松实现后端数据与前端页面的优雅绑定开发出高性能、高可维护性的 Java Web 应用。