> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/input-number.html

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

# InputNumber 数字输入框

输入数量、金额等数字内容。


## 基础用法

通过 `min`、`max` 限制范围。`onChange` 返回数值，清空时返回 `null`。输入中的负号或小数点会暂时保留，失焦或按 Enter 时校正范围与精度。


数量

当前数量：3

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-number/basic.tsx"
import { Form, FormField, InputNumber, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputNumberBasic() {
  const [value, setValue] = useState<number | null>(3);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="数量">
        <InputNumber name="quantity" min={0} max={20} value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        当前数量：{value ?? '未填写'}
      </Text>
    </Form>
  );
}
```

展开代码


## 示例

### 单位与小数

使用 `prefix`、`suffix` 展示单位，通过 `step` 和 `precision` 设置步长与小数位数。`controls={false}` 隐藏增减按钮。


金额

¥

百分比

%

units.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-number/units.tsx"
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberUnits() {
  return (
    <Form layout="vertical">
      <FormField label="金额">
        <InputNumber min={0} step={0.1} precision={2} defaultValue={19.9} prefix="¥" />
      </FormField>
      <FormField label="百分比">
        <InputNumber defaultValue={50} min={0} max={100} suffix="%" controls={false} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 只读与禁用

只读状态保留数值但禁止编辑；禁用状态不可交互。


只读

禁用

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-number/states.tsx"
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberStates() {
  return (
    <Form layout="vertical">
      <FormField label="只读">
        <InputNumber defaultValue={12} readOnly />
      </FormField>
      <FormField label="禁用">
        <InputNumber defaultValue={8} disabled />
      </FormField>
    </Form>
  );
}
```

展开代码

### 格式化显示

[](#)
使用 `grouping` 显示本地化数字分组。自定义格式时，`formatter` 负责显示，`parser` 将输入文字还原为数值；格式化不改变原生表单提交的原始值。


千分位分组

自定义百分比

formatting.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-number/formatting.tsx"
import { Form, FormField, InputNumber } from '@ifhover/leaf-ui';

export function InputNumberFormatting() {
  return (
    <Form layout="vertical">
      <FormField label="千分位分组">
        <InputNumber defaultValue={12345.67} precision={2} grouping />
      </FormField>
      <FormField label="自定义百分比">
        <InputNumber
          defaultValue={15}
          min={0}
          max={100}
          formatter={(value) => (value == null ? '' : `${value}%`)}
          parser={(text) => text.replace('%', '')}
        />
      </FormField>
    </Form>
  );
}
```

展开代码

### 高精度数值

超出 JavaScript Number 安全精度时，使用 `stringMode`。该模式下 `value`、`defaultValue`、`step`、`min` 和 `max` 使用字符串，`onChange` 返回字符串或 `null`；不要先转成 Number。


高精度金额

当前值：9007199254740993.01

exact.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-number/exact.tsx"
import { Form, FormField, InputNumber, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function InputNumberExact() {
  const [value, setValue] = useState<string | null>('9007199254740993.01');

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="高精度金额">
        <InputNumber
          stringMode
          name="amount"
          value={value}
          onChange={setValue}
          step="0.01"
          precision={2}
        />
      </FormField>
      <Text tone="muted" role="status">
        当前值：{value ?? '未填写'}
      </Text>
    </Form>
  );
}
```

展开代码


## API

### InputNumber API

#### 表单接入

设置 `name` 可通过 FormData 提交原始数值。非受控字段支持表单重置，受控字段需同步重置应用状态。`required`、`form` 等原生属性传给输入元素；表单接入见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。

| 属性             | 类型                                                                                             | 默认值     | 说明                                |
| -------------- | ---------------------------------------------------------------------------------------------- | ------- | --------------------------------- |
| `value`        | `number \| null \| string`                                                                     | —       | 受控数值；stringMode 时使用字符串，空值为 null。  |
| `defaultValue` | `number \| null \| string`                                                                     | `null`  | 非受控初始值；stringMode 时使用字符串，表单重置时恢复。 |
| `onChange`     | `((value: number \| null) => void) \| ((value: string \| null) => void)`                       | —       | 有效数字变化或清空时触发                      |
| `min`          | `number \| string`                                                                             | 无限制     | 可输入数字的范围                          |
| `max`          | `number \| string`                                                                             | 无限制     | 可输入数字的范围                          |
| `step`         | `number \| string`                                                                             | `1`     | 增减步长                              |
| `precision`    | `number`                                                                                       | —       | 小数精度，范围 0–15                      |
| `controls`     | `boolean`                                                                                      | `true`  | 展示增减按钮                            |
| `keyboard`     | `boolean`                                                                                      | `true`  | 支持上下方向键增减                         |
| `size`         | `'sm' \| 'md' \| 'lg'`                                                                         | `'md'`  | 控件尺寸                              |
| `status`       | `'error' \| 'warning'`                                                                         | —       | 校验状态                              |
| `prefix`       | `ReactNode`                                                                                    | —       | 前后装饰内容                            |
| `suffix`       | `ReactNode`                                                                                    | —       | 前后装饰内容                            |
| `stringMode`   | `false \| true`                                                                                | —       | 使用字符串处理高精度数值、步长和边界。               |
| `formatter`    | `( value: number \| string \| null, info: { userTyping: boolean; input: string }, ) => string` | —       | 格式化显示文字，不改变表单的原始值。                |
| `parser`       | `(text: string) => number \| string`                                                           | —       | 把显示文字还原为数值。                       |
| `grouping`     | `boolean`                                                                                      | —       | 启用本地化数字分组。                        |
| `locale`       | `string`                                                                                       | —       | 语言或数字格式的区域标识。                     |
| `disabled`     | `boolean`                                                                                      | `false` | 禁用交互。                             |
| `readOnly`     | `boolean`                                                                                      | `false` | 锁定业务值，禁止输入、选择、清除和删除。              |
| `ref`          | `Ref<HTMLInputElement>`                                                                        | —       | 输入框引用                             |

### NumericInputNumber API

这里只列出该模式的类型差异；通用参数见本页主 API 表。

| 属性             | 类型                                                                                             | 默认值    | 说明                             |
| -------------- | ---------------------------------------------------------------------------------------------- | ------ | ------------------------------ |
| `value`        | `number \| null`                                                                               | —      | 受控值。                           |
| `defaultValue` | `number \| null`                                                                               | `null` | 初始值；非受控模式支持表单重置。               |
| `onChange`     | `(value: number \| null) => void`                                                              | —      | 值发生变化时调用。                      |
| `min`          | `number`                                                                                       | —      | 允许的最小值。                        |
| `max`          | `number`                                                                                       | —      | 允许的最大值。                        |
| `step`         | `number`                                                                                       | `1`    | 增减步长。                          |
| `stringMode`   | `false`                                                                                        | —      | 数值模式，省略或传 false；值和回调使用 number。 |
| `formatter`    | `( value: number \| string \| null, info: { userTyping: boolean; input: string }, ) => string` | —      | 格式化显示文字，不改变表单的原始值。             |
| `parser`       | `(text: string) => number \| string`                                                           | —      | 把显示文字还原为数值。                    |

### StringInputNumber API

这里只列出该模式的类型差异；通用参数见本页主 API 表。

| 属性             | 类型                                                                                             | 默认值    | 说明                              |
| -------------- | ---------------------------------------------------------------------------------------------- | ------ | ------------------------------- |
| `formatter`    | `( value: number \| string \| null, info: { userTyping: boolean; input: string }, ) => string` | —      | 格式化显示文字，不改变表单的原始值。              |
| `parser`       | `(text: string) => number \| string`                                                           | —      | 把显示文字还原为数值。                     |
| `stringMode`   | `true`                                                                                         | 必填     | 高精度字符串模式，必须传 true；值、步长和边界使用字符串。 |
| `value`        | `string \| null`                                                                               | —      | 受控值。                            |
| `defaultValue` | `string \| null`                                                                               | `null` | 初始值；非受控模式支持表单重置。                |
| `onChange`     | `(value: string \| null) => void`                                                              | —      | 值发生变化时调用。                       |
| `min`          | `string`                                                                                       | —      | 允许的最小值。                         |
| `max`          | `string`                                                                                       | —      | 允许的最大值。                         |
| `step`         | `string`                                                                                       | `'1'`  | 增减步长。                           |
