组件 · 数据录入

InputNumber 数字输入

数字输入框。

入口 @selrux/ui/input-number · 源码 src/components/input-number/index.ts · 5 个组件 · 发布状态 preview

使用建议

避免：用文本 Input 假装数字校验
限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造

引入

tsx

1234567import {
  InputNumber,
  InputNumberDecrement,
  InputNumberGroup,
  InputNumberIncrement,
  InputNumberInput,
} from '@selrux/ui/input-number';

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

代码演示

基础用法

min / max / step 限定范围与步长。

精度与格式化

precision 保留小数，formatter / parser 处理显示格式。

按钮模式与状态

mode="spinner" 两侧加减按钮；disabled、invalid。

受控与步长

value / onValueChange 受控；smallStep（Alt）/ largeStep（Shift）步长；snapOnStep 对齐步长；keyboard 方向键；changeOnWheel 滚轮修改；allowWheelScrub 拖拽擦洗；size 尺寸。

value = 12

按钮、清除与前后缀

controls 定制增减按钮；showButton / buttonPlacement（both / left / right）；clearable、clearLabel、clearIndicator、onClear；prefix / suffix；placeholder；readOnly；name 表单字段名。

¥元

已清空 0 次

提交时机与校验

updateValueOnInput 输入时即时更新、changeOnBlur 失焦提交；validator 自定义合法性（这里只允许偶数）；inputProps 透传给内部 input。

value = 2（奇数会被拒绝）

API

属性覆盖：示例用到 35 / 35 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

InputNumber.form：原生 form 关联（外部 form id），无可见效果

InputNumber

主题化数字输入。ref 指向可见 input。默认拼装 Group / 前后缀 / 清空 / 步进；传入 children 时完全自定义组合。

属性	说明	类型	默认值
`size`	控件尺寸；缺省跟随 ConfigProvider，再回退 md。	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	-
`value`	受控值。	`InputNumberValue`	-
`defaultValue`	非受控初始值。	`InputNumberValue`	-
`onValueChange`	值变化回调；同值不触发。	`((value: InputNumberValue) => void)`	-
`onValueCommitted`	提交回调（失焦钳制、步进指针松开时）。对齐 Base `onValueCommitted`；与键盘/滚轮同步触发。	`((value: InputNumberValue) => void)`	-
`min`	最小值。	`number`	-
`max`	最大值。	`number`	-
`step`	步进；可为小数。	`number`	-
`smallStep`	Alt 键微调步长（Base `smallStep`）。	`number`	-
`largeStep`	Shift 键大步长（Base `largeStep`）。	`number`	-
`snapOnStep`	步进时是否吸附到 step 网格（Base `snapOnStep`）。	`boolean`	-
`precision`	展示/提交精度；与 formatter 并存时以 formatter 为准。	`number`	-
`formatter`	展示格式化；对齐 Ant `formatter` / Naive `format`。设定后键入过程是否立刻写回数值仍受 `updateValueOnInput` 约束。	`((value: number \| string, info: InputNumberFormatInfo) => string)`	-
`parser`	从展示串还原；对齐 Ant `parser` / Naive `parse`。返回 string 时再走默认数值解析；返回 number/null 则直接采用。	`((display: string) => string \| number \| null)`	-
`keyboard`	键盘步进；默认开启。	`InputNumberKeyboard`	-
`changeOnWheel`	聚焦且悬停时滚轮改值（Ant `changeOnWheel`）。别名 `allowWheelScrub` 会归一到本字段。	`boolean`	-
`allowWheelScrub`	Base 别名；与 `changeOnWheel` 等价，文档只推 `changeOnWheel`。	`boolean`	-
`controls`	步进按钮：`true` 常显、`false` 不渲染、`'hover'` 悬停/焦点显示。对象时可定制图标，并用 `visibility: 'hover'` 叠加显隐（Ant `controls` 扩展）。别名 `showButton` 仅归一布尔语义（不表达 hover）。	`boolean \| "hover" \| InputNumberControls`	-
`showButton`	Naive `showButton` 别名；仅 `true`/`false`。	`boolean`	-
`buttonPlacement`	按钮位置：左侧叠放、右侧叠放或左右分置。	`"both" \| "left" \| "right"`	-
`mode`	Ant `mode`；`spinner` 归一为 `buttonPlacement="both"`。文档只推 `buttonPlacement`。	`"input" \| "spinner"`	-
`clearable`	可清空（Naive）。	`boolean`	-
`clearLabel`	清空按钮可访问名称。	`string`	-
`clearIndicator`	清空指示器节点；UI 层注入图标。	`ReactNode`	-
`onClear`	点击清空时回调。	`(() => void)`	-
`prefix`	前缀节点（Ant / Naive）。	`ReactNode`	-
`suffix`	后缀节点（Ant / Naive）。	`ReactNode`	-
`disabled`	禁用。	`boolean`	-
`readOnly`	只读。	`boolean`	-
`invalid`	语义错误；写入内部 input 的 aria-invalid。	`boolean`	-
`placeholder`	占位符。	`string`	-
`name`	表单字段名；写入隐藏 input 供提交。	`string`	-
`form`	关联 form id。	`string`	-
`updateValueOnInput`	输入过程中合法值是否立刻提交（Naive；默认 true）。	`boolean`	`true`
`changeOnBlur`	失焦时钳制到 min/max 并提交（Ant；默认 true）。	`boolean`	`true`
`validator`	自定义合法校验；返回 false 则拒绝该数值（Naive）。	`((value: number) => boolean)`	-
`onStep`	递增/递减时回调（Ant `onStep` 精简版）。	`((value: number, info: { offset: number; type: "up" \| "down"; emitter: "handler" \| "keydown" \| "wheel"; }) => void)`	-
`inputProps`	内部 input 额外属性（Naive `inputProps`）；不覆盖受管字段。	`Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" \| "onChange" \| "disabled" \| "name" \| "type" \| "value" \| "readOnly">`	-
`rootClassName`	外壳额外类名。	`string`	-
`inputClassName`	传给可见 input 的类名（`className` 仍落在根上以兼容外壳样式）。	`string`	-
`children`	复合子节点；提供时跳过默认 Group/Input/按钮拼装。	`ReactNode`	-

另有 276 项原生属性与事件继承自 HTMLAttributes，原样透传。

InputNumberDecrement

主题化递减。

无自有属性；其余 290 项原生属性继承自 ButtonHTMLAttributes / HTMLAttributes。

InputNumberGroup

主题化分组。

无自有属性；其余 280 项原生属性继承自 HTMLAttributes。

InputNumberIncrement

主题化递增。