# 數字格式

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

數字格式是電子表格中用於控制數字顯示方式的功能。它允許使用者自訂數字的顯示格式，包括小數點位數、千位分隔符、百分比、貨幣符號等。透過設定數字格式，使用者可以使資料更易於閱讀和理解。

工具列的貨幣操作會根據 Univer 的 `region` 選擇貨幣符號和格式。未明確設定時，`region` 會跟隨 `locale`：

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

> [!WARNING: 注意事項]
> 不支援 **DBNum** 語法



## 使用方法

UI 介面中，可以透過選單欄設定單元格的數字格式。或者在單元格資料 [`ICellData`](https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data.md) 物件中設定 [`s.n.pattern`](https://docs.univer.ai/zh-TW/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, // 文字格式
    },
  },
}
```

或使用 Facade API 設定單元格格式：

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

2. 在輸入數字前加上單引號 `'`（[強制文字](https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data.md#cell-type)）

## Facade API

### 引入

> [!INFO: 外掛模式提示]
> 僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。

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

### 設定數字格式

具體參數請參考 [https://support.microsoft.com/zh-cn/office/%E6%95%B0%E5%AD%97%E6%A0%BC%E5%BC%8F%E4%BB%A3%E7%A0%81-5026bbd6-04bc-48cd-bf33-80f18b4eae68](https://support.microsoft.com/zh-cn/office/%E6%95%B0%E5%AD%97%E6%A0%BC%E5%BC%8F%E4%BB%A3%E7%A0%81-5026bbd6-04bc-48cd-bf33-80f18b4eae68)

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

// 將 A1 單元格的數字格式設定為 '#,##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()

// 設定 A1:B2 範圍的數字格式
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()

// 獲取 A1:B2 範圍左上角單元格的數字格式
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormat()
```

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

// 獲取 A1:B2 範圍的數字格式
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormats()
```

### 設定數字格式的區域設定

使用 [`FWorkbook.setNumfmtLocal(local)`](https://docs.univer.ai/zh-TW/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')

// 設定數字格式的區域設定為 en
fWorkbook.setNumfmtLocal('en')
fRange.getDisplayValue() // 1,234.57

// 設定數字格式的區域設定為 de
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` 產生預設格式與預覽。既有的自訂日期格式仍可選取。切換選取範圍後，格式面板會重新整理，讓控制項反映目前儲存格的格式。