# 数字格式

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-core",
      "locale": "@univerjs/preset-sheets-core/locales/zh-CN",
      "style": "@univerjs/preset-sheets-core/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/sheets-numfmt",
      "facade": "@univerjs/sheets-numfmt/facade"
    },
    {
      "client": "@univerjs/sheets-numfmt-ui",
      "locale": "@univerjs/sheets-numfmt-ui/locale/zh-CN",
      "style": "@univerjs/sheets-numfmt-ui/lib/index.css"
    }
  ],
  "server": false
}
```

数字格式是电子表格中用于控制数字显示方式的功能。它允许用户自定义数字的显示格式，包括小数点位数、千位分隔符、百分比、货币符号等。通过设置数字格式，用户可以使数据更易于阅读和理解。

工具栏的货币操作会根据 Univer 的 `region` 选择货币符号和格式。未显式配置时，`region` 会跟随 `locale`：

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

> [!WARNING: 注意事项]
> 不支持 **DBNum** 语法

## 使用方法

UI 界面中，可以通过菜单栏设置单元格的数字格式。或者在单元格数据 [`ICellData`](https://docs.univer.ai/zh-CN/guides/sheets/model/cell-data.md) 对象中设置 [`s.n.pattern`](https://docs.univer.ai/zh-CN/guides/sheets/model/cell-data.md#number-format) 字段。

```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-CN/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-CN/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_US
fWorkbook.setNumfmtLocal('en_US')
fRange.getDisplayValue() // 1,234.57

// 设置数字格式的区域设置为 de_DE
fWorkbook.setNumfmtLocal('de_DE')
fRange.getDisplayValue() // 1.234,57
```

## 禁用单元格文本格式警告和标记

`UniverSheetsNumfmtPlugin` 插件提供了 `disableTextFormatAlert` 和 `disableTextFormatMark` 两个配置项，用于禁用单元格文本格式的警告和标记。

```typescript
// presets 配置
const { univerAPI } = createUniver({
  // ...
  presets: [
    UniverSheetsCorePreset({
      disableTextFormatAlert: true,
      disableTextFormatMark: true,
    }),
  ],
})
```

```typescript
// Plugin 配置
univer.registerPlugin(UniverSheetsNumfmtPlugin, {
  disableTextFormatAlert: true,
  disableTextFormatMark: true,
})
```