Thymeleaf中文网

深色模式

数字工具 ​

#numbers：是用于处理数字对象的工具方法集合：

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

/*
 * ==========================
 * 格式化整数
 * ==========================
 */

/* 
 * 设置整数部分的最小位数（不足补0）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#numbers.formatInteger(num,3)}
${#numbers.arrayFormatInteger(numArray,3)}
${#numbers.listFormatInteger(numList,3)}
${#numbers.setFormatInteger(numSet,3)}

/* 
 * 设置整数部分的最小位数（不足补0），并指定千位分隔符：
 * 可选值为 'POINT'（点）、'COMMA'（逗号）、'WHITESPACE'（空格）、'NONE'（无）或 'DEFAULT'（按当前语言环境）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#numbers.formatInteger(num,3,'POINT')}
${#numbers.arrayFormatInteger(numArray,3,'POINT')}
${#numbers.listFormatInteger(numList,3,'POINT')}
${#numbers.setFormatInteger(numSet,3,'POINT')}

/*
 * ==========================
 * 格式化十进制数（小数）
 * ==========================
 */

/*
 * 设置整数部分的最小位数（不足补0）和小数部分的精确位数（多余截断、不足补0）。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#numbers.formatDecimal(num,3,2)}
${#numbers.arrayFormatDecimal(numArray,3,2)}
${#numbers.listFormatDecimal(numList,3,2)}
${#numbers.setFormatDecimal(numSet,3,2)}

/*
 * 设置整数部分的最小位数、小数部分的精确位数，并指定小数分隔符。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#numbers.formatDecimal(num,3,2,'COMMA')}
${#numbers.arrayFormatDecimal(numArray,3,2,'COMMA')}
${#numbers.listFormatDecimal(numList,3,2,'COMMA')}
${#numbers.setFormatDecimal(numSet,3,2,'COMMA')}

/*
 * 设置整数部分的最小位数、小数部分的精确位数，同时指定千位分隔符和小数分隔符。
 * 此方法同样适用于数组、列表（List）或集合（Set）类型的参数。
 */
${#numbers.formatDecimal(num,3,'POINT',2,'COMMA')}
${#numbers.arrayFormatDecimal(numArray,3,'POINT',2,'COMMA')}
${#numbers.listFormatDecimal(numList,3,'POINT',2,'COMMA')}
${#numbers.setFormatDecimal(numSet,3,'POINT',2,'COMMA')}

/* 
 * =====================
 * 格式化货币
 * =====================
 */
${#numbers.formatCurrency(num)}
${#numbers.arrayFormatCurrency(numArray)}
${#numbers.listFormatCurrency(numList)}
${#numbers.setFormatCurrency(numSet)}

/* 
 * ======================
 * 格式化百分比
 * ======================
 */
${#numbers.formatPercent(num)}
${#numbers.arrayFormatPercent(numArray)}
${#numbers.listFormatPercent(numList)}
${#numbers.setFormatPercent(numSet)}

/* 
 * 设置百分比的整数部分最小位数和小数部分精确位数。
 */
${#numbers.formatPercent(num, 3, 2)}
${#numbers.arrayFormatPercent(numArray, 3, 2)}
${#numbers.listFormatPercent(numList, 3, 2)}
${#numbers.setFormatPercent(numSet, 3, 2)}

/*
 * ===============
 * 工具方法
 * ===============
 */

/*
 * 生成一个从 x 到 y 的整数序列（数组）。
 * 支持指定步长（step），默认步长为1。
 */
${#numbers.sequence(from,to)}
${#numbers.sequence(from,to,step)}

补充说明（贴合 Thymeleaf 数值格式化技术语境） ​

1. 核心术语解析 ​

英文术语译法/说明
minimum integer digits整数部分最小位数（如 formatInteger(5,3) → 005，不足补0，超出则保留原位数）
thousands separator千位分隔符（如 1000 用 POINT 分隔 → 1.000，用 COMMA 分隔 → 1,000）
decimal separator小数分隔符（如 123.45 用 COMMA 分隔 → 123,45）
exact decimal digits小数部分精确位数（如 formatDecimal(123.4,3,2) → 123.40，多余截断、不足补0）
formatCurrency货币格式化（按当前语言环境添加货币符号，如人民币 → ¥123.00，美元 → $123.00）
formatPercent百分比格式化（自动乘以100并加%，如 0.25 → 25%，formatPercent(0.25,3,2) → 025.00%）
sequence整数序列生成（如 sequence(1,5) → [1,2,3,4,5]，sequence(1,5,2) → [1,3,5]）

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

html
<!-- 1. 整数格式化（补0+千位分隔符） -->
<div th:with="num=123">
  整数最小3位：<span th:text="${#numbers.formatInteger(num,3)}"></span> <!-- 123 -->
  整数最小4位：<span th:text="${#numbers.formatInteger(num,4)}"></span> <!-- 0123 -->
  千位分隔符（POINT）：<span th:text="${#numbers.formatInteger(123456,3,'POINT')}"></span> <!-- 123.456 -->
</div>

<!-- 2. 小数格式化（整数补0+小数精确位数） -->
<div th:with="decimalNum=12.3">
  整数3位+小数2位：<span th:text="${#numbers.formatDecimal(decimalNum,3,2)}"></span> <!-- 012.30 -->
  自定义分隔符（千位POINT+小数COMMA）：<span th:text="${#numbers.formatDecimal(1234.56,3,'POINT',2,'COMMA')}"></span> <!-- 1.234,56 -->
</div>

<!-- 3. 货币与百分比格式化 -->
<div th:with="money=123.45, rate=0.1234">
  货币格式化：<span th:text="${#numbers.formatCurrency(money)}"></span> <!-- ¥123.45（中文环境） -->
  百分比默认格式：<span th:text="${#numbers.formatPercent(rate)}"></span> <!-- 12% -->
  百分比自定义位数：<span th:text="${#numbers.formatPercent(rate,3,2)}"></span> <!-- 012.34% -->
</div>

<!-- 4. 整数序列生成（常用于循环） -->
<div th:each="i : ${#numbers.sequence(1,5)}">
  序列元素：<span th:text="${i}"></span> <!-- 依次输出 1、2、3、4、5 -->
</div>
<div th:each="i : ${#numbers.sequence(10,0,2)}">
  倒序序列（步长2）：<span th:text="${i}"></span> <!-- 依次输出 10、8、6、4、2、0 -->
</div>
  • 核心特性：
    • 所有批量处理方法（array*/list*/set*）会遍历数组/集合中的每个数值，按相同规则格式化；
    • 货币格式化依赖服务器的语言环境（Locale），中文环境默认显示¥，英文环境默认显示$；
    • sequence 生成的序列包含起始值和结束值，步长支持正数（升序）和负数（降序）。

3. 句式优化说明 ​

  • 统一将“Also works with arrays, lists or sets”译为“此方法同样适用于数组、列表（List）或集合（Set）类型的参数”，避免重复且清晰；
  • 对分隔符可选值补充中文注释（如 POINT→点、COMMA→逗号），降低新手理解成本；
  • 拆分长参数方法的注释（如 formatDecimal 的“千位+小数分隔符”），按“参数含义”拆分说明；
  • 保留 ${#numbers.xxx} 表达式原样，注释兼顾“参数规则”和“实际效果”，适配模板开发场景。

总结 ​

  1. #numbers 是 Thymeleaf 核心数值处理工具类，覆盖整数/小数格式化、货币/百分比展示、整数序列生成三大核心场景；
  2. 格式化核心规则：
    • 整数部分：minimum digits 控制不足补0，千位分隔符可选（POINT/COMMA等）；
    • 小数部分：exact digits 控制精确位数（多余截断、不足补0），支持自定义小数分隔符；
    • 货币/百分比：按Locale自动适配格式，百分比会自动×100并加%；
  3. 高频扩展用法：sequence 方法常用于 th:each 循环生成连续数值（如分页、序号），支持自定义步长和倒序。