# 숫자 형식

- Human documentation: [https://docs.univer.ai/ko-KR/guides/sheets/features/core/numfmt](https://docs.univer.ai/ko-KR/guides/sheets/features/core/numfmt)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/sheets/features/core/numfmt.md](https://docs.univer.ai/ko-KR/guides/sheets/features/core/numfmt.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [sheets/features/core/numfmt.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/numfmt.ko-KR.mdx)

---

스프레드시트의 숫자 형식 기능은 숫자가 표시되는 방식을 제어하는 데 사용합니다. 소수 자릿수, 천 단위 구분 기호, 백분율, 통화 기호 등 숫자의 표시 형식을 사용자가 지정할 수 있습니다. 숫자 형식을 설정하면 데이터를 더 쉽게 읽고 이해할 수 있습니다.

도구 모음의 통화 작업은 Univer의 `region`에 따라 통화 기호와 형식을 선택합니다. 명시적으로 설정하지 않으면 `region`은 `locale`을 따릅니다.

```typescript
const univer = new Univer({
  locale: LocaleType.KO_KR,
  region: LocaleType.DE_DE,
})
```

> [!WARNING: 주의]
> **DBNum 구문**은 지원되지 않습니다.



## 사용법

UI에서는 메뉴 모음을 통해 셀의 숫자 형식을 설정할 수 있습니다. 또는 셀 데이터 [`ICellData`](https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data.md) 객체의 [`s.n.pattern`](https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data.md#number-format)[^number-format-value] 필드를 설정할 수 있습니다.

```typescript
const data = {
  v: 123456.789,
  s: {
    n: {
      pattern: '#,##0.00',
    },
  },
}
```

**기본적으로 0으로 시작하는 텍스트와 날짜 형식으로 변환할 수 있는 숫자는 해당 숫자 형식으로 자동 변환됩니다.**

이 자동 변환을 원하지 않으면 다음 방법 중 하나를 선택할 수 있습니다.

1. 셀 숫자 형식을 텍스트 형식으로 설정합니다.

```typescript
import { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'

const data = {
  v: '012.0',
  s: {
    n: {
      pattern: DEFAULT_TEXT_FORMAT_EXCEL, // Text format
    },
  },
}
```

또는 Facade API를 사용하여 셀 형식을 설정합니다.

```typescript
fRange.setNumberFormat(DEFAULT_TEXT_FORMAT_EXCEL)
```

2. 숫자를 입력하기 전에 작은따옴표 `'`를 추가합니다. 이를 [텍스트 강제 적용](https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data.md#cell-type)이라고 합니다.

## Facade API

### 가져오기

> [!INFO: 플러그인 모드 참고 사항]
> Facade 패키지를 직접 가져와야 하는 것은 플러그인 모드뿐입니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

```typescript
import '@univerjs/sheets-numfmt/facade'
```

### 숫자 형식 설정

구체적인 매개변수는 다음 문서를 참고하세요. [https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68](https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68)

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set the number format of the A1 cell to '#,##0.00'.
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')
fRange.getDisplayValue() // 1,234.57
```

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set the number formats of the A1:B2 range.
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  [1234.567, 0.1234],
  [45658, 0.9876],
]).setNumberFormats([
  ['#,##0.00', '0.00%'],
  ['yyyy-MM-DD', ''],
])
fRange.getDisplayValues() // [['1,234.57', '12.34%'], ['2025-01-01', 0.9876]]
```

### 숫자 형식 가져오기

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Get the number format of the top-left cell of the A1:B2 range.
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormat()
```

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Get the number formats of the A1:B2 range.
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormats()
```

### 숫자 형식의 로캘 설정

[`FWorkbook.setNumfmtLocal(local)`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#setnumfmtlocal) 메서드를 사용해 숫자 형식의 로캘을 설정할 수 있습니다.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')

// Set the locale en for number formatting.
fWorkbook.setNumfmtLocal('en')
fRange.getDisplayValue() // 1,234.57

// Set the locale de for number formatting.
fWorkbook.setNumfmtLocal('de')
fRange.getDisplayValue() // 1.234,57
```

## 텍스트 형식 경고 및 표시 비활성화

`UniverSheetsNumfmtPlugin` 플러그인은 셀 텍스트 형식의 경고와 표시를 비활성화하는 `disableTextFormatAlert` 및 `disableTextFormatMark` 구성 항목을 제공합니다.

사용 중인 모드를 선택하고 기존 초기화 설정에 아래 옵션을 병합하세요. 다른 플러그인, 언어, 테마 및 컨테이너 설정은 유지하고 같은 플러그인을 중복 등록하지 마세요.

#### 플러그인 모드

```typescript
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'

univer.registerPlugin(UniverSheetsNumfmtPlugin, {
  disableTextFormatAlert: true,
  disableTextFormatMark: true,
})
```

#### 프리셋 모드

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import { createUniver } from '@univerjs/presets'

const { univerAPI } = createUniver({
  presets: [
    UniverSheetsCorePreset({
      disableTextFormatAlert: true,
      disableTextFormatMark: true,
    }),
  ],
})
```

[^number-format-value]: 숫자 서식은 표시만 바꾸고 저장된 값은 바꾸지 않습니다. `0.25`에 `0%` 서식을 적용하면 `25%`로 표시되지만 수식은 `0.25`로 계산합니다.

## 지역별 날짜 프리셋

날짜 형식 패널은 Univer의 현재 `locale`에 맞는 형식과 미리보기를 제공합니다. 기존 사용자 지정 날짜 형식도 선택할 수 있습니다. 선택 범위를 바꾸면 패널이 현재 셀의 형식을 반영하도록 갱신됩니다.