# Числовой формат

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

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

---

Числовой формат в электронных таблицах определяет, как отображаются числа. Он позволяет настраивать количество знаков после запятой, разделители разрядов, проценты, символы валют и другие параметры. Благодаря числовым форматам данные становятся более наглядными и понятными.

Действие валюты на панели инструментов выбирает символ и формат по свойству Univer `region`. Если оно не задано явно, `region` следует за `locale`:

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

> [!WARNING: Внимание]
> Синтаксис **DBNum** не поддерживается.



## Использование

В интерфейсе числовой формат ячейки можно задать через строку меню. Также можно установить поле [`s.n.pattern`](https://docs.univer.ai/ru-RU/guides/sheets/model/cell-data.md#number-format)[^number-format-value] в объекте данных ячейки [`ICellData`](https://docs.univer.ai/ru-RU/guides/sheets/model/cell-data.md).

```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/ru-RU/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/ru-RU/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%` показывает `0.25` как `25%`, но формулы используют `0.25`.

## Локализованные форматы дат

Панель форматов даты использует текущую настройку `locale` Univer для шаблонов и предварительного просмотра. Существующие пользовательские форматы остаются доступны. При смене выделенного диапазона панель обновляется в соответствии с текущими ячейками.