Thymeleaf中文网

深色模式

4.4 链接URL表达式 ​

由于 URL 在 Web 应用模板中的重要性，Thymeleaf 标准方言为其设计了专属语法——@ 语法：@{...}。

URL 的类型 ​

Thymeleaf 支持多种类型的 URL：

  • 绝对 URL：http://www.thymeleaf.org
  • 相对 URL：
    • 页面相对：user/login.html（基于当前页面路径）
    • 上下文相对：/itemdetails?id=3（自动拼接应用上下文名称）
    • 服务器相对：~/billing/processInvoice（可访问同服务器下其他应用的 URL）
    • 协议相对URL：//code.jquery.com/jquery-2.0.3.min.js（自动适配当前页面的 HTTP/HTTPS 协议）

URL 表达式的解析和转换逻辑，由注册到 ITemplateEngine 的 org.thymeleaf.linkbuilder.ILinkBuilder 接口实现类完成。

默认情况下，Thymeleaf 会注册 org.thymeleaf.linkbuilder.StandardLinkBuilder——该实现适配离线（非 Web）场景和基于 Servlet API 的 Web 场景；若集成非 Servlet API 的 Web 框架，可能需要自定义链接构建器。

我们通过 th:href 属性来使用 URL 表达式，示例如下：

html
<!-- 生成绝对 URL：http://localhost:8080/gtvg/order/details?orderId=3（含 URL 重写） -->
<a href="details.html" 
   th:href="@{http://localhost:8080/gtvg/order/details(orderId=${o.id})}">view</a>

<!-- 生成上下文相对 URL：/gtvg/order/details?orderId=3（自动拼接应用上下文 gtvg） -->
<a href="details.html" th:href="@{/order/details(orderId=${o.id})}">view</a>

<!-- 生成路径参数式 URL：/gtvg/order/3/details（路径中的 {orderId} 被变量替换） -->
<a href="details.html" th:href="@{/order/{orderId}/details(orderId=${o.id})}">view</a>

关键注意事项 ​

  1. th:href 的修饰特性： 处理完成后，Thymeleaf 会计算出最终的 URL，并将其赋值给 <a> 标签的 href 属性，覆盖原有的静态 href 值。

  2. URL 参数与编码：支持在 URL 中使用表达式作为参数（如 orderId=${o.id}），Thymeleaf 会自动完成 URL 参数的编码（如空格转 %20、中文转 UTF-8 编码）；

  3. 多参数用逗号分隔：@{/order/process(execId=${execId},execType='FAST')}。

  4. 路径变量模板： URL 路径中可使用 {变量名} 作为模板占位符，通过参数赋值替换：@{/order/{orderId}/details(orderId=${orderId})}。

  5. 上下文自动拼接： 以 / 开头的相对 URL（如 /order/details）会自动拼接应用上下文名称（如示例中的 gtvg），避免硬编码上下文导致的部署问题。

  6. URL 重写（URL Rewriting）： 若浏览器未启用 Cookie，Thymeleaf 会自动为相对 URL 添加 ;jsessionid=... 后缀以保留会话（基于 Servlet API 的 response.encodeURL(...) 机制），也可自定义重写过滤器。

  7. 静态原型兼容： th:href 允许模板中保留有效的静态 href 属性（如 href="details.html"），直接打开 HTML 文件时链接仍可访问，符合“自然模板”特性。

URL 的基地址也可通过表达式动态生成，类似消息表达式的动态键：

html
<a th:href="@{${url}(orderId=${o.id})}">view</a>
<a th:href="@{'/details/'+${user.login}(orderId=${o.id})}">view</a>

核心语法解释 ​

  1. URL 表达式的核心优势：

    • 上下文无关：自动拼接应用上下文路径，无需硬编码（如 /gtvg/order/details 中的 gtvg 由框架自动补充）；
    • 自动编码：参数中的特殊字符（如中文、空格）自动 URL 编码，避免手动处理的错误；
    • 动态灵活：支持参数、路径变量、动态基地址，适配各类动态链接场景。

  2. 路径变量 vs 参数变量：

    • 路径变量（{orderId}）：将变量嵌入 URL 路径中，符合 RESTful 风格（如 /order/3/details）；
    • 参数变量（orderId=${o.id}）：以查询参数形式拼接（如 /order/details?orderId=3），适用于普通业务参数。

  3. 静态 href 的作用： 模板未被 Thymeleaf 处理时（如直接打开 HTML），href="details.html" 保证链接可点击，方便前端原型调试；处理后则被 th:href 生成的动态 URL 替换。

总结 ​

  1. @{...} 是 Thymeleaf 专属的 URL 表达式语法，支持绝对/相对/协议相对等多种 URL 类型，自动处理上下文拼接和参数编码。
  2. th:href 是最常用的 URL 表达式载体，兼具“静态原型兼容”和“动态 URL 生成”的特性，是 Web 模板中构建链接的首选方式。
  3. URL 表达式支持路径变量、多参数、动态基地址等高级特性，能适配 RESTful 链接、动态参数链接等各类场景，且无需关注 URL 编码和上下文拼接的细节。