website/sdds-cs-docs/docs/components/NumberFormat.mdx - dev - sdds/plasma

website/sdds-cs-docs/docs/components/NumberFormat.mdx
209 строк7 KB
TitanKuzmich
feat(sdds-cs-docs): add numberFormatter docs
03 дек 2025, 15:04
03 дек 2025, 15:04bb7c58f
---
id: number-format
title: NumberFormat
---

import { PropsTable, Description } from '@site/src/components';

# NumberFormat
<Description name="NumberFormat" />
<PropsTable name="NumberFormat" exclude={['css']} />

## Использование
Компонент `NumberFormat` представляет собой поле ввода с поле ввода числовых значений.
Он реализован на компоненте [TextField](https://plasma.sberdevices.ru/sdds-cs/components/textfield/) 
и наследует практически все его свойства (`size`, `view`, `disabled`, `label` и тд.)

### Разделитель тысяч и десятичных знаков
Разделитель тысяч задается с помощью свойства `thousandSeparator`, 
а разделитель десятичных знаков с помощью `decimalSeparator`:

```tsx live
import React from 'react';
import { NumberFormat } from '@salutejs/sdds-cs';

export function App() {
    return (
        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
            <NumberFormat
                size="s"
                thousandSeparator=" "
                decimalSeparator="."
                defaultValue="123456.789"
            />
            <NumberFormat
                size="s"
                thousandSeparator="/"
                decimalSeparator=","
                defaultValue="123456,789"
            />
            <NumberFormat
                size="s"
                thousandSeparator=","
                decimalSeparator="$"
                defaultValue="123456$789"
            />
        </div>
    );
}
```

### Стиль группировки тысяч
Поддерживается четыре вида группировок:
- 'thousand' (123 456 789)
- 'lakh' (индийский стиль, 12 34 56 789)
- 'wan' (китайский стиль, 1 2345 6789)
- 'none' (без группировки)

```tsx live
import React from 'react';
import { NumberFormat } from '@salutejs/sdds-cs';

export function App() {
    return (
        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
            <NumberFormat
                size="s"
                thousandSeparator=" "
                defaultValue="123456789"
                thousandsGroupStyle="thousand"
            />
            <NumberFormat
                size="s"
                thousandSeparator=" "
                defaultValue="123456789"
                thousandsGroupStyle="lakh"
            />
            <NumberFormat
                size="s"
                thousandSeparator=" "
                defaultValue="123456789"
                thousandsGroupStyle="wan"
            />
            <NumberFormat
                size="s"
                thousandSeparator=" "
                defaultValue="123456789"
                thousandsGroupStyle="none"
            />
        </div>
    );
}
```

### Количество знаков после запятой
Количество знаков после запятой задается с помощью свойства `decimalScale`.
Если же необходимо, чтобы число имело определенное количество знаков после запятой, то нужно задать `fixedDecimalScale`:

```tsx live
import React from 'react';
import { NumberFormat } from '@salutejs/sdds-cs';

export function App() {
    return (
        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
            <NumberFormat
                size="s"
                defaultValue="123"
                thousandSeparator=" "
                decimalSeparator="."
                decimalScale={4}
                fixedDecimalScale
            />
            <NumberFormat
                size="s"
                defaultValue="123.1"
                thousandSeparator=" "
                decimalSeparator="."
                decimalScale={4}
                fixedDecimalScale
            />
        </div>
    );
}
```

### Отрицательные числа
Свойство ` allowNegative` позволяет вводить отрицательные числа:

```tsx live
import React from 'react';
import { NumberFormat } from '@salutejs/sdds-cs';

export function App() {
    return (
        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
            <NumberFormat
                size="s"
                defaultValue="-123"
                thousandSeparator=" "
                decimalSeparator="."
                allowNegative
            />
        </div>
    );
}
```

### Ведущие нули
Чтобы разрешить в числе ведущие нули, нуджно указать свойство `allowLeadingZeros`:

```tsx live
import React from 'react';
import { NumberFormat } from '@salutejs/sdds-cs';

export function App() {
    return (
        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
            <NumberFormat
                size="s"
                defaultValue="000123.456"
                thousandSeparator=" "
                decimalSeparator="."
                allowLeadingZeros
            />
        </div>
    );
}
```

### Функция форматирования
Для приведения числа к нужному формату можно использовать функцию `numberFormatter`.
Она принимает два параметра:
- строковое значение
- объект с параметрами форматирования

```tsx
const num = 100.23
const options = {
    /**
     * Разделитель тысяч.
     * Может быть строкой (например, " ").
     * @example 123 456 789
     */
    thousandSeparator: ' ',
    /**
     * Разделитель десятичных знаков (например, ".").
     * @example 123.456
     */
    decimalSeparator: '.',
    /**
     * Количество знаков после запятой.
     */
    decimalScale: 3,
    /**
     * Фиксирует количество знаков после запятой, даже если число их не содержит (добавляет нули).
     */
    fixedDecimalScale: false,
    /**
     * Разрешает ввод отрицательных чисел.
     */
    allowNegative: true,
    /**
     * Разрешает ведущие нули (например, "0123").
     */
    allowLeadingZeros: false,
}

const value = numberFormatter(String(num), options)
```