InputNumber数字输入框

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

何时使用

当需要获取标准数值时。

代码演示

数字输入框。

TypeScript
JavaScript
import React from 'react';
import { InputNumber } from 'antd';

const onChange = (value: number) => {
  console.log('changed', value);
};

const App: React.FC = () => <InputNumber min={1} max={10} defaultValue={3} onChange={onChange} />;

export default App;

cascader

前置/后置标签

用于配置一些固定组合。

TypeScript
JavaScript
import React from 'react';
import { SettingOutlined } from '@ant-design/icons';
import { Cascader, InputNumber, Select, Space } from 'antd';

const { Option } = Select;

const selectBefore = (
  <Select defaultValue="add" style={{ width: 60 }}>
    <Option value="add">+</Option>
    <Option value="minus">-</Option>
  </Select>
);
const selectAfter = (
  <Select defaultValue="USD" style={{ width: 60 }}>
    <Option value="USD">$</Option>
    <Option value="EUR">€</Option>
    <Option value="GBP">£</Option>
    <Option value="CNY">¥</Option>
  </Select>
);

const App: React.FC = () => (
  <Space direction="vertical">
    <InputNumber addonBefore="+" addonAfter="$" defaultValue={100} />
    <InputNumber addonBefore={selectBefore} addonAfter={selectAfter} defaultValue={100} />
    <InputNumber addonAfter={<SettingOutlined />} defaultValue={100} />
    <InputNumber
      addonBefore={<Cascader placeholder="cascader" style={{ width: 150 }} />}
      defaultValue={100}
    />
  </Space>
);

export default App;

高精度小数

通过 stringMode 开启高精度小数支持，onChange 事件将返回 string 类型。对于旧版浏览器，你需要 BigInt polyfill。

TypeScript
JavaScript
import React from 'react';
import { InputNumber } from 'antd';

const onChange = (value: string) => {
  console.log('changed', value);
};

const App: React.FC = () => (
  <InputNumber<string>
    style={{ width: 200 }}
    defaultValue="1"
    min="0"
    max="10"
    step="0.00000000000001"
    onChange={onChange}
    stringMode
  />
);

export default App;

Toggle keyboard

键盘行为

使用 keyboard 属性可以控制键盘行为。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Checkbox, InputNumber, Space } from 'antd';

const App: React.FC = () => {
  const [keyboard, setKeyboard] = useState(true);

  return (
    <Space>
      <InputNumber min={1} max={10} keyboard={keyboard} defaultValue={3} />
      <Checkbox
        onChange={() => {
          setKeyboard(!keyboard);
        }}
        checked={keyboard}
      >
        Toggle keyboard
      </Checkbox>
    </Space>
  );
};

export default App;

超出边界

当通过受控将 value 超出边界时，提供警告样式。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Button, InputNumber, Space } from 'antd';

const App: React.FC = () => {
  const [value, setValue] = useState<string | number | null>('99');

  return (
    <Space>
      <InputNumber min={1} max={10} value={value} onChange={setValue} />
      <Button
        type="primary"
        onClick={() => {
          setValue(99);
        }}
      >
        Reset
      </Button>
    </Space>
  );
};

export default App;

自定义状态

使用 status 为 InputNumber 添加状态，可选 error 或者 warning。

TypeScript
JavaScript
import React from 'react';
import ClockCircleOutlined from '@ant-design/icons/ClockCircleOutlined';
import { InputNumber, Space } from 'antd';

const App: React.FC = () => (
  <Space direction="vertical" style={{ width: '100%' }}>
    <InputNumber status="error" style={{ width: '100%' }} />
    <InputNumber status="warning" style={{ width: '100%' }} />
    <InputNumber status="error" style={{ width: '100%' }} prefix={<ClockCircleOutlined />} />
    <InputNumber status="warning" style={{ width: '100%' }} prefix={<ClockCircleOutlined />} />
  </Space>
);

export default App;

三种大小

三种大小的数字输入框，当 size 分别为 large 和 small 时，输入框高度为 40px 和 24px ，默认高度为 32px。

TypeScript
JavaScript
import React from 'react';
import { InputNumber, Space } from 'antd';

const onChange = (value: number) => {
  console.log('changed', value);
};

const App: React.FC = () => (
  <Space>
    <InputNumber size="large" min={1} max={100000} defaultValue={3} onChange={onChange} />
    <InputNumber min={1} max={100000} defaultValue={3} onChange={onChange} />
    <InputNumber size="small" min={1} max={100000} defaultValue={3} onChange={onChange} />
  </Space>
);

export default App;

不可用

点击按钮切换可用状态。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Button, InputNumber } from 'antd';

const App: React.FC = () => {
  const [disabled, setDisabled] = useState(true);

  const toggle = () => {
    setDisabled(!disabled);
  };

  return (
    <>
      <InputNumber min={1} max={10} disabled={disabled} defaultValue={3} />
      <div style={{ marginTop: 20 }}>
        <Button onClick={toggle} type="primary">
          Toggle disabled
        </Button>
      </div>
    </>
  );
};

export default App;

格式化展示

通过 formatter 格式化数字，以展示具有具体含义的数据，往往需要配合 parser 一起使用。

这里有一个更复杂的货币格式化输入框：https://codesandbox.io/s/currency-wrapper-antd-input-3ynzo

TypeScript
JavaScript
import React from 'react';
import { InputNumber, Space } from 'antd';

const onChange = (value: number | string) => {
  console.log('changed', value);
};

const App: React.FC = () => (
  <Space>
    <InputNumber
      defaultValue={1000}
      formatter={(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
      parser={(value) => value!.replace(/\$\s?|(,*)/g, '')}
      onChange={onChange}
    />
    <InputNumber
      defaultValue={100}
      min={0}
      max={100}
      formatter={(value) => `${value}%`}
      parser={(value) => value!.replace('%', '')}
      onChange={onChange}
    />
  </Space>
);

export default App;

无边框

没有边框。

TypeScript
JavaScript
import React from 'react';
import { InputNumber } from 'antd';

const App: React.FC = () => <InputNumber min={1} max={10} defaultValue={3} bordered={false} />;

export default App;

￥

前缀

在输入框上添加前缀图标。

TypeScript
JavaScript
import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { InputNumber } from 'antd';

const App: React.FC = () => (
  <>
    <InputNumber prefix="￥" style={{ width: '100%' }} />
    <br />
    <br />
    <InputNumber addonBefore={<UserOutlined />} prefix="￥" style={{ width: '100%' }} />
    <br />
    <br />
    <InputNumber prefix="￥" disabled style={{ width: '100%' }} />
  </>
);

export default App;

API

参数	说明	类型	默认值	版本
addonAfter	带标签的 input，设置后置标签	ReactNode	-	4.17.0
addonBefore	带标签的 input，设置前置标签	ReactNode	-	4.17.0
autoFocus	自动获取焦点	boolean	false	-
bordered	是否有边框	boolean	true	4.12.0
controls	是否显示增减按钮，也可设置自定义箭头图标	boolean \| { upIcon?: React.ReactNode; downIcon?: React.ReactNode; }	-	4.19.0
decimalSeparator	小数点	string	-	-
defaultValue	初始值	number	-	-
disabled	禁用	boolean	false	-
formatter	指定输入框展示值的格式	function(value: number \| string, info: { userTyping: boolean, input: string }): string	-	info: 4.17.0
keyboard	是否启用键盘快捷行为	boolean	true	4.12.0
max	最大值	number	Number.MAX_SAFE_INTEGER	-
min	最小值	number	Number.MIN_SAFE_INTEGER	-
parser	指定从 `formatter` 里转换回数字的方式，和 `formatter` 搭配使用	function(string): number	-	-
precision	数值精度，配置 `formatter` 时会以 `formatter` 为准	number	-	-
readOnly	只读	boolean	false	-
status	设置校验状态	'error' \| 'warning'	-	4.19.0
prefix	带有前缀图标的 input	ReactNode	-	4.17.0
size	输入框大小	`large` \| `middle` \| `small`	-	-
step	每次改变步数，可以为小数	number \| string	1	-
stringMode	字符值模式，开启后支持高精度小数。同时 `onChange` 将返回 string 类型	boolean	false	4.13.0
value	当前值	number	-	-
onChange	变化回调	function(value: number \| string \| null)	-	-
onPressEnter	按下回车的回调	function(e)	-	-
onStep	点击上下箭头的回调	(value: number, info: { offset: number, type: 'up' \| 'down' }) => void	-	4.7.0

方法

名称	描述
blur()	移除焦点
focus()	获取焦点

Design Token

Global Token

Token 名称	描述	类型	默认值
colorBgContainer	组件的容器背景色，例如：默认按钮、输入框等。务必不要将其与 `colorBgElevated` 混淆。	string	#ffffff
colorBgContainerDisabled	控制容器在禁用状态下的背景色。	string	rgba(0, 0, 0, 0.04)
colorBorder	默认使用的边框颜色, 用于分割不同的元素，例如：表单的分割线、卡片的分割线等。	string	#d9d9d9
colorError	用于表示操作失败的 Token 序列，如失败按钮、错误状态提示（Result）组件等。	string	#ff4d4f
colorErrorBorderHover	错误色的描边色悬浮态	string	#ffa39e
colorErrorOutline	控制输入组件错误状态下的外轮廓线颜色。	string	rgba(255, 38, 5, 0.06)
colorFillAlter	控制元素替代背景色。	string	rgba(0, 0, 0, 0.02)
colorPrimary	品牌色是体现产品特性和传播理念最直观的视觉元素之一。在你完成品牌主色的选取之后，我们会自动帮你生成一套完整的色板，并赋予它们有效的设计语义	string	#1677ff
colorPrimaryHover	主色梯度下的悬浮态。	string	#4096ff
colorText	最深的文本色。为了符合W3C标准，默认的文本颜色使用了该色，同时这个颜色也是最深的中性色。	string	rgba(0, 0, 0, 0.88)
colorTextDescription	控制文本描述字体颜色。	string	rgba(0, 0, 0, 0.45)
colorTextDisabled	控制禁用状态下的字体颜色。	string	rgba(0, 0, 0, 0.25)
colorTextPlaceholder	控制占位文本的颜色。	string	rgba(0, 0, 0, 0.25)
colorWarning	用于表示操作警告的 Token 序列，如 Notification、 Alert等警告类组件或 Input 输入类等组件会使用该组梯度变量。	string	#faad14
colorWarningBorderHover	警戒色的描边色悬浮态	string	#ffd666
colorWarningOutline	控制输入组件警告状态下的外轮廓线颜色。	string	rgba(255, 215, 5, 0.1)
borderRadius	基础组件的圆角大小，例如按钮、输入框、卡片等	number	6
borderRadiusLG	LG号圆角，用于组件中的一些大圆角，如 Card、Modal 等一些组件样式。	number	8
borderRadiusSM	SM号圆角，用于组件小尺寸下的圆角，如 Button、Input、Select 等输入类控件在 small size 下的圆角	number	4
controlHeight	Ant Design 中按钮和输入框等基础控件的高度	number	32
controlHeightLG	较高的组件高度	number	40
controlHeightSM	较小的组件高度	number	24
controlOutline	控制输入组件的外轮廓线颜色。	string	rgba(5, 145, 255, 0.1)
controlOutlineWidth	控制输入组件的外轮廓线宽度。	number	2
controlPaddingHorizontal	控制元素水平内间距。	number	12
controlPaddingHorizontalSM	控制元素中小尺寸水平内间距。	number	8
fontFamily	Ant Design 的字体家族中优先使用系统默认的界面字体，同时提供了一套利于屏显的备用字体库，来维护在不同平台以及浏览器的显示下，字体始终保持良好的易读性和可读性，体现了友好、稳定和专业的特性。	string	-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'
fontSize	设计系统中使用最广泛的字体大小，文本梯度也将基于该字号进行派生。	number	14
fontSizeLG	大号字体大小	number	16
lineHeight	文本行高	number	1.5714285714285714
lineHeightLG	大型文本行高	number	1.5
lineType	用于控制组件边框、分割线等的样式，默认是实线	string	solid
lineWidth	用于控制组件边框、分割线等的宽度	number	1
motionDurationMid	动效播放速度，中速。用于中型元素动画交互	string	0.2s
motionDurationSlow	动效播放速度，慢速。用于大型元素如面板动画交互	string	0.3s
paddingSM	控制元素的小内间距。	number	12
paddingXS	控制元素的特小内间距。	number	8
paddingXXS	控制元素的极小内间距。	number	4

FAQ

为何受控模式下，`value` 可以超出 `min` 和 `max` 范围？

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

为何动态修改 `min` 和 `max` 让 `value` 超出范围不会触发 `onChange` 事件？

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

InputNumber数字输入框

InputNumber数字输入框

何时使用

代码演示

API

方法

Design Token

Global Token

FAQ

为何受控模式下，value 可以超出 min 和 max 范围？

为何动态修改 min 和 max 让 value 超出范围不会触发 onChange 事件？

何时使用

代码演示

API

方法

Design Token

Global Token

FAQ

为何受控模式下，value 可以超出 min 和 max 范围？

为何动态修改 min 和 max 让 value 超出范围不会触发 onChange 事件？

为何受控模式下，`value` 可以超出 `min` 和 `max` 范围？

为何动态修改 `min` 和 `max` 让 `value` 超出范围不会触发 `onChange` 事件？

为何受控模式下，`value` 可以超出 `min` 和 `max` 范围？

为何动态修改 `min` 和 `max` 让 `value` 超出范围不会触发 `onChange` 事件？