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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/input-number.md.

InputNumber 数字输入框

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

基础用法

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

当前数量:3
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
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
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
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
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。

属性类型默认值说明
valuenumber | null | string—受控数值;stringMode 时使用字符串,空值为 null。
defaultValuenumber | null | stringnull非受控初始值;stringMode 时使用字符串,表单重置时恢复。
onChange((value: number | null) => void) | ((value: string | null) => void)—有效数字变化或清空时触发
minnumber | string无限制可输入数字的范围
maxnumber | string无限制可输入数字的范围
stepnumber | string1增减步长
precisionnumber—小数精度,范围 0–15
controlsbooleantrue展示增减按钮
keyboardbooleantrue支持上下方向键增减
size'sm' | 'md' | 'lg''md'控件尺寸
status'error' | 'warning'—校验状态
prefixReactNode—前后装饰内容
suffixReactNode—前后装饰内容
stringModefalse | true—使用字符串处理高精度数值、步长和边界。
formatter( value: number | string | null, info: { userTyping: boolean; input: string }, ) => string—格式化显示文字,不改变表单的原始值。
parser(text: string) => number | string—把显示文字还原为数值。
groupingboolean—启用本地化数字分组。
localestring—语言或数字格式的区域标识。
disabledbooleanfalse禁用交互。
readOnlybooleanfalse锁定业务值,禁止输入、选择、清除和删除。
refRef<HTMLInputElement>—输入框引用

NumericInputNumber API

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

属性类型默认值说明
valuenumber | null—受控值。
defaultValuenumber | nullnull初始值;非受控模式支持表单重置。
onChange(value: number | null) => void—值发生变化时调用。
minnumber—允许的最小值。
maxnumber—允许的最大值。
stepnumber1增减步长。
stringModefalse—数值模式,省略或传 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—把显示文字还原为数值。
stringModetrue必填高精度字符串模式,必须传 true;值、步长和边界使用字符串。
valuestring | null—受控值。
defaultValuestring | nullnull初始值;非受控模式支持表单重置。
onChange(value: string | null) => void—值发生变化时调用。
minstring—允许的最小值。
maxstring—允许的最大值。
stepstring'1'增减步长。