# 数字输入框

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/input-number
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

通过鼠标或键盘，输入范围内的数值。


## 何时使用 {#when-to-use}

当需要获取标准数值时。

## 代码演示 {#examples}


- 基本 · `basic`
- 三种大小 · `size`

- 不可用 · `disabled`
- 高精度小数 · `digit`
- 格式化展示 · `formatter`
- 键盘行为 · `keyboard`
- 鼠标滚轮 · `change-on-wheel`
- 形态变体 · `variant`
- 拨轮 · `spinner`



- 超出边界 · `out-of-range`
- 前缀/后缀 · `presuffix`
- 自定义状态 · `status`
- 聚焦 · `focus`
- 自定义语义结构的样式和类 · `style-class`




## API

通用属性参考：[通用属性](#jguang-common-props)

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| ~~addonAfter~~ | 带标签的 input，设置后置标签，请使用 Space.Compact 替换 | ReactNode | - | 4.17.0 | × |
| ~~addonBefore~~ | 带标签的 input，设置前置标签，请使用 Space.Compact 替换 | ReactNode | - | 4.17.0 | × |
| changeOnBlur | 是否在失去焦点时，触发 `onChange` 事件（例如值超出范围时，重新限制回范围并触发事件） | boolean | true | 5.11.0 | × |
| changeOnWheel | 允许鼠标滚轮改变数值 | boolean | - | 5.14.0 | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - | 6.0.0 | 6.0.0 |
| controls | 是否显示增减按钮，也可设置自定义箭头图标 | boolean \| { upIcon?: React.ReactNode; downIcon?: React.ReactNode; } | - |  | × |
| decimalSeparator | 小数点 | string | - | - | × |
| placeholder | 占位符 | string | - |  | × |
| defaultValue | 初始值 | number | - | - | × |
| disabled | 禁用 | boolean | false | - | × |
| formatter | 指定输入框展示值的格式 | function(value: number \| string, info: { userTyping: boolean, input: string }): string | - |  | × |
| keyboard | 是否启用键盘快捷行为 | boolean | true |  | × |
| max | 最大值 | number | [Number.MAX_SAFE_INTEGER](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) | - | × |
| min | 最小值 | number | [Number.MIN_SAFE_INTEGER](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER) | - | × |
| parser | 指定从 `formatter` 里转换回数字的方式，和 `formatter` 搭配使用 | function(string): number | - | - | × |
| precision | 数值精度，配置 `formatter` 时会以 `formatter` 为准 | number | - | - | × |
| readOnly | 只读 | boolean | false | - | × |
| status | 设置校验状态 | 'error' \| 'warning' | - |  | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 6.0.0 | 6.0.0 |
| prefix | 带有前缀图标的 input | ReactNode | - |  | × |
| suffix | 带有后缀图标的 input | ReactNode | - | 5.20.0 | × |
| size | 输入框大小 | `large` \| `medium` \| `small` | - | - | × |
| step | 每次改变步数，可以为小数 | number \| string | 1 | - | × |
| stringMode | 字符值模式，开启后支持高精度小数。同时 `onChange` 将返回 string 类型 | boolean | false | 4.13.0 | × |
| mode | 展示输入框或拨轮 | `'input' \| 'spinner'` | `'input'` |  | × |
| value | 当前值 | number | - | - | × |
| variant | 形态变体 | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | 5.19.0 |
| onChange | 变化回调 | function(value: number \| string \| null) | - | - | × |
| onPressEnter | 按下回车的回调 | function(e) | - | - | × |
| onStep | 点击上下箭头、键盘、滚轮的回调 | (value: number, info: { offset: number, type: 'up' \| 'down', emitter: 'handler' \| 'keydown' \| 'wheel' }) => void | - | - | × |
| ~~bordered~~ | 是否带边框，请使用 `variant` 替代 | boolean | true | - | × |

## Ref

| 名称 | 说明 | 参数 | 版本 |
| --- | --- | --- | --- |
| blur() | 移除焦点 | - |  |
| focus() | 获取焦点 | (option?: { preventScroll?: boolean, cursor?: 'start' \| 'end' \| 'all' }) | cursor - 5.22.0 |
| nativeElement | 获取原生 DOM 元素 | - | 5.17.3 |

## Semantic DOM

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，设置行内块布局、宽度、边框圆角和重置样式 | — |
| `prefix` | 前缀的包裹元素，设置flex布局、对齐方式和右边距样式 | — |
| `input` | 输入框元素，设置字体、行高、文本输入和交互样式 | — |
| `suffix` | 后缀的包裹元素，设置flex布局、边距和过渡动画样式 | — |
| `actions` | 操作元素，设置绝对定位、宽度、flex布局和数值调节按钮样式 | — |
| `action` | 单个操作按钮元素，设置按钮的样式、悬浮效果和点击交互 | — |

语义说明来源: `vendor/components/input-number/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `controlWidth` | `number` | 输入框宽度 |
| `handleWidth` | `number` | 操作按钮宽度 |
| `handleFontSize` | `number` | 操作按钮图标大小 |
| `handleVisible` | `'auto' \| true` | 操作按钮可见性 |
| `handleBg` | `string` | 操作按钮背景色 |
| `handleActiveBg` | `string` | 操作按钮激活背景色 |
| `handleHoverColor` | `string` | 操作按钮悬浮颜色 |
| `handleBorderColor` | `string` | 操作按钮边框颜色 |
| `filledHandleBg` | `string` | 面性变体操作按钮背景色 |
| `handleOpacity` | `number` | 见原生声明及继承类型 |
| `handleVisibleWidth` | `number` | 见原生声明及继承类型 |

声明来源: `vendor/components/input-number/style/token.ts`

```ts
import { FastColor } from '@ant-design/fast-color';

import type { SharedComponentToken, SharedInputToken } from '../../input/style/token';

import { initComponentToken } from '../../input/style/token';

import type { FullToken, GetDefaultToken } from '../../theme/internal';

export interface ComponentToken extends SharedComponentToken {
  /**
   * @desc 输入框宽度
   * @descEN Width of input
   */
  controlWidth: number;
  /**
   * @desc 操作按钮宽度
   * @descEN Width of control button
   */
  handleWidth: number;
  /**
   * @desc 操作按钮图标大小
   * @descEN Icon size of control button
   */
  handleFontSize: number;
  /**
   * Default `auto`. Set `true` will always show the handle
   * @desc 操作按钮可见性
   * @descEN Handle visible
   */
  handleVisible: 'auto' | true;
  /**
   * @desc 操作按钮背景色
   * @descEN Background color of handle
   */
  handleBg: string;
  /**
   * @desc 操作按钮激活背景色
   * @descEN Active background color of handle
   */
  handleActiveBg: string;
  /**
   * @desc 操作按钮悬浮颜色
   * @descEN Hover color of handle
   */
  handleHoverColor: string;
  /**
   * @desc 操作按钮边框颜色
   * @descEN Border color of handle
   */
  handleBorderColor: string;
  /**
   * @desc 面性变体操作按钮背景色
   * @descEN Background color of handle in filled variant
   */
  filledHandleBg: string;
  /**
   * @internal
   */
  handleOpacity: number;
  /**
   * @internal
   */
  handleVisibleWidth: number;
}

export type InputNumberToken = FullToken<'InputNumber'> & SharedInputToken;
```

## 注意事项 {#notes}

根据相关问题 [#21158](https://github.com/ant-design/ant-design/issues/21158)、[#17344](https://github.com/ant-design/ant-design/issues/17344)、[#9421](https://github.com/ant-design/ant-design/issues/9421) 以及 [关于 number 输入框的文档](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input/number)，社区似乎不支持在 `<Input />` 属性中原生包含 `type="number"`，因此请根据需要自行添加，并注意强烈建议使用服务端验证，因为客户端验证可能被高级用户修改。

## FAQ

### 为何受控模式下，`value` 可以超出 `min` 和 `max` 范围？ {#faq-controlled-range}

在受控模式下，开发者可能自行存储相关数据。如果组件将数据约束回范围内，会导致展示数据与实际存储数据不一致的情况。这使得一些如表单场景存在潜在的数据问题。

### 为何动态修改 `min` 和 `max` 让 `value` 超出范围不会触发 `onChange` 事件？ {#faq-dynamic-range-change}

`onChange` 事件为用户触发事件，自行触发会导致表单库误以为变更来自用户操作。我们以错误样式展示超出范围的数值。

### 为何 `onBlur` 等事件获取不到正确的 value？ {#faq-onblur-value}

InputNumber 的值由内部逻辑封装而成，通过 `onBlur` 等事件获取的 `event.target.value` 仅为 DOM 元素的 `value` 而非 InputNumber 的实际值。例如通过 `formatter` 或者 `decimalSeparator` 更改展示格式，DOM 中得到的就是格式化后的字符串。你总是应该通过 `onChange` 获取当前值。

### 为何 `changeOnWheel` 无法控制鼠标滚轮是否改变数值？ {#faq-change-on-wheel}

> 不建议使用 `type` 属性

InputNumber 组件允许你使用 input 元素的所有属性最终透传至 input 元素，当你传入 `type="number"` 时 input 元素也会添加这个属性，这会使 input 元素触发原生特性（允许鼠标滚轮改变数值），从而导致 `changeOnWheel` 无法控制鼠标滚轮是否改变数值。


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/input-number/index.tsx`
- `vendor/components/input-number/style/token.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt