# 숫자와 날짜

> 만·억 단위, "단위: 백만원", 통화 기호, 소수점, 날짜 모양, 시간대.

Source: https://82chart.com/docs/numbers-dates/

축 눈금은 짧게, 툴팁·표는 정확하게 적는 것이 기본입니다. 한국어 페이지에서 축은 **1.2만 · 3.4억 · 6,000만**, 툴팁은 **123,456,789원**처럼 쉼표가 들어간 전체 숫자입니다.

## numberFormat

| 값 | 12,345 → | 340,000,000 → | 쓰는 곳 |
| --- | --- | --- | --- |
| `'korean'` | 1.2만 | 3.4억 | 한국어 페이지 기본 |
| `'compact'` | 12.3K | 340M | 그 외 언어 기본 |
| `'comma'` | 12,345 | 340,000,000 | 정확한 숫자가 필요한 표·보고서 |
| `'percent'` | 12,345% | - | 값이 이미 퍼센트일 때 (0.5 가 아니라 50 으로 넘김) |
| 함수 | `(v) => string` |  | 축과 툴팁에 모두 씀 |

축 눈금만 따로 바꾸려면 `yAxis: { format }` (또는 `xAxis`) 에 같은 값을 줍니다. 숫자 도우미는 따로 꺼내 쓸 수도 있습니다.

```js
import { korean, compact, comma } from '@82chart/core';
korean(123456789);  // '1.2억'
compact(123456789); // '123.5M'
comma(1234.5);      // '1,234.5'
```

## "단위: 백만원" 보고서 방식

공공 자료·보고서처럼 축을 백만원 단위 쉼표 숫자로 쓰고 싶다면 `scale` 로 나누고 `unit` 을 붙입니다. `scale` 이 있으면 축·툴팁·표가 모두 나눈 숫자에 단위를 붙여 적고, 머리 숫자(`value`)는 원래 금액 그대로입니다. `footnote` 로 단위를 밝혀 두세요.

```js
createChart('#chart', {
  type: 'bar',
  title: '사업부별 매출',
  scale: 1000000,
  unit: '백만원',
  footnote: '단위: 백만원',
  data: {
    labels: ['국내', '해외', '온라인', '도매'],
    series: [{ name: '매출', data: [1820000000, 940000000, 2310000000, 610000000] }],
  },
});
```

| 옵션 | 설명 |
| --- | --- |
| `unit` | 값 뒤에 붙는 단위: `'원'`, `'명'`, `'%'`, `'백만원'` |
| `prefix` | 값 앞에: `'₩ '`, `'$'`. `scale` 과 함께 쓰면 툴팁은 원래 금액 전체(₩ 1,820,000,000) |
| `scale` | 축 눈금을 이 수로 나눔 (1000000 → 백만 단위) |
| `decimals` | 툴팁·라벨의 소수 자리 (기본: 최대 2자리, 끝의 0은 지움) |

## 날짜 모양

날짜 축의 라벨은 간격에 맞게 정해집니다. 월 단위면 `1월 · 2월` (해가 바뀌면 `2027년 1월`), 일 단위면 `10.21`, 시간 단위면 `09:00`. 툴팁은 `2026.10.21(화)` 처럼 요일까지 씁니다. 직접 정하려면 `dateFormat` 에 패턴을 넘깁니다.

| 토큰 | 뜻 | 예 |
| --- | --- | --- |
| `YYYY` / `YY` | 연도 | 2026 / 26 |
| `M` / `MM` | 월 | 3 / 03 |
| `MMM` | 월 이름(영어 등 이름이 있는 언어) | Mar |
| `D` / `DD` | 일 | 7 / 07 |
| `ddd` | 요일 | 화 |
| `H` / `HH` | 시 | 9 / 09 |
| `mm` / `ss` | 분 / 초 | 05 / 30 |

```js
createChart('#chart', {
  type: 'line',
  dateFormat: 'MM/DD(ddd)', // 10/21(화)
  data: { series: [{ name: '방문자', data: [['2026-10-20', 1820], ['2026-10-21', 2140]] }] },
});
```

`dateFormat` 은 축과 툴팁에 함께 쓰입니다. `'auto'` 는 기본 동작입니다.

## 시간대 (timeZone)

날짜는 기본으로 실행 환경의 시간대로 읽고 적습니다. 브라우저에서는 보통 문제가 없지만, 서버(Cloudflare Workers, 대부분의 Node 서버)는 UTC 라서 `renderToSVG` 로 그리면 한국 자정 데이터가 전날로 찍힙니다. `timeZone` 에 IANA 이름을 주면 축·툴팁·표·CSV 가 모두 그 시간대로 적힙니다. `'2026-10-21'` 처럼 날짜만 있는 문자열은 그 시간대의 그날, 시차 표시가 없는 `'2026-10-21T09:00'` 은 그 시간대의 9시로 읽습니다.

```js
createChart('#chart', {
  type: 'line',
  timeZone: 'Asia/Seoul', // 어디서 실행해도 한국 시간
  data: { series: [{ name: '주문', data: [['2026-10-21T00:00:00Z', 120], ['2026-10-21T06:00:00Z', 180]] }] },
});
```

시간대 이름이 틀리면 경고를 한 번 남기고 실행 환경의 시간대로 그립니다. 내보낸 숫자 도우미 `formatDate(date, pattern, locale, timeZone)` 도 네 번째 인자로 시간대를 받습니다.