输入框 Input - Ant Design

何时使用

需要用户输入表单域内容时。
提供组合型输入框，带搜索的输入框，还可以进行大小选择。

代码演示

API

通用属性参考：通用属性

Input

参数	说明	类型	默认值	版本
~~addonAfter~~	带标签的 input，设置后置标签，请使用 `Space.Compat` 替换	ReactNode	-
~~addonBefore~~	带标签的 input，设置前置标签，请使用 `Space.Compat` 替换	ReactNode	-
allowClear	可以点击清除图标删除内容	boolean \| { clearIcon: ReactNode }	-
~~bordered~~	是否有边框，请使用 `variant` 替换	boolean	true	4.5.0
classNames	语义化结构 class	Record<SemanticDOM, string>	-	5.4.0
count	字符计数配置	CountConfig	-	5.10.0
defaultValue	输入框默认内容	string	-
disabled	是否禁用状态，默认为 false	boolean	false
id	输入框的 id	string	-
maxLength	最大长度	number	-
prefix	带有前缀图标的 input	ReactNode	-
showCount	是否展示字数	boolean \| { formatter: (info: { value: string, count: number, maxLength?: number }) => ReactNode }	false	4.18.0 info.value: 4.23.0
status	设置校验状态	'error' \| 'warning'	-	4.19.0
styles	语义化结构 style	Record<SemanticDOM, CSSProperties>	-	5.4.0
size	控件大小。注：标准表单内的输入框大小限制为 `middle`	`large` \| `middle` \| `small`	-
suffix	带有后缀图标的 input	ReactNode	-
type	声明 input 类型，同原生 input 标签的 type 属性，见：MDN(请直接使用 `Input.TextArea` 代替 `type="textarea"`)	string	`text`
value	输入框内容	string	-
variant	形态变体	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
onChange	输入框内容变化时的回调	function(e)	-
onPressEnter	按下回车的回调	function(e)	-
onClear	按下清除按钮的回调	() => void	-	5.20.0

如果 Input 在 Form.Item 内，并且 Form.Item 设置了 id 属性，则 value defaultValue 和 id 属性会被自动设置。

Input 的其他属性和 React 自带的 input 一致。

CountConfig

tsx

interface CountConfig {
  // 最大字符数，不同于原生 `maxLength`，超出后标红但不会截断
  max?: number;
  // 自定义字符计数，例如标准 emoji 长度大于 1，可以自定义计数策略将其改为 1
  strategy?: (value: string) => number;
  // 同 `showCount`
  show?: boolean | ((args: { value: string; count: number; maxLength?: number }) => ReactNode);
  // 当字符数超出 `count.max` 时的自定义裁剪逻辑，不配置时不进行裁剪
  exceedFormatter?: (value: string, config: { max: number }) => string;
}

Input.TextArea

同 Input 属性，外加：

参数	说明	类型	默认值	版本
autoSize	自适应内容高度，可设置为 true \| false 或对象：{ minRows: 2, maxRows: 6 }	boolean \| object	false
classNames	语义化结构 class	Record<SemanticDOM, string>	-	5.4.0
styles	语义化结构 style	Record<SemanticDOM, CSSProperties>	-	5.4.0

Input.TextArea 的其他属性和浏览器自带的 textarea 一致。

Input.Search

参数	说明	类型	默认值
enterButton	是否有确认按钮，可设为按钮文字。该属性会与 `addonAfter` 冲突。	ReactNode	false
loading	搜索 loading	boolean	false
onSearch	点击搜索图标、清除图标，或按下回车键时的回调	function(value, event, { source: "input" \| "clear" })	-

其余属性和 Input 一致。

Input.Password

参数	说明	类型	默认值	版本
iconRender	自定义切换按钮	(visible) => ReactNode	(visible) => (visible ? <EyeOutlined /> : <EyeInvisibleOutlined />)	4.3.0
visibilityToggle	是否显示切换按钮或者控制密码显隐	boolean \| VisibilityToggle	true

Input.OTP

5.16.0 新增。

开发者注意事项：
当 mask 属性的类型为 string 时，我们强烈推荐接收单个字符或单个 emoji，如果传入多个字符或多个 emoji，则会在控制台抛出警告。

参数	说明	类型	默认值	版本
defaultValue	默认值	string	-
disabled	是否禁用	boolean	false
formatter	格式化展示，留空字段会被填充	(value: string) => string	-
separator	分隔符，在指定索引的输入框后渲染分隔符	ReactNode \|((i: number) => ReactNode)	-	5.24.0
mask	自定义展示，和 `formatter` 的区别是不会修改原始值	boolean \| string	`false`	`5.17.0`
length	输入元素数量	number	6
status	设置校验状态	'error' \| 'warning'	-
size	输入框大小	`small` \| `middle` \| `large`	`middle`
variant	形态变体	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	`underlined`: 5.24.0
value	输入框内容	string	-
onChange	当输入框内容全部填充时触发回调	(value: string) => void	-
onInput	输入值变化时触发的回调	(value: string[]) => void	-	`5.22.0`

VisibilityToggle

参数	说明	类型	默认值	版本
visible	用于手动控制密码显隐	boolean	false	4.24
onVisibleChange	显隐密码的回调	(visible) => void	-	4.24

Input Methods

名称	说明	参数	版本
blur	取消焦点	-
focus	获取焦点	(option?: { preventScroll?: boolean, cursor?: 'start' \| 'end' \| 'all' })	option - 4.10.0

Semantic DOM

Input

17

input
5.4.0
输入框元素
prefix
5.4.0
前缀的包裹元素
suffix
5.4.0
后缀的包裹元素
count
5.4.0
文字计数元素

Input.TextArea

17 / 100

textarea
5.4.0
输入框元素
count
5.4.0
文字计数元素

主题变量（Design Token）

组件 Token如何定制？

Token 名称	描述	类型	默认值
activeBg	输入框激活状态时背景颜色	string	#ffffff
activeBorderColor	激活态边框色	string	#1677ff
activeShadow	激活态阴影	string	0 0 0 2px rgba(5,145,255,0.1)
addonBg	前/后置标签背景色	string	rgba(0,0,0,0.02)
errorActiveShadow	错误状态时激活态阴影	string	0 0 0 2px rgba(255,38,5,0.06)
hoverBg	输入框hover状态时背景颜色	string	#ffffff
hoverBorderColor	悬浮态边框色	string	#4096ff
inputFontSize	字体大小	number	14
inputFontSizeLG	大号字体大小	number	16
inputFontSizeSM	小号字体大小	number	14
paddingBlock	输入框纵向内边距	number	4
paddingBlockLG	大号输入框纵向内边距	number	7
paddingBlockSM	小号输入框纵向内边距	number	0
paddingInline	输入框横向内边距	number	11
paddingInlineLG	大号输入框横向内边距	number	11
paddingInlineSM	小号输入框横向内边距	number	7
warningActiveShadow	警告状态时激活态阴影	string	0 0 0 2px rgba(255,215,5,0.1)

全局 Token如何定制？

FAQ

为什么我动态改变 `prefix/suffix/showCount` 时，Input 会失去焦点？

当 Input 动态添加或者删除 prefix/suffix/showCount 时，React 会重新创建 DOM 结构而新的 input 是没有焦点的。你可以预设一个空的 <span /> 来保持 DOM 结构不变：

jsx

const suffix = condition ? <Icon type="smile" /> : <span />;

<Input suffix={suffix} />;

为何 TextArea 受控时，`value` 可以超过 `maxLength`？

受控时，组件应该按照受控内容展示。以防止在表单组件内使用时显示值和提交值不同的问题。