输入类 · TagInput
标签输入框
标签输入框能够将输入的内容生成标签。
代码演示
如何引入
基本演示
敲击回车键后,输入内容将成为标签。标签内容如果为空串或者纯空格时,则会被过滤。
批量添加
可以使用
separator 设置分隔符,来实现批量输入,它的默认值为英文逗号。1.29.0 版本后支持多个分隔符以 string[] 格式传入。批量删除
可使用
showClear 设置是否支持一键删除所有标签和输入框内容。禁用
尺寸大小
通过
size 控制标签输入框的大小尺寸,可选: small 、 default 、 large。不同校验状态样式
可以使用
validateStatus 设置不同校验状态的样式,它仅影响背景颜色等样式表现,可选值: default 、 warning 、 error。前缀 / 后缀
可以通过
当
prefix 传入输入框前缀,通过 suffix 传入输入框后缀,可以为文本或者 ReactNode。当
prefix、suffix 传入的内容为 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 的值自动创建成 tag | boolean | false | 1.20.0 |
| allowDuplicates | 是否允许添加相同 tag | boolean | true | 1.20.0 |
| autoFocus | 初始渲染时是否自动 focus | boolean | false | 1.29.0 |
| className | 样式类名 | string | - | 1.19.0 |
| defaultValue | 初始标签 | string[] | - | 1.19.0 |
| disabled | 是否禁用 | boolean | false | 1.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 显示剩余内容 | boolean | true | 1.21.0 |
| restTagsPopoverProps | Popover 的配置属性,可以控制弹出方向、zIndex、trigger等,具体参考Popover | PopoverProps | {} | 1.21.0 |
| showContentTooltip | 当标签长度过长发生截断时,hover 标签的时候,是否通过 Tooltip 显示全部内容, 支持 Tooltip|Popover;opts,其他需要透传给浮层组件的属性 | boolean|{type: 'tooltip'|'popover', opts: object} | true | 1.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 | 是否支持一键删除所有标签和输入内容 | boolean | false | 1.19.0 |
| size | 设置输入框尺寸,可选: small、large、default | string | default | 1.19.0 |
| style | 内联样式 | React.CSSProperties | - | 1.19.0 |
| suffix | 后缀标签 | ReactNode | - | 1.19.0 |
| validateStatus | 设置校验状态样式,可选: default、warning、error | string | default | 1.19.0 |
| value | 当前标签,配合 onChange 实现受控 | string[] | undefined | - | 1.19.0 |
| draggable | 设置是否可拖拽 | boolean | false | 2.17.0 |
| expandRestTagsOnClick | 在不可拖拽的情况下,在 TagInput 被点击后是否展开多余的 Tag | boolean | true | 2.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 |
| onKeyDown | keydown 回调 | (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-disabled、aria-invalid; - TagInput 的输入框和清空按钮均具有
aria-label来表明元素作用。