Thymeleaf中文网

深色模式

URIs/URLs工具 ​

#uris 是 Thymeleaf 标准表达式中的工具对象，专门用于在表达式内执行 URI/URL 相关操作（尤其是转义/反转义），其底层对应 org.thymeleaf.expression.Uris 类。

java
/*
 * ======================================================================
 * 请查阅 org.thymeleaf.expression.Uris 类的 Javadoc API 文档
 * ======================================================================
 */

/*
 * 对 URI/URL 路径进行转义/反转义处理
 */
${#uris.escapePath(uri)}
${#uris.escapePath(uri, encoding)}
${#uris.unescapePath(uri)}
${#uris.unescapePath(uri, encoding)}

/*
 * 对 URI/URL 路径段（即 '/' 符号之间的部分）进行转义/反转义处理
 */
${#uris.escapePathSegment(uri)}
${#uris.escapePathSegment(uri, encoding)}
${#uris.unescapePathSegment(uri)}
${#uris.unescapePathSegment(uri, encoding)}

/*
 * 对片段标识符（格式为 #frag）进行转义/反转义处理
 */
${#uris.escapeFragmentId(uri)}
${#uris.escapeFragmentId(uri, encoding)}
${#uris.unescapeFragmentId(uri)}
${#uris.unescapeFragmentId(uri, encoding)}

/*
 * 对查询参数（格式为 ?var=value）进行转义/反转义处理
 */
${#uris.escapeQueryParam(uri)}
${#uris.escapeQueryParam(uri, encoding)}
${#uris.unescapeQueryParam(uri)}
${#uris.unescapeQueryParam(uri, encoding)}

补充说明（贴合 Thymeleaf URL 处理技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
Escape/Unescape转义/反转义（URL 安全处理核心操作，如将空格转为 %20，反转义则还原）
URI/URL pathURI/URL 路径（完整路径，如 https://example.com/path/name?a=1#frag 中的 /path/name）
path segment路径段（路径中 \ 分隔的单个部分，如 /path/name 中的 path 或 name）
Fragment Identifier片段标识符（URL 中 # 后的部分，用于定位页面锚点，如 #top）
Query Parameter查询参数（URL 中 ? 后的键值对，如 ?username=张三 中的 username=张三）
encoding编码格式（可选参数，如 UTF-8/GBK，默认通常为 UTF-8）
UrisURI 工具类（Thymeleaf 表达式工具，#uris 是其在模板中的简写，专用于 URL 安全处理）

2. 关键逻辑解读 ​

  • 不同场景的转义规则差异：
    • escapePath：处理完整路径（会保留 / 等路径分隔符，仅转义非法字符）；
    • escapePathSegment：处理单个路径段（会转义 /，避免路径被拆分）；
    • escapeFragmentId：适配片段标识符规则（不转义 # 本身，仅转义其后面的非法字符）；
    • escapeQueryParam：适配查询参数规则（如转义 &/=/空格等，避免参数解析错误）。
  • 编码参数的作用：指定转义时使用的字符编码（如中文转义需明确 UTF-8，否则可能出现乱码）。

3. 句式优化说明 ​

  • 将原文括号内的补充说明（如 (between '/' symbols)）整合到中文注释中，改为“（即 '/' 符号之间的部分）”，更符合中文技术注释的表达习惯；
  • 补充“处理”二字（如“进行转义/反转义处理”），让注释语义更完整，避免直译“转义/反转义作为路径”的生硬感；
  • 保留 ${#uris.xxx} 表达式原样（技术规范），同时用简洁的中文明确每个方法的处理对象（路径/路径段/片段标识符/查询参数），突出核心差异。

总结 ​

  1. #uris 核心作用：在 Thymeleaf 模板中对 URL/URI 不同部分进行安全转义/反转义，避免非法字符导致的 URL 解析错误；
  2. 核心用法分类（按处理对象）：
    • 完整路径：escapePath/unescapePath（保留 / 分隔符）；
    • 单个路径段：escapePathSegment/unescapePathSegment（转义 /）；
    • 片段标识符：escapeFragmentId/unescapeFragmentId（适配 # 后的锚点）；
    • 查询参数：escapeQueryParam/unescapeQueryParam（适配 ? 后的键值对）；
  3. 关键注意点：可选的 encoding 参数建议显式指定为 UTF-8，避免中文等非 ASCII 字符转义/反转义乱码。