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

代码演示

如何引入

基本

基本使用

三种大小

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

不可用

设定 disabled 属性为 true

前缀/后缀

在输入框上增加前缀、后缀图标,可以是 ReactNode
当 prefix、suffix 传入的内容为文本或者 Semi Icon 时,会自动带上左右间隔,若为自定义 ReactNode,则左右间隔为 0

前置/后置标签

在输入框上增加前置/后置标签
当 addonBefore、addonAfter 传入的内容为文本或者 Semi Icon 时,会自动带上左右间隔,若为自定义 ReactNode,则左右间隔为 0

带移除图标

点击图标删除所有内容

密码模式

隐藏输入的具体内容

校验状态

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

受控组件

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

输入框组合

可以将多个输入框放入 InputGroup 的容器中,通过设置 sizedisabled 可统一设置组合中的输入框属性,支持输入框类型包括: InputInputNumberSelectAutoCompleteTreeSelectCascaderDatePicker
注意事项
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
borderless无边框模式 >=2.33.0boolean
className类名string
clearIcon可用于自定义清除按钮, showClear为true时有效 >=2.25.0ReactNode
defaultValue输入框内容默认值ReactText
disabled是否禁用,默认为falsebooleanfalse
getValueLength自定义计算字符串长度(value: string) => number
hideSuffix清除按钮与后缀标签并存时隐藏后缀标签,默认为false两者并列booleanfalse
mode输入框的模式,可选值password >=v1.3.0string
prefix前缀标签ReactNode
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
showClear输入框有内容且 hover 或 focus 时展示清除按钮 >=1.0.0booleanfalse
size输入框大小,large、default、smallstring'default'
style样式CSSProperties
suffix后缀标签ReactNode
type声明input类型,同原生input标签的type属性stringtext
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)
onKeyDownkeydown回调function(e:event)
onKeyPresskeypress回调function(e:event)
onKeyUpkeyup回调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是否随着自动适应内容高度,可写成对象配置最小最大行数{minRows?: number, maxRows?: number}
从2.45.0版本起支持对象参数
boolean|objectfalse
borderless无边框模式 >=2.33.0boolean
className类名string-
cols默认列数number
disabled禁用状态booleanfalse
getValueLength自定义计算字符串长度(value: string) => number
maxCount设置字数限制并显示字数统计number
placeholder当前的默认值string
readonly只读booleanfalse
rows默认行数number4
showClear支持清除 >=1.30.0booleanfalse
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-
onKeyDownkeydown 回调,html 事件(e:event) => void-
onKeyPresskeypress 回调,html 事件(e:event) => void-
onKeyUpkeyup 回调,html 事件(e:event) => void-
onResize触发高度变化时的回调 >=v0.37.0({ height:number }) => void-

InputGroup

通用属性将设置到 InputGroup 的子级元素上,例如 disabled、onFocus 等。如果你在子级设置了 onFocus、onBlur 或 disabled,会覆盖掉 InputGroup 对应属性值。
属性说明类型默认值
className组的类名string-
disabled禁用boolean-
labelInputGroup 的 label 属性LabelProps-
labelPositionlabel 位置,可选 top 或 leftstring-
size输入框大小,large、default、smallstring'default'
style组的样式CSSProperties-
onBlur输入框失去焦点时的回调(e:event) => void-
onFocus输入框 focus 时的回调(e:event) => void-

Methods

绑定在组件实例上的方法,可以通过 ref 调用实现某些特殊交互
名称描述
blur()移出焦点
focus()获取焦点

Accessibility

ARIA

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

键盘和焦点

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

设计变量