メインコンテンツへスキップ

11 · TEXT() 書式指定

シナリオ​

お金はお金らしく見える必要があり($#,##0.00)、日付はロケールに沿ってきれいに(yyyy-mm-dd)、パーセントに小数 8 桁が付いてはいけません(0.0%)。XTL の TEXT(value, format) がこのレンダリングを担当します。

通貨​

{{ TEXT([金額], "¥#,##0") }}     → "$1,200.00"
{{ TEXT([金額], "[$¥-ja-JP] #,##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 基準の今日の日付を返します。運用担当者のタイムゾーンが重要なら、TODAY() を呼ぶ代わりに __inputs__ 値として日付を渡してください。

パーセント​

{{ TEXT([マージン], "0.0%") }}     → "12.3%"(マージンが 0.1234 のとき)
{{ TEXT([レート], "0%") }}          → "8%"

文字列連結と組み合わせる​

{{ "合計: " & TEXT(SUM([金額]), "¥#,##0") }}    → "合計: ¥43,500"
{{ "Run: " & TEXT(TODAY(), "yyyy-mm-dd") }}          → "Run: 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(ユーザー定義書式文字列は実装定義)。