跳转到主要内容

11 · TEXT() 格式化

场景​

钱要看上去像钱（$#,##0.00），日期要简洁（yyyy-mm-dd），百分比不要带 8 位小数（0.0%）。XTL 的 TEXT(value, format) 负责完成这些渲染。

货币​

{{ TEXT([金额], "$#,##0.00") }}     → "$1,200.00"
{{ TEXT([金额], "[$￥-zh-CN] #,##0") }} → "￥ 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（自定义格式字符串属于实现自定义）。