数字输入框
概述
用于输入数值的输入框组件，支持步进按钮、键盘交互与 min/max 边界控制。适用于数量、价格、年龄等必须是数字且处于一定范围的场景。通用文本请使用 SInput。
用法
特性
- 📏 6 种尺寸：xs、sm、md、lg、xl、2xl
- 🎚 步进按钮，支持按住加速（400ms → 60ms 循环）
- ⌨️ 完整键盘支持——方向键、Page Up/Down、Home/End、Enter、滚轮
- ⚖️
min/max钳制（边界处按钮禁用）、step、formatOptions精度 - 🌐 基于
Intl.NumberFormat的本地化数字格式 - 🧹 可清除模式，清除按钮带 i18n
aria-label - 📋 设置
name时通过代理隐藏输入框支持原生表单提交 - ♿ 完整无障碍支持——
aria-valuemin/max/now、清除按钮命名、axe 零违规
演示
基础
100%
插槽
100%
API
Aria 层
7InputNumber
34 属性2 事件5 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于根元素的额外类名。 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<InputNumberUi> | — | 该组件的按槽类重写。 |
center | boolean | false | 是否将输入内容居中对齐。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
controlProps | InputNumberControlProps | — | 转发给控件的属性。 |
incrementProps | InputNumberIncrementProps | — | 转发给 increment 元素的属性。 |
decrementProps | InputNumberDecrementProps | — | 转发给递减元素的属性。 |
clearProps | ButtonProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | number | — | 输入的默认值 |
modelValue | number | null | — | 输入的受控值 |
min | number | — | 输入允许的最小值。 |
max | number | — | 输入允许的最大值。 |
step | number | — | 输入值在每次增量或减量“ tick”时的变化量。 |
stepSnapping | boolean | — | 当值为 `false` 时，防止该值对齐到步长值的最近增量 |
focusOnChange | boolean | — | 当值为 `true` 时，值发生变化时将聚焦于输入框。 |
formatOptions | NumberFormatOptions | — | 数字字段中显示值的格式化选项。这也会影响允许
用户输入的字符。 |
locale | string | — | 用于日期格式的语言环境 |
disableWheelChange | boolean | — | 当值为 `true` 时，防止该值在滚轮滚动时发生变化。 |
invertWheelChange | boolean | — | 当值为 `true` 时，反转车轮的旋转方向。 |
rootProps | BaseProps | — | 转发至根元素的属性。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | number | null | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | InputNumberCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | InputNumberCompactSlotProps | 尾部槽位的自定义内容。 |
clear | InputNumberCompactSlotProps | 为“clear”槽位定制内容。 |
decrement | InputNumberCompactSlotProps | 针对 decrement 插槽的自定义内容。 |
increment | InputNumberCompactSlotProps | 增量槽位的自定义内容。 |
InputNumberClear
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
clear | PointerEvent | 点击“清除”按钮时触发。 |
InputNumberCompact
30 属性2 事件5 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
clearable | boolean | false | 是否显示“清除”按钮。 |
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
controlProps | InputNumberControlProps | — | 转发给控件的属性。 |
incrementProps | InputNumberIncrementProps | — | 转发给 increment 元素的属性。 |
decrementProps | InputNumberDecrementProps | — | 转发给递减元素的属性。 |
clearProps | ButtonProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | number | — | 输入的默认值 |
modelValue | number | null | — | 输入的受控值 |
min | number | — | 输入允许的最小值。 |
max | number | — | 输入允许的最大值。 |
step | number | — | 输入值在每次增量或减量“ tick”时的变化量。 |
stepSnapping | boolean | — | 当值为 `false` 时，防止该值对齐到步长值的最近增量 |
focusOnChange | boolean | — | 当值为 `true` 时，值发生变化时将聚焦于输入框。 |
formatOptions | NumberFormatOptions | — | 数字字段中显示值的格式化选项。这也会影响允许
用户输入的字符。 |
locale | string | — | 用于日期格式的语言环境 |
disableWheelChange | boolean | — | 当值为 `true` 时，防止该值在滚轮滚动时发生变化。 |
invertWheelChange | boolean | — | 当值为 `true` 时，反转车轮的旋转方向。 |
rootProps | BaseProps | — | 转发至根元素的属性。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | number | null | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | InputNumberCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | InputNumberCompactSlotProps | 尾部槽位的自定义内容。 |
clear | InputNumberCompactSlotProps | 为“clear”槽位定制内容。 |
decrement | InputNumberCompactSlotProps | 针对 decrement 插槽的自定义内容。 |
increment | InputNumberCompactSlotProps | 增量槽位的自定义内容。 |
InputNumberControl
InputNumberDecrement
4 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
InputNumberIncrement
4 属性
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
InputNumberRoot
24 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
defaultValue | number | — | 输入的默认值 |
modelValue | number | null | — | 输入的受控值 |
min | number | — | 输入允许的最小值。 |
max | number | — | 输入允许的最大值。 |
step | number | — | 输入值在每次增量或减量“ tick”时的变化量。 |
stepSnapping | boolean | — | 当值为 `false` 时，防止该值对齐到步长值的最近增量 |
focusOnChange | boolean | — | 当值为 `true` 时，值发生变化时将聚焦于输入框。 |
formatOptions | NumberFormatOptions | — | 数字字段中显示值的格式化选项。这也会影响允许
用户输入的字符。 |
locale | string | — | 用于日期格式的语言环境 |
disableWheelChange | boolean | — | 当值为 `true` 时，防止该值在滚轮滚动时发生变化。 |
invertWheelChange | boolean | — | 当值为 `true` 时，反转车轮的旋转方向。 |
rootProps | BaseProps | — | 转发至根元素的属性。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | number | null | 当模型值发生变化时触发。 |
注意事项
架构与对标差异
VeanUI 将数字输入框拆分为负责状态、数字解析/格式化、边界逻辑与表单代理的 Aria 层（@vean/aria/input-number），以及负责变体与 UnoCSS 样式的 styled 层（@vean/ui）。Aria InputNumberCompact 组合 InputNumberRoot / InputNumberControl / InputNumberIncrement / InputNumberDecrement / InputNumberClear 并暴露 increment / decrement / clear 插槽。这与 Aria/styled 分离一致，区别于 Ant Design、Element Plus、Mantine 等单包方案。
| 能力 | VeanUI | Ant Design InputNumber | Element Plus input-number | Mantine NumberInput |
|---|---|---|---|---|
| Aria/styled 分离 | ✅ | — | — | — |
| 受控/非受控 | ✅ | ✅ | ✅ | ✅ |
| step / min / max / 精度 | ✅ | ✅ | ✅ | ✅ |
| 键盘 Arrow/Page/Home/End | ✅ | ✅ | ✅ | ✅ |
| 按住触发加速 | ✅ | ✅ | — | — |
| 边界按钮禁用 | ✅ | — | ✅ | — |
| 清除按钮（i18n 标签） | ✅ | — | ✅ | — |
| 本地化数字格式（Intl） | ✅ | — | — | — |
| 尺寸变体（xs…2xl） | ✅ | — | — | ✅ |
center 布局 | ✅ | ✅ | ✅ | — |
注意事项
formatter/parser钩子、controls显隐开关与compact模式未实现，列为增强待办。- 输入过程中组件接受中间状态，失焦或按 Enter 时会回弹为合法数字。
- 清除按钮仅在悬停或聚焦时出现（桌面惯例）。
常见问题
如何限制数值范围？
传入 min 和 max。值在变化时会被钳制，且步进按钮在边界处自动禁用。
如何控制小数位数？
通过 formatOptions.maximumFractionDigits 控制显示与解析的小数位数（如 { maximumFractionDigits: 2 }）。格式化与步进计算都会遵循配置的精度。
键盘如何操作？
方向键上/下按 step 步进；Page Up/Down 按 step * 10 步进；Home/End 跳到 min / max；Enter 提交；悬停时滚轮可调整数值。
如何本地化显示的数字？
组件使用 Intl.NumberFormat 结合当前 locale（以及可选的 formatOptions）。千分位与小数点符号随 locale 自动适配。