输入类 · TagInput
标签输入框
标签输入框能够将输入的内容生成标签。

代码演示

如何引入

基本演示

敲击回车键后,输入内容将成为标签。标签内容如果为空串或者纯空格时,则会被过滤。

批量添加

可以使用 separator 设置分隔符,来实现批量输入,它的默认值为英文逗号。1.29.0 版本后支持多个分隔符以 string[] 格式传入。

批量删除

可使用 showClear 设置是否支持一键删除所有标签和输入框内容。

禁用

尺寸大小

通过 size 控制标签输入框的大小尺寸,可选: smalldefaultlarge

不同校验状态样式

可以使用 validateStatus 设置不同校验状态的样式,它仅影响背景颜色等样式表现,可选值: defaultwarningerror

前缀 / 后缀

可以通过 prefix 传入输入框前缀,通过 suffix 传入输入框后缀,可以为文本或者 ReactNode。
prefixsuffix 传入的内容为 string 或者 Icon 时,会自动带上左右间隔;若为自定义 ReactNode,则左右间隔为 0,如需可以在你传入的 ReactNode中自行设置。

失焦后自动创建标签

可使用 addOnBlur,设置是否在 blur 事件触发时,将当前 input 的值自动创建成 tag。

过滤重复标签

可使用 allowDuplicates,设置是否允许创建相同 tag,默认为 true。

输入限制

可使用 max 限制输入的标签数量,超出后将不允许再输入,并且触发 onExceed() 回调。
可使用 maxLength 限制单个标签的最大长度,超出后将不允许再输入,并且触发 onInputExceed() 回调。

限制标签展示数量

利用 maxTagCount 可以限制展示的标签数量,超出部分将以 +N 的方式展示。使用 showRestTagsPopover 可以设置在超出 maxTagCount 后,hover +N 是否显示 Popover,并且可以在 restTagsPopoverProps 属性中配置 Popover

标签受控

可使用 value 设置标签内容,并配合 onChange 实现标签内容受控。

输入受控

可使用 inputValue 设置输入框内容,并配合 onInputChange 实现输入内容受控。

回调

焦点管理

可以使用 blur()focus() 方法对焦点进行管理。

自定义标签渲染

可以使用 renderTagItem 自定义标签渲染。 renderTagItem(value: string, index: number, onClose: function ) => React.ReactNode 第三个参数 onClose 于 2.23.0 版本开始提供。

拖拽排序

draggable设为 true,开启拖拽排序功能。v2.17.0 后支持。拖拽排序下不允许添加相同 Tag, 因此需要将 allowDuplicates 设置为 false。 拖拽功能开启后,点击 TagInput,Tag 可拖拽。点击 TagInput 外任意区域,Tag 不可拖拽。

API 参考

属性说明类型默认值版本
addOnBlur是否在 blur 事件触发时,将当前 input 的值自动创建成 tagbooleanfalse1.20.0
allowDuplicates是否允许添加相同 tagbooleantrue1.20.0
autoFocus初始渲染时是否自动 focusbooleanfalse1.29.0
className样式类名string-1.19.0
defaultValue初始标签string[]-1.19.0
disabled是否禁用booleanfalse1.19.0
inputValue当前输入框,配合 onInputChange 实现受控string-1.19.0
maxLength单个标签的最大长度number-1.19.0
max允许标签的最大数量number-1.21.0
maxTagCount标签的最大展示数量,超出后将以 +N 形式展示number-1.21.0
showRestTagsPopover当超过 maxTagCount,hover 到 +N 时,是否通过 Popover 显示剩余内容booleantrue1.21.0
restTagsPopoverPropsPopover 的配置属性,可以控制弹出方向、zIndex、trigger等,具体参考PopoverPopoverProps{}1.21.0
showContentTooltip当标签长度过长发生截断时,hover 标签的时候,是否通过 Tooltip 显示全部内容, 支持 Tooltip|Popover;opts,其他需要透传给浮层组件的属性boolean|{type: 'tooltip'|'popover', opts: object}true1.21.0
placeholder占位默认值string-1.19.0
prefix前缀标签ReactNode-1.19.0
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
renderTagItem自定义标签渲染, 参数 onClose 于版本2.23.0版本提供
(params) => React.ReactNode
-1.19.0
separator设置批量输入时的分隔符string|string[],1.19.0, string[]是从1.29.0开始支持
showClear是否支持一键删除所有标签和输入内容booleanfalse1.19.0
size设置输入框尺寸,可选: smalllargedefaultstringdefault1.19.0
style内联样式React.CSSProperties-1.19.0
suffix后缀标签ReactNode-1.19.0
validateStatus设置校验状态样式,可选: defaultwarningerrorstringdefault1.19.0
value当前标签,配合 onChange 实现受控string[] | undefined-1.19.0
draggable设置是否可拖拽booleanfalse2.17.0
expandRestTagsOnClick在不可拖拽的情况下,在 TagInput 被点击后是否展开多余的 Tagbooleantrue2.17.0
onAdd添加标签时的回调(addedValue: string[]) => void-1.19.0
onBlur输入框失去焦点时的回调(e:React.MouseEvent) => void-1.19.0
onChange标签变化时的回调(value:string[]) => void-1.19.0
onExceed超过 max 时的回调(value:string[]) => void-1.19.0
onFocus输入框获取焦点时的回调(e:React.MouseEvent) => void-1.19.0
onInputChange输入框内容变化时的回调(value:string,e: React.KeyboardEvent) => void)-1.19.0
onInputExceed超过 maxLength 时的回调(value:string) => void-1.19.0
onKeyDownkeydown 回调(e: React.KeyboardEvent) => void-2.1.0
onRemove移除标签时的回调(removedValue: string, idx: number) => void-1.19.0

Methods

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

Accessibility

ARIA

  • TagInput 支持传入 aria-label 来表示该 TagInput 作用;
  • TagInput 会依据 disabled 及 validateStatus props 来分别设置 aria-disabledaria-invalid
  • TagInput 的输入框和清空按钮均具有 aria-label 来表明元素作用。

设计变量