NumberInput

输入受约束的数值。中文惯用名：数字输入框。设计文档原名：InputNumber。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.number-input`
名称	NumberInput
二级分类	数据录入（`data-entry`）
用途	输入受约束的数值
描述	中文惯用名：数字输入框。设计文档原名：InputNumber。

预览

静态结构：NumberInput 的控件为包裹节点 data-slot="number-input"（relative block），内嵌原生 number input（隐藏浏览器原生步进箭头）+ 右侧绝对定位的竖排双按钮列（上 / 下 Chevron 图标，按 step 增减并以 min / max 钳制；到达边界或 disabled 时对应按钮禁用）。输入过程保留中间文本（如 "-" / "1."），可解析时传出钳制 + precision 规整后的 number，清空传出 undefined。Form 内声明非空 name 时经 FieldShell 包裹（label + 校验错误行）。

DSL 结构

DslNode

{
  "type": "NumberInput",
  "props": {
    "name": "quantity",
    "label": "数量",
    "value": 2,
    "min": 0,
    "max": 10,
    "step": 1
  }
}

何时用

何时使用

采集数值：数量、件数、天数、百分比等需要范围与步进约束的字段。
需要钳制边界（min / max）或小数精度（precision 四舍五入）的输入。
需要步进微调的数值（右侧上 / 下按钮，步距由 step 决定）。

何时不用

大范围连续取值、强调「比例感」的调参：使用 Slider，NumberInput 侧重精确录入。
金额等需要千分位、货币符号与专用格式化的场景：使用业务侧金额组件或格式化展示（Statistic）。
编号、手机号等「数字形态的标识」：使用 Input，它们不做数值运算。

变体

变体	视觉形态	适用场景
默认	描边数字输入框 + 右侧上 / 下步进按钮	常规数值录入
min / max 钳制	越界输入被钳制，边界处对应按钮禁用	有明确取值范围的字段（如 0-100 分）
step 自定义步距	步进按钮按 step 增减	成组变化的数值（如 5 的倍数、0.1 步进）
precision 精度	输入值按精度四舍五入后提交	小数位数固定的金额 / 比率
Form 表单项	FieldShell：label + 控件 + 校验错误行	表单内数值字段（声明 name 自动注册）
disabled 禁用	输入与步进按钮均禁用	只读回显、流程未就绪

API 属性

属性	类型	默认值	说明
`name`	`string`	—	字段名；在 Form 内声明即自动成为表单项
`label`	`string`	—	表单项标签（FieldShell 呈现）
`rules`	`FieldRule[]`	—	校验规则
`value`	`number`	—	受控值（独立渲染时生效）；Form 内作为字段初始值（优先于 Form initialValues）
`min`	`number`	—	最小值（输入越界时钳制）
`max`	`number`	—	最大值（输入越界时钳制）
`step`	`number`	1	步长（步进按钮步距，同时透传原生 input step）
`precision`	`number`	—	小数精度位数；声明后输入值按此精度四舍五入
`placeholder`	`string`	—	空态提示文案
`disabled`	`boolean`	false	禁用输入与步进按钮
`onChange`	`(value: number	undefined) => void`	—
`controlClassName`	`string`	—	控件本体（input）class（无论是否在 Form 内都挂 input 节点）
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为控件包裹节点）

使用规范

有明确取值范围的字段一定给 min / max：钳制发生在输入与步进两条路径上，避免越界值进入表单。
precision 同时作用于手输与步进结果；金额场景固定 2 位，避免浮点尾数落入表单 values。
onChange 可能传出 undefined（用户清空）；下游取值需处理空值，不要直接参与算术。
值始终是 number 类型（非字符串），表单校验与提交均按数值语义处理。
强调比例、连续调参（如音量、透明度）时改用 Slider；NumberInput 适合精确录入。

正例

✓ 购买数量：min={1} max={10} step={1}，步进按钮在边界处自动禁用。
✓ 折扣率：precision={2} + min={0} max={1}，输入 0.1234 提交为 0.12。
✓ Form 内「工时」：name + rules 必填，onChange 传出 number 直接参与后端计算。

反例

✕ 用 NumberInput 采集手机号、订单编号等标识（应使用 Input，它们不参与数值运算）。
✕ 不给 min / max 就交给后端兜底，用户可提交负数或超大值。
✕ 把 onChange 传出的 undefined 当作 0 使用，清空与「填了 0」语义混淆。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。