萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> JSP 程式設計

FreeMarker 數字格式化完全指南:內建函數、預定義格式、自定義模式、四捨五入與優先級

概覽

FreeMarker 提供豐富的數字格式化機制,從簡單的 `?c` 到複雜的模式字串、全域/局部設定,滿足各種貨幣、百分比、科學記號顯示需求。

1. 內建函數 `?c` (Computer Language Format)

  • 將**任意格式的數字字串**轉為標準計算機可識別形式(無千分位、點號小數點、無前導零)。
  • 輸入範例:`"123,456.123,456"`、`"123 456.123 456"`、`"000123.456"` → 全部輸出 `123456.123456`。
  • 用途:表單接收用戶自由格式輸入後統一轉換儲存/計算。
${"123,456.123,456"?c}  <!-- 輸出: 123456.123456 -->

2. 四種預定義格式 (Locale 敏感)

缺點:強依賴 JVM Locale 環境,跨部署不穩定,**不建議直接使用**,改用自定義模式。

3. 自定義模式語法 (Java `DecimalFormat` 風格)

語法:`${num?string("模式字串")}`

格式名用途範例 (Locale=US)
`computer`同 `?c`,但語法不同${123456.123?string.computer} → `123456.123`
`currency`貨幣格式(含符號、千分位)${1234.5?string.currency} → `$1,234.50`
`number`一般數字(含千分位)${1234.5?string.number} → `1,234.5`
`percent`百分比(乘100加%)${0.1234?string.percent} → `12%`
符號含義範例輸入輸出
`0`強制位數(不足補 0)`12.3?string("000.00")``012.30`
`#`選擇性位數(不足不補)`12.3?string("###.##")``12.3`
`,`千分位分隔符`1234567?string(",###")``1,234,567`
`.`小數點(Locale 決定實際字元)`1234.5?string(",##0.00")``1,234.50`
%`百分比(值×100)`0.123?string("0.00%")``12.30%`
`E`科學記號`12345?string("0.00E0")``1.23E4`
前/後綴字串直接輸出`12?string("'$'0.00")``$12.00`

常用模式速查

  • 保留兩位小數:`"0.00"` 或 `"#.00"`
  • 千分位 + 兩位小數:`",##0.00"`
  • 整數部分最少三位:`"000"`
  • 貨幣格式:`"¥#,##0.00"`

4. 局部設定 `<#setting number_format="...">`

影響**當前模板**後續所有未顯式指定格式的數字輸出。

<#setting number_format=",##0.00">
${price}       <!-- 自動套用千分位+兩位小數 -->
${ratio}       <!-- 同 -->
${ratio?string("0.0000")} <!-- 明確指定覆蓋設定 -->

可放在共用宏檔/版頭模板,`include` 後全局生效。

5. 全域設定 (Spring 整合範例)

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="freemarkerSettings">
        <props>
            <prop key="number_format">0.##</prop> <!-- 預設保留最多兩位小數 -->
            <prop key="locale">zh_TW</prop>
        </props>
    </property>
</bean>

6. 四捨五入模式

函數行為範例
`?round`四捨五入到整數 (銀行家算法:.5 到偶數)`1.5?round=2`, `2.5?round=2`
`?floor`向下取整`1.9?floor=1`
`?ceiling`向上取整`1.1?ceiling=2`
`?string("0")`同 `?round`,銀行家算法`1.5?string("0")=2`
財務/統計嚴格四捨五入(.5 向上)請用 `BigDecimal.setScale(RoundingMode.HALF_UP)` 在 Java 層處理,勿依賴模板層。

7. 優先級機制

優先級高 → 低:
1. 顯式 ?string("pattern")          // 最高
2. 模板內 <#setting number_format="...">   // 中
3. 全域配置 (freemarkerSettings)     // 低
4. 預定義格式 (currency/number/...)   // 最低

8. 避免 FreeMarker 自動加千分位「副作用」

FreeMarker 預設可能對大數字加千分位(視 Locale/版本)。純數字 ID、電話號碼**不要格式化**;

  • 模板寫 `${id?c}` 或 `${id?string("#")}` 強制無格式。
  • 或全域設定 `<#setting number_format="#">` / `0`。
  • 實體類 getter 回傳 `String` 而非 `Long`/`Integer` 徹底繞過。
copyright © 萬盛學電腦網 all rights reserved