Thymeleaf中文网

深色模式

3 使用文本 ​

3.1 支持多种语言的欢迎页 ​

我们的第一个任务是为杂货店网站创建首页。

这个页面的初始版本会极其简单：仅包含一个标题和一条欢迎语。以下是 /WEB-INF/templates/home.html 文件的内容：

html
<!DOCTYPE html>

<html xmlns:th="http://www.thymeleaf.org">

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" media="all" 
          href="../../css/gtvg.css" th:href="@{/css/gtvg.css}" />
  </head>

  <body>
  
    <p th:text="#{home.welcome}">Welcome to our grocery store!</p>
  
  </body>

</html>

你首先会注意到：这个文件是可被任意浏览器正确显示的 HTML5 代码——因为它不包含任何非 HTML 标签（浏览器会忽略所有不认识的属性，比如 th:text）。

但你也可能发现，这个模板并非严格合规的 HTML5 文档：我们使用的 th:* 形式的非标准属性，并不被 HTML5 规范允许。实际上，我们甚至在 <html> 标签中添加了 xmlns:th 属性，这完全不符合 HTML5 的风格：

html
<html xmlns:th="http://www.thymeleaf.org">

这个属性对模板处理没有任何实际影响，仅作为一种“标识”，避免 IDE 因 th:* 属性缺少命名空间定义而报错。

那如果我们想让模板符合 HTML5 规范该怎么做？很简单：切换到 Thymeleaf 的数据属性语法——属性名使用 data- 前缀，并用连字符（-）替代冒号（:）作为分隔符：

html
<!DOCTYPE html>

<html>

  <head>
    <title>Good Thymes Virtual Grocery</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" media="all" 
          href="../../css/gtvg.css" data-th-href="@{/css/gtvg.css}" />
  </head>

  <body>
  
    <p data-th-text="#{home.welcome}">Welcome to our grocery store!</p>
  
  </body>

</html>

HTML5 规范允许自定义 data- 前缀的属性，因此上述代码能让模板成为完全合规的 HTML5 文档。

INFO

这两种写法（th:* 和 data-th-*）完全等效且可互换，但为了让代码示例更简洁紧凑，本教程将使用命名空间写法（th:*）。此外，th:* 写法通用性更强，可在所有 Thymeleaf 模板模式（XML、TEXT 等）中使用；而 data- 写法仅支持 HTML 模式。

核心语法解释 ​

  1. th:text 核心作用：
    • 替换标签内的文本内容，#{home.welcome} 是 Thymeleaf 的消息表达式，用于读取国际化配置文件中的 home.welcome 键值（实现国际化）；
    • 标签内的默认文本（Welcome to our grocery store!）会在模板未被 Thymeleaf 处理时（如直接打开 HTML 文件）显示，体现“自然模板”特性。
  2. th:href 与资源路径：
    • @{/css/gtvg.css} 是 URL 表达式，会自动拼接应用上下文路径，避免硬编码路径导致的部署问题；
    • 原生 href="../../css/gtvg.css" 作为静态原型的 fallback 路径，保证直接打开 HTML 时样式正常加载。
  3. 两种语法对比：
    写法合规性适用场景
    th:text非 HTML5 合规所有模板模式（XML/TEXT 等）
    data-th-textHTML5 合规仅 HTML 模板模式

总结 ​

  1. Thymeleaf 模板兼具“静态原型”和“动态模板”特性：直接打开 HTML 可显示默认内容，经引擎处理后渲染动态数据。
  2. th:* 是 Thymeleaf 核心属性写法，data-th-* 是 HTML5 兼容写法，二者功能完全一致，仅语法形式不同。
  3. #{} 消息表达式用于国际化文本，@{} URL 表达式用于资源路径，是 Thymeleaf 处理文本和路径的核心语法。