TagInput

代码演示

如何引入

import { TagInput } from '@chenzy-design/svelte';

基本演示

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

批量添加

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

批量删除

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

禁用

尺寸大小

通过 size 控制标签输入框的大小尺寸，可选：small、default、large。

不同校验状态样式

可以使用 validateStatus 设置不同校验状态的样式，它仅影响背景颜色等样式表现，可选值：default、warning、error。

前缀 / 后缀

可以通过 prefix 传入输入框前缀，通过 suffix 传入输入框后缀，可以为文本或者节点。当 prefix、suffix 传入的内容为 string 或者 Icon 时，会自动带上左右间隔；若为自定义节点，则左右间隔为 0。

失焦后自动创建标签

可使用 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 自定义标签渲染，第三个参数 onClose 用于关闭对应标签。

拖拽排序

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

API 参考

属性	说明	类型	默认值
addOnBlur	是否在 blur 事件触发时，将当前 input 的值自动创建成 tag	boolean	false
affixIsIcon	prefix/suffix 传节点时是否按图标间距渲染	boolean	true
allowDuplicates	是否允许添加相同 tag	boolean	true
aria-label	表示该 TagInput 作用	string	-
ariaDescribedby	关联 helpText / extraText 节点 id	string	-
ariaErrormessage	error 态关联错误信息容器 id	string	-
ariaLabelledby	关联外部 label 元素 id	string	-
ariaRequired	必填语义	boolean	-
autoFocus	初始渲染时是否自动 focus	boolean	false
class	样式类名	string	-
clearIcon	自定义清除图标	Snippet	-
defaultValue	初始标签	string[]	-
disabled	是否禁用	boolean	false
draggable	设置是否可拖拽	boolean	false
expandRestTagsOnClick	在不可拖拽的情况下，TagInput 被点击后是否展开多余的 Tag	boolean	true
insetLabel	内嵌 label（前缀位）	string \| Snippet	-
insetLabelId	内嵌 label 的 id（关联输入）	string	-
inputValue	当前输入框内容，配合 onInputChange 实现受控	string	-
max	允许标签的最大数量	number	-
maxLength	单个标签的最大长度	number	-
maxTagCount	标签的最大展示数量，超出后将以 +N 形式展示	number	-
placeholder	占位默认值	string	-
prefix	前缀标签	string \| Snippet	-
preventScroll	指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的 focus 方法	boolean	-
renderTagItem	自定义标签渲染	Snippet<[{ value, index, onClose }]>	-
restTagsPopoverProps	Popover 的配置属性	object	{}
separator	设置批量输入时的分隔符	string \| string[]	,
showClear	是否支持一键删除所有标签和输入内容	boolean	false
showContentTooltip	当标签长度过长发生截断时，hover 标签时是否通过 Tooltip 显示全部内容	boolean \| object	true
showRestTagsPopover	当超过 maxTagCount，hover +N 时，是否通过 Popover 显示剩余内容	boolean	true
size	设置输入框尺寸，可选：small、large、default	string	default
split	自定义分隔符处理函数	(value: string, separator) => string[]	-
style	内联样式	string	-
suffix	后缀标签	string \| Snippet	-
validateStatus	设置校验状态样式，可选：default、warning、error	string	default
value	当前标签，配合 onChange 实现受控	string[]	-
onAdd	添加标签时的回调	(addedValue: string[]) => void	-
onBlur	输入框失去焦点时的回调	(e) => void	-
onChange	标签变化时的回调	(value: string[]) => void	-
onExceed	超过 max 时的回调	(value: string[]) => void	-
onFocus	输入框获取焦点时的回调	(e) => void	-
onInputChange	输入框内容变化时的回调	(value: string) => void	-
onInputExceed	超过 maxLength 时的回调	(value: string) => void	-
onKeyDown	keydown 回调	(e: KeyboardEvent) => void	-
onRemove	移除标签时的回调	(removedValue: string, idx: number) => void	-

Methods

绑定在组件实例上的方法，可以通过 bind:this 拿到实例后调用：

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

Accessibility

ARIA

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

设计变量

color

font

height

radius

spacing

width

变量	默认值	用法
--cd-tag-input-border-default	transparent	标签输入框描边颜色 - 默认
--cd-tag-input-border-focus	var(--cd-color-focus-border)	标签输入框描边颜色 - 选中态
--cd-tag-input-border-hover	transparent	标签输入框描边颜色 - 悬浮
--cd-tag-input-danger-bg-default	var(--cd-color-danger-light-default)	危险标签输入框背景颜色 - 默认
--cd-tag-input-danger-bg-focus	var(--cd-color-danger-light-default)	危险标签输入框背景颜色 - 选中
--cd-tag-input-danger-bg-hover	var(--cd-color-danger-light-hover)	危险标签输入框背景颜色 - 悬浮
--cd-tag-input-danger-border-default	var(--cd-color-danger-light-default)	危险标签输入框描边颜色 - 默认
--cd-tag-input-danger-border-focus	var(--cd-color-danger)	危险标签输入框描边颜色 - 选中
--cd-tag-input-danger-border-hover	var(--cd-color-danger-light-hover)	危险标签输入框描边颜色 - 悬浮
--cd-tag-input-default-bg-default	var(--cd-color-fill-0)	标签输入框背景颜色 - 默认

显示第 1 条-第 10 条，共 27 条

• 1
• 2
• 3