본문으로 건너뛰기

11 · TEXT() 형식 지정

시나리오​

돈은 돈처럼 보여야 하고 ($#,##0.00), 날짜는 로캘에 깔끔하게 떨어져야 하며 (yyyy-mm-dd), 퍼센트에 소수점 8자리가 따라붙어선 안 됩니다 (0.0%). XTL 의 TEXT(value, format) 이 이 렌더링을 담당합니다.

통화​

{{ TEXT([금액], "₩#,##0") }}     → "$1,200.00"
{{ TEXT([금액], "[$₩-ko-KR] #,##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 를 쓰는 쪽이 더 간단합니다.

  • 엑셀에서 셀에 $#,##0.00 형식을 미리 지정합니다.
  • 표현식은 원본 숫자만 참조합니다: {{ [금액] }}.
  • xl3 가 결과에 셀 형식을 그대로 보존합니다.

이렇게 하면 셀이 숫자 타입으로 유지됩니다 — 엑셀에서 합계, 필터링 등이 그대로 동작합니다. TEXT() 는 셀을 문자열 타입으로 강제합니다. 다음 경우에 TEXT() 를 씁니다.

  • 형식화된 값을 문자열 연결 안에 넣어야 할 때.
  • 셀의 numFmt 로는 표현할 수 없는 형식이 필요할 때.
  • 결과물이 셀 형식을 적용해 주지 않는 곳으로 흘러갈 때 (예: CSV 소비자).

지원 형식​

xl3 는 Excel 핵심 형식 표를 지원합니다. 핵심 표 밖의 형식은 ADR-0021 에 따라 구현 정의 동작이므로 — template.xlsx 의 이식성을 유지하려면 관용적인 Excel 토큰만 사용하세요.

스펙 참고​

  • spec/language.md "TEXT" 와 핵심 형식 표.
  • ADR-0001 (TODAY() 는 UTC).
  • ADR-0017 (날짜 값 모델).
  • ADR-0021 (사용자 정의 형식 문자열은 구현 정의).