Thymeleaf中文网

深色模式

字符串工具（Strings） ​

#strings 是 Thymeleaf 标准表达式中最常用的工具对象，专为 String 类型提供空值安全的操作方法（所有方法均对 null 做了兼容处理），底层对应 org.thymeleaf.expression.Strings 类（可参考其 JavaDoc 获取完整 API）。

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

/*
 * 空值安全的 toString() 方法（避免 null 调用 toString() 抛异常）
 */
${#strings.toString(obj)}                           // 同样支持数组、列表、集合的批量处理（array*/list*/set* 方法）

/*
 * 检查字符串是否为空（或 null）。检查前会先执行 trim() 去除首尾空格。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.isEmpty(name)}
${#strings.arrayIsEmpty(nameArr)}
${#strings.listIsEmpty(nameList)}
${#strings.setIsEmpty(nameSet)}

/*
 * 对字符串执行 isEmpty() 检查：若结果为 false（非空）则返回原字符串；
 * 若为 true（为空）则返回指定的默认字符串。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.defaultString(text,default)}
${#strings.arrayDefaultString(textArr,default)}
${#strings.listDefaultString(textList,default)}
${#strings.setDefaultString(textSet,default)}

/*
 * 检查字符串中是否包含指定片段（子串）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.contains(name,'ez')}                     // 同样支持数组、列表、集合的批量处理
${#strings.containsIgnoreCase(name,'ez')}           // 忽略大小写的包含检查，同样支持批量处理

/*
 * 检查字符串是否以指定片段开头/结尾。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.startsWith(name,'Don')}                  // 开头检查，同样支持批量处理
${#strings.endsWith(name,endingFragment)}           // 结尾检查，同样支持批量处理

/*
 * 字符串子串相关操作。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.indexOf(name,frag)}                      // 获取子串首次出现的索引，同样支持批量处理
${#strings.substring(name,3,5)}                     // 截取子串（从索引3到5，左闭右开），同样支持批量处理
${#strings.substringAfter(name,prefix)}             // 截取前缀之后的部分，同样支持批量处理
${#strings.substringBefore(name,suffix)}            // 截取后缀之前的部分，同样支持批量处理
${#strings.replace(name,'las','ler')}               // 替换子串，同样支持批量处理

/*
 * 字符串前缀/后缀拼接。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.prepend(str,prefix)}                     // 在字符串开头拼接前缀，同样支持批量处理
${#strings.append(str,suffix)}                      // 在字符串结尾拼接后缀，同样支持批量处理

/*
 * 大小写转换。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.toUpperCase(name)}                       // 转大写，同样支持批量处理
${#strings.toLowerCase(name)}                       // 转小写，同样支持批量处理

/*
 * 拆分与拼接（仅针对数组/列表/集合）
 */
${#strings.arrayJoin(namesArray,',')}               // 将字符串数组用指定分隔符拼接为单个字符串
${#strings.listJoin(namesList,',')}                 // 将字符串列表用指定分隔符拼接为单个字符串
${#strings.setJoin(namesSet,',')}                   // 将字符串集合用指定分隔符拼接为单个字符串
${#strings.arraySplit(namesStr,',')}                // 将字符串按分隔符拆分为字符串数组（返回 String[]）
${#strings.listSplit(namesStr,',')}                 // 将字符串按分隔符拆分为字符串列表（返回 List<String>）
${#strings.setSplit(namesStr,',')}                  // 将字符串按分隔符拆分为字符串集合（返回 Set<String>）

/*
 * 去除首尾空格。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.trim(str)}                               // 去除首尾空格，同样支持批量处理

/*
 * 计算字符串长度。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.length(str)}                             // 获取字符串长度，同样支持批量处理

/*
 * 字符串缩写：将文本截断为最大长度 n，若原文本超过该长度则截断并以 "..." 结尾。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#strings.abbreviate(str,10)}                      // 缩写为最大长度10，同样支持批量处理

/*
 * 转换首字符大小写（反之亦然）
 */
${#strings.capitalize(str)}                         // 首字符转大写，同样支持批量处理
${#strings.unCapitalize(str)}                       // 首字符转小写，同样支持批量处理

/*
 * 将每个单词的首字符转为大写
 */
${#strings.capitalizeWords(str)}                    // 按默认分隔符（空格）拆分单词，首字符大写，同样支持批量处理
${#strings.capitalizeWords(str,delimiters)}         // 按指定分隔符拆分单词，首字符大写，同样支持批量处理

/*
 * 字符串转义
 */
${#strings.escapeXml(str)}                          // XML 转义，同样支持批量处理
${#strings.escapeJava(str)}                         // Java 转义（如 \n/\t），同样支持批量处理
${#strings.escapeJavaScript(str)}                   // JavaScript 转义，同样支持批量处理
${#strings.unescapeJava(str)}                       // Java 反转义，同样支持批量处理
${#strings.unescapeJavaScript(str)}                 // JavaScript 反转义，同样支持批量处理

/*
 * 空值安全的字符串比较与拼接
 */
${#strings.equals(first, second)}                   // 字符串相等比较（区分大小写）
${#strings.equalsIgnoreCase(first, second)}         // 字符串相等比较（忽略大小写）
${#strings.concat(values...)}                       // 拼接多个字符串（null 会被当作空字符串处理）
${#strings.concatReplaceNulls(nullValue, values...)}// 拼接多个字符串（null 替换为指定的 nullValue）

/*
 * 生成随机字符串
 */
${#strings.randomAlphanumeric(count)}               // 生成指定长度的随机字母数字字符串

补充说明（贴合 Thymeleaf 字符串操作技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
Null-safe空值安全（处理 null 时不抛异常，如 toString(null) 返回空字符串而非 NPE）
trim()去除首尾空格（isEmpty 检查前会执行，即 " " 会被判定为 empty）
abbreviate字符串缩写（如 abbreviate("HelloWorld123",6) 返回 "Hello..."）
capitalizeWords单词首字母大写（默认按空格拆分，如 capitalizeWords("hello world") 返回 "Hello World"）
concatReplaceNulls拼接并替换 null（如 concatReplaceNulls("-", null, "abc") 返回 "-abc"）
randomAlphanumeric随机字母数字字符串（仅包含 a-z、A-Z、0-9，长度由 count 指定）

2. 关键逻辑解读（高频用法示例） ​

html
<!-- 1. 空值处理与默认值 -->
<div th:with="username=${null}, defaultName='游客'">
  用户名：<span th:text="${#strings.defaultString(username, defaultName)}"></span> <!-- 输出 游客 -->
</div>

<!-- 2. 包含性检查（忽略大小写） -->
<div th:with="name='Thymeleaf'">
  是否包含 'leaf'：<span th:text="${#strings.containsIgnoreCase(name, 'leaf')}"></span> <!-- true -->
</div>

<!-- 3. 字符串缩写 -->
<div th:with="longText='Thymeleaf 是优秀的模板引擎'">
  缩写（长度8）：<span th:text="${#strings.abbreviate(longText, 8)}"></span> <!-- 输出 "Thymeleaf..." -->
</div>

<!-- 4. 拆分与拼接 -->
<div th:with="strList=${#lists.toList(new String[]{'张三','李四','王五'})}">
  列表拼接：<span th:text="${#strings.listJoin(strList, '|')}"></span> <!-- 输出 "张三|李四|王五" -->
  字符串拆分：<span th:text="${#strings.listSplit('苹果,香蕉,橙子', ',')}"></span> <!-- 输出 [苹果,香蕉,橙子] -->
</div>

<!-- 5. 空值安全拼接 -->
<div th:with="str1='Hello', str2=${null}, str3='World'">
  普通拼接：<span th:text="${#strings.concat(str1, str2, str3)}"></span> <!-- 输出 "HelloWorld" -->
  替换null拼接：<span th:text="${#strings.concatReplaceNulls('-', str1, str2, str3)}"></span> <!-- 输出 "Hello-World" -->
</div>
  • 核心特性：
    • 所有带 array*/list*/set* 后缀的方法，均为“批量处理”（如 listIsEmpty 会遍历列表中所有字符串，只要有一个非空则返回 false）；
    • isEmpty 检查前会执行 trim()，即全空格的字符串会被判定为 empty；
    • 转义方法（escapeXml/escapeJavaScript）是前端防 XSS 的常用手段，推荐在渲染用户输入内容时使用。

3. 句式优化说明 ​

  • 统一补充“（同样支持数组、列表、集合的批量处理）”解释 // also array*, list* and set*，避免重复且贴合中文阅读习惯；
  • 对易混淆的方法补充括号注释（如 substring 的“左闭右开”、capitalizeWords 的“默认分隔符”）；
  • 拆分长句为“功能+规则”的结构（如缩写方法的“截断+结尾...”），突出核心逻辑；
  • 保留 ${#strings.xxx} 表达式原样，注释兼顾“精准”与“易懂”，适配新手理解。

总结 ​

  1. #strings 是 Thymeleaf 最常用的工具类，覆盖空值处理、内容检查、截取替换、大小写转换、拆分拼接、转义等所有字符串操作场景；
  2. 核心特性：所有方法均为“空值安全”（避免 NPE），且支持数组/列表/集合的批量处理；
  3. 高频用法：
    • 空值兜底：defaultString(str, default)；
    • 内容检查：contains/containsIgnoreCase；
    • 拆分拼接：listJoin/listSplit；
    • 防 XSS：escapeXml/escapeJavaScript；
    • 空值安全拼接：concatReplaceNulls。