> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# InputNumber

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

输入并格式化货币、百分比及其他数值。

## 何时使用

数值需要范围、小数位、前后缀或本地化分隔符时使用 InputNumber。

**推荐**

- 明确展示单位与格式。
- 范围限制应与错误提示一致。

**避免**

- 普通文本或编号标识不要使用数值输入。

## 代码演示


### 基础用法
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';
import { useState } from 'react';

function InputNumberExample() {
  const [value, setValue] = useState('1500');

  return (
    <InputNumber
      value={value}
      onChange={setValue}
      prefix="$"
      suffix="USD"
      decimalPlaces={2}
      thousandsSeparator=","
    />
  );
}

export default InputNumberExample;
```

### 货币与百分比
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';

function InputNumberFormats() {
  return (
    <Stack gap="md">
      <InputNumber
        defaultValue="150000"
        prefix="€"
        decimalPlaces={2}
        thousandsSeparator=","
      />
      <InputNumber
        defaultValue="0.42"
        isPercentage
        suffix="%"
        decimalPlaces={1}
      />
    </Stack>
  );
}

export default InputNumberFormats;
```

### 尺寸、变体与范围
```tsx preview
import { InputNumber, Stack } from '@rockshin/tao-ui';

function InputNumberStates() {
  return (
    <Stack gap="md">
      <InputNumber size="small" variant="outlined" placeholder="Small" />
      <InputNumber
        size="medium"
        variant="filled"
        min={0}
        max={100}
        defaultValue="50"
      />
      <InputNumber size="large" variant="borderless" error defaultValue="120" />
    </Stack>
  );
}

export default InputNumberStates;
```

### 货币格式
千位分隔符、两位小数和前缀只改变展示，输出值便于业务计算。
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberCurrency() {
  const args: React.ComponentProps<typeof InputNumber> = {
    prefix: '€',
    thousandsSeparator: ',',
    decimalSeparator: '.',
    decimalPlaces: 2,
    value: '150000',
    placeholder: 'Amount',
  };
  return <ControlledWrapper {...args} />;
}
```

### 前后缀
用前后缀表达单位，避免将单位混入业务数值。
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberWithSuffix() {
  const args: React.ComponentProps<typeof InputNumber> = {
    suffix: 'USD',
    prefix: '$',
    decimalPlaces: 2,
    placeholder: 'Try 1234567',
  };
  return <ControlledWrapper {...args} />;
}
```

### 三种尺寸
比较三种输入尺寸，数值处理规则保持一致。
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';

export default function InputNumberSizes() {
  const args: React.ComponentProps<typeof InputNumber> = {
    thousandsSeparator: ',',
  };
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber {...args} size="small" prefix="¥" value="1000" />
      <InputNumber {...args} size="medium" prefix="¥" value="1000" />
      <InputNumber {...args} size="large" prefix="¥" value="1000" />
    </div>
  );
}
```

### 外观变体
在不同外观下使用相同的受控输入逻辑。
```tsx preview
import { InputNumber } from '@rockshin/tao-ui';

export default function InputNumberVariants() {
  const args: React.ComponentProps<typeof InputNumber> = {
    thousandsSeparator: ',',
  };
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber {...args} variant="outlined" prefix="¥" value="1000" />
      <InputNumber {...args} variant="filled" prefix="¥" value="1000" />
      <InputNumber {...args} variant="borderless" prefix="¥" value="1000" />
    </div>
  );
}
```

### 百分比
配置小数精度和百分号后缀，本例不自动换算百分比与小数。
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberPercentage() {
  const args: React.ComponentProps<typeof InputNumber> = {
    isPercentage: true,
    decimalPlaces: 2,
    suffix: '%',
    placeholder: 'Type 50 → actual is 0.5',
  };
  return <ControlledWrapper {...args} />;
}
```

### 数值上下限
设置允许的范围，输入和失焦后的值应遵循范围配置。
```tsx preview
import { useState } from 'react';

import { InputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(props: React.ComponentProps<typeof InputNumber>) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <InputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function InputNumberClampedRange() {
  const args: React.ComponentProps<typeof InputNumber> = {
    min: 0,
    max: 100,
    decimalPlaces: 0,
    placeholder: 'Type 999, blur to clamp to 100',
  };
  return <ControlledWrapper {...args} />;
}
```

## 地区格式

地区分组、小数符号和数字字符继承 `TaoProvider.locale.numberLocale`，也可用组件 `locale="fr-FR"` 覆盖。显式分隔符优先；数字输入在本地化显示的同时保留规范 ASCII 字符串及精度。

## API


### [#](#inputnumber)InputNumber



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |

