Input 输入框 - Semi Design

输入类 · Input

输入框

输入框是最基本的接收用户文本输入的组件

代码演示

如何引入

基本

基本使用

三种大小

默认定义了三种尺寸：大、默认、小

不可用

设定 disabled 属性为 true

前缀/后缀

在输入框上增加前缀、后缀图标，可以是 ReactNode

当 prefix、suffix 传入的内容为文本或者 Semi Icon 时，会自动带上左右间隔，若为自定义 ReactNode，则左右间隔为 0

前置/后置标签

在输入框上增加前置/后置标签

当 addonBefore、addonAfter 传入的内容为文本或者 Semi Icon 时，会自动带上左右间隔，若为自定义 ReactNode，则左右间隔为 0

带移除图标

点击图标删除所有内容

密码模式

隐藏输入的具体内容

校验状态

可设置不同校验状态，展示不同样式

受控组件

Input 值完全取决于传入的 value 值，配合 onChange 回调函数使用

输入框组合

可以将多个输入框放入 InputGroup 的容器中，通过设置 size ，disabled 可统一设置组合中的输入框属性，支持输入框类型包括： Input， InputNumber， Select， AutoComplete、TreeSelect、Cascader、DatePicker

注意事项

InputGroup 不推荐插入非支持元素，Form.InputGroup 会对支持的元素进行错误聚合，而不会自定义元素进行处理。

多行输入框

用于多行输入。通过设置 maxCount 属性可以进行字数限制并显示字数统计。1.30.0 开始支持 showClear。

自动扩展的多行输入框

通过设置 autosize 属性可设置只有高度自动随内容增加而变化。

自定义计算字符串长度

通过设置 getValueLength 属性可以自定义计算字符串长度。搭配 maxLength 和 minLength 可以支持 emoji 长度按照可见长度计算。

传入 getValueLength 时，Semi 内部做了什么：

maxLength：不直接透传 maxLength 给原生 input。如果输入长度超出最大限制，则使用上一次输入的合法长度字符。
minLength：动态切换 minLength 的长度，emoji 按照一个长度计算。
maxCount：使用 getValueLength 获取的值与 maxCount 进行比较

一些问题的回答：

为何不直接引入 grapheme-splitter 包？这个包未压缩体积为 200+kB，对于不需要把 emoji 按照可见长度计算的用户来说，这个体积有点过大了。因此 Semi 选择把长度计算函数作为参数让用户传入。

为何不动态修改 maxLength？动态修改 maxLength 在输入操作完成以后，计算剩余可以输入的字符长度。如 maxLength 设置为 1，想输入一个 length 为 2 的 '💖'，但是由于 input maxLength 的限制，这里根本就输入不进去，也就无法更新 maxLength。

API 参考

Input

其他属性与html input 标签保持一致

属性	说明	类型	默认值
aria-describedby	设置 aria-describedby 属性	string	-
aria-errormessage	设置 aria-errormessage 属性	string	-
aria-invalid	设置 aria-invalid 属性	string	-
aria-label	设置 aria-label 属性	string	-
aria-labelledby	设置 aria-labelledby 属性	string	-
aria-required	设置 aria-required 属性	string	-
addonAfter	后置标签	ReactNode
addonBefore	前置标签	ReactNode
className	类名	string
defaultValue	输入框内容默认值	ReactText
disabled	是否禁用，默认为false	boolean	false
getValueLength	自定义计算字符串长度	(value: string) => number
hideSuffix	清除按钮与后缀标签并存时隐藏后缀标签，默认为false两者并列	boolean	false
mode	输入框的模式，可选值password >=v1.3.0	string
prefix	前缀标签	ReactNode
preventScroll	指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的 focus 方法	boolean
showClear	输入框有内容且 hover 或 focus 时展示清除按钮 >=1.0.0	boolean	false
size	输入框大小，large、default、small	string	'default'
style	样式	CSSProperties
suffix	后缀标签	ReactNode
type	声明input类型，同原生input标签的type属性	string	text
validateStatus	校验状态，可选值default、error、warning，默认default。仅影响展示样式	string	'default'
value	输入框内容	ReactText
onBlur	输入框失去焦点时的回调	function(e:event)
onChange	输入框内容变化时的回调	function(value:string, e:event)
onClear	点击清除按钮时的回调	function(e:event)
onEnterPress	按回车时回调（keypress）	function(e:event)
onFocus	输入框focus时的回调	function(e:event)
onKeyDown	keydown回调	function(e:event)
onKeyPress	keypress回调	function(e:event)
onKeyUp	keyup回调	function(e:event)

TextArea

其他属性与 html textarea 标签保持一致

属性	说明	类型	默认值
aria-describedby	设置 aria-describedby 属性	string	-
aria-errormessage	设置 aria-errormessage 属性	string	-
aria-invalid	设置 aria-invalid 属性	string	-
aria-label	设置 aria-label 属性	string	-
aria-labelledby	设置 aria-labelledby 属性	string	-
aria-required	设置 aria-required 属性	string	-
autosize	是否随着自动适应内容高度	boolean	false
className	类名	string	-
cols	默认列数	number	无
disabled	禁用状态	boolean	false
getValueLength	自定义计算字符串长度	(value: string) => number
maxCount	设置字数限制并显示字数统计	number	无
placeholder	当前的默认值	string	无
readonly	只读	boolean	false
rows	默认行数	number	4
showClear	支持清除 >=1.30.0	boolean	false
style	样式	CSSProperties	-
onBlur	输入框失去焦点时的回调	(e:event) => void	-
onChange	输入框内容变化时的回调	(value:string, e:event) => void
onClear	点击清除按钮时的回调 >=1.30.0	(e:event) => void	-
onEnterPress	按下回车的回调	(e:event) => void	无
onFocus	输入框 focus 时的回调	(e:event) => void	-
onKeyDown	keydown 回调，html 事件	(e:event) => void	-
onKeyPress	keypress 回调，html 事件	(e:event) => void	-
onKeyUp	keyup 回调，html 事件	(e:event) => void	-
onResize	触发高度变化时的回调 >=v0.37.0	({ height:number }) => void	-

InputGroup

通用属性将设置到 InputGroup 的子级元素上，例如 disabled、onFocus 等。如果你在子级设置了 onFocus、onBlur 或 disabled，会覆盖掉 InputGroup 对应属性值。

属性	说明	类型	默认值
className	组的类名	string	-
disabled	禁用	boolean	-
label	InputGroup 的 label 属性	LabelProps	-
labelPosition	label 位置，可选 top 或 left	string	-
size	输入框大小，large、default、small	string	'default'
style	组的样式	CSSProperties	-
onBlur	输入框失去焦点时的回调	(e:event) => void	-
onFocus	输入框 focus 时的回调	(e:event) => void	-

Methods

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

Accessibility

ARIA

当 validateStatus 为 error 时，输入框的 aria-invalid 为 true
在 Form 中使用时，field label 是 Input 的 aria-label

键盘和焦点

Input 可被获取焦点，键盘用户可以使用 Tab 及 Shift + Tab 切换焦点
密码按钮可以被聚焦，聚焦后使用 Enter 或者空格键激活

设计变量

React 组件库 Figma UIKit

主题与DSM

GitHub

京ICP备19058139号-13

浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED