跳至主要內容

11 · TEXT() 格式化

情境​

金額要長得像金額（$#,##0.00）、日期要在地化乾淨（yyyy-mm-dd）、百分比不該有 8 位小數（0.0%）。XTL 的 TEXT(value, format) 負責這層渲染。

貨幣​

{{ TEXT([金額], "$#,##0.00") }}     → "$1,200.00"
{{ TEXT([金額], "[$NT$-zh-TW] #,##0") }} → "NT$ 1,200"
{{ TEXT([金額], "#,##0;(#,##0)") }} → 負值用括號

日期​

{{ TEXT([下單日期], "yyyy-mm-dd") }}      → "2026-05-12"
{{ TEXT([下單日期], "yyyy-mm") }}          → "2026-05"
{{ TEXT([下單日期], "mmm d, yyyy") }}      → "May 12, 2026"
{{ TEXT(TODAY(), "yyyy-mm-dd") }}            → 今日（UTC，依 ADR-0001）

TODAY() 回傳的是「UTC 的今日」。若操作員所在時區重要，請把日期當成 __inputs__ 傳進來，而不是用 TODAY()。

百分比​

{{ TEXT([毛利率], "0.0%") }}     → "12.3%"（毛利率為 0.1234）
{{ TEXT([費率], "0%") }}          → "8%"

與串接搭配​

{{ "合計: " & TEXT(SUM([金額]), "$#,##0") }}    → "合計: $43,500"
{{ "執行日: " & TEXT(TODAY(), "yyyy-mm-dd") }}    → "執行日: 2026-05-12"

& 運算子把 TEXT() 的結果與字面字串及其他文字串接起來。用在頁首列、檔名、工作表名都很順手。

什麼時候不要用 TEXT()​

對大多數儲存格來說，更簡單的路徑是範本儲存格的 numFmt：

  • 在 Excel 把儲存格格式設為 $#,##0.00。
  • 在表達式中直接寫純數字：{{ [金額] }}。
  • xl3 在輸出時會保留儲存格格式。

這樣儲存格仍維持為數字型別 — Excel 還是可以加總、篩選等等。TEXT() 會強制把儲存格變成字串。在這些情境用 TEXT()：

  • 需要把格式化值塞進字串串接。
  • 需要儲存格 numFmt 表達不出來的格式。
  • 輸出要去的地方無法套用儲存格格式（例如 CSV 消費端）。

支援的格式​

xl3 支援 Excel 核心格式表。核心表以外的格式依 ADR-0021 為實作定義 — 想讓 template.xlsx 跨實作可攜，請堅守傳統 Excel 標記。

規格指引​

  • spec/language.md 的「TEXT」與核心格式表。
  • ADR-0001（TODAY() 為 UTC）。
  • ADR-0017（日期值模型）。
  • ADR-0021（自訂格式字串為實作定義）。