代码演示

如何引入

import { TagInput } from '@kousum/semi-ui-vue';

基本演示

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput

5

        defaultValue={['抖音', '火山', '西瓜视频']}

6

        placeholder='请输入...'

7

        onChange={v => console.log(v)}

8

    />

9

);

Show Error

Auto Save

批量添加

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

17

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <>

5

        <TagInput 

6

            separator='-' 

7

            placeholder='使用 - 进行批量输入'

8

            onChange={v => console.log(v)}

9

        />

10

        <br/><br/>

11

        <TagInput 

12

            separator={['-', '/', '|', '++']}

13

            placeholder='支持多个分隔符进行批量输入'

14

            onChange={v => console.log(v)}

15

        />

16

    </>

17

);

Show Error

Auto Save

批量删除

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

10

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput 

5

        showClear 

6

        defaultValue={['抖音', '火山']} 

7

        placeholder='请输入...'

8

        onChange={v => console.log(v)}

9

    />

10

);

Show Error

Auto Save

禁用

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

10

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput 

5

        disabled 

6

        showClear 

7

        defaultValue={['抖音', '火山', '西瓜视频']} 

8

        placeholder='请输入...'

9

    />

10

);

Show Error

Auto Save

尺寸大小

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

11

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <>

5

        <TagInput size='small' placeholder='small'/>

6

        <br/><br/>

7

        <TagInput placeholder='default'/>

8

        <br/><br/>

9

        <TagInput size='large' placeholder='large'/>

10

    </>

11

);

Show Error

Auto Save

不同校验状态样式

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

11

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <>

5

        <TagInput placeholder='default'/>

6

        <br/><br/>

7

        <TagInput placeholder='warning' validateStatus='warning'/>

8

        <br/><br/>

9

        <TagInput placeholder='error' validateStatus='error'/>

10

    </>

11

);

Show Error

Auto Save

前缀 / 后缀

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

14

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

import { IconVigoLogo, IconGift } from '@kousum/semi-icons-vue';

3

​

4

export default () => (

5

    <>

6

        <TagInput prefix={<IconVigoLogo />} />

7

        <br/><br/>

8

        <TagInput prefix="Prefix" />

9

        <br/><br/>

10

        <TagInput suffix={<IconGift />} />

11

        <br/><br/>

12

        <TagInput suffix="Suffix" />

13

    </>

14

);

Show Error

Auto Save

失焦后自动创建标签

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

10

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput

5

        defaultValue={['抖音', '火山', '西瓜视频']}

6

        addOnBlur={true}

7

        placeholder='请输入...'

8

        onChange={v => console.log(v)}

9

    />

10

);

Show Error

Auto Save

过滤重复标签

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

10

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput

5

        defaultValue={['抖音', '火山', '西瓜视频']}

6

        allowDuplicates={false}

7

        placeholder='请输入...'

8

        onChange={v => console.log(v)}

9

    />

10

);

Show Error

Auto Save

输入限制

可使用 max 限制输入的标签数量，超出后将不允许再输入，并且触发 onExceed() 回调。

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

25

 

1

import { TagInput,Toast } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <>

5

        <TagInput 

6

            max={3} 

7

            placeholder='最多输入3条标签..' 

8

            onChange={v => console.log(v)}

9

            onExceed={v => {

10

                Toast.warning('超过 max');

11

                console.log(v);

12

            }}

13

        />

14

        <TagInput 

15

            maxLength={5} 

16

            placeholder='单个标签长度不超过5...'  

17

            style={{ marginTop: '12px' }}

18

            onChange={v => console.log(v)}

19

            onInputExceed={v => {

20

                Toast.warning('超过 maxLength');

21

                console.log(v);

22

            }} 

23

        />

24

    </>

25

);

Show Error

Auto Save

限制标签展示数量

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

11

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput 

5

        maxTagCount={2}

6

        showRestTagsPopover={true}

7

        restTagsPopoverProps={{ position: 'top' }}

8

        defaultValue={['抖音', '火山', '西瓜视频']}

9

        onChange={v => console.log(v)}

10

    />

11

);

Show Error

Auto Save

标签受控

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

26

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

import { defineComponent, reactive } from 'vue';

3

​

4

const Comp = defineComponent(() => {

5

​

6

  const state = reactive({

7

    value: ['抖音']

8

  });

9

  function onChange(value){

10

    state.value = value

11

  }

12

​

13

  return () => {

14

​

15

    return (

16

      <TagInput

17

        value={state.value}

18

        onChange={value => {

19

          onChange(value);

20

        }}

21

      />

22

    );

23

  }

24

})

25

​

26

export default Comp

Show Error

Auto Save

输入受控

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

25

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

import { defineComponent } from 'vue';

3

import { reactive } from 'vue';

4

​

5

const Comp = defineComponent(() => {

6

​

7

  const state = reactive({

8

    value: 'abc'

9

  });

10

  function handleInputChange(value, event){

11

    state.value = value

12

  }

13

​

14

  return () => {

15

​

16

    return (

17

      <TagInput

18

        inputValue={state.value}

19

        onInputChange={(v, e) => handleInputChange(v, e)}

20

      />

21

    );

22

  }

23

})

24

​

25

export default Comp

Show Error

Auto Save

回调

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

15

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput 

5

        defaultValue={['抖音']} 

6

        placeholder='请输入...'

7

        showClear 

8

        onFocus={e => {console.log(`onFocus`);}} 

9

        onBlur={e => {console.log(`onBlur`);}} 

10

        onChange={tag => {console.log(`onChange,当前标签数组：${tag}`);}} 

11

        onAdd={tag => {console.log(`onAdd，新增：${tag}`);}} 

12

        onRemove={(v, i) => {console.log(`onRemove，移除：${v}, 序号：${i}`);}} 

13

        onInputChange={(input, e) => {console.log(`onInputChange，当前输入内容：${input}`);}} 

14

    />

15

);

Show Error

Auto Save

焦点管理

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

25

 

1

import { TagInput, Button } from '@kousum/semi-ui-vue';

2

import { defineComponent } from 'vue';

3

import { ref } from 'vue';

4

​

5

const Comp = defineComponent(() => {

6

​

7

  const thisRef = ref()

8

  function handleTagInputFocus()

9

  {

10

    thisRef.value.focus();

11

  }

12

  return () => {

13

​

14

    return (

15

      <>

16

        <TagInput defaultValue={['抖音', '火山']} ref={thisRef} />

17

        <Button style={{ marginTop: '10px' }} onClick={handleTagInputFocus}>

18

          点击按钮聚焦

19

        </Button>

20

      </>

21

    );

22

  }

23

})

24

​

25

export default Comp

Show Error

Auto Save

自定义标签渲染

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

62

 

1

import { TagInput, Avatar } from '@kousum/semi-ui-vue';

2

import { IconClose } from '@kousum/semi-icons-vue';

3

import { defineComponent } from 'vue';

4

import { reactive } from 'vue';

5

​

6

const Comp = defineComponent(() => {

7

​

8

  const state = reactive({

9

    value: ['夏可漫']

10

  });

11

  const list = [

12

    {

13

      "name": "夏可漫",

14

      "avatar": "https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/avatarDemo.jpeg"

15

    },

16

    {

17

      "name": "申悦",

18

      "avatar": "https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg"

19

    },

20

    {

21

      "name": "曲晨一",

22

      "avatar": "https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dbf7351bb779433d17c4f50478cf42f7.jpg"

23

    },

24

    {

25

      "name": "文嘉茂",

26

      "avatar": "https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/7abf810ff060ac3387bd027ead92c4e0.jpg"

27

    },

28

  ];

29

  const mapList = new Map(list.map(item => [item.name, item]));

30

  function renderTagItem(value, index, onClose)

31

  {

32

    const data = mapList.get(value);

33

    return (

Show Error

Auto Save

拖拽排序

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

0px x 0px

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx

11

7

11

 

1

import { TagInput } from '@kousum/semi-ui-vue';

2

​

3

export default () => (

4

    <TagInput

5

        draggable

6

        allowDuplicates={false}

7

        defaultValue={['抖音', '火山', '西瓜视频']}

8

        placeholder='请输入...'

9

        onChange={v => console.log(v)}

10

    />

11

);

Show Error

Auto Save

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 来表明元素作用。

设计变量

color

spacing

height

width

radius

other

font

animation

变量	默认值	用法
$color-tagInput-icon-default	var(--semi-color-text-2)	标签输入框图标颜色 - 默认
$color-tagInput-maxTagCount-default	var(--semi-color-text-0)	标签输入框限制标签展示数量文字颜色
$color-tagInput-icon-hover	var(--semi-color-primary-hover)	标签输入框图标颜色 - 悬浮
$color-tagInput_disabled-text-default	var(--semi-color-disabled-text)	标签输入框禁用文字颜色
$color-tagInput_default-bg-focus	var(--semi-color-fill-0)	标签输入框背景颜色 - 选中态
$color-tagInput-border-default	transparent	标签输入框描边颜色 - 默认
$color-tagInput-border-hover	transparent	标签输入框描边颜色 - 悬浮
$color-tagInput-border-focus	var(--semi-color-focus-border)	标签输入框描边颜色 - 选中态
$color-tagInput_prefix-default	var(--semi-color-text-2)	标签输入框 prefix 颜色
$color-tagInput_suffix-default	var(--semi-color-text-2)	标签输入框 suffix 颜色

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

• 1
• 2
• 3

变量	默认值	用法
$spacing-tagInput_small-Y	1px	小尺寸标签输入框标签顶部外边距
$spacing-tagInput_default-Y	$spacing-super-tight	默认尺寸标签输入框标签顶部外边距
$spacing-tagInput_large-Y	3px	大尺寸标签输入框标签顶部外边距
$spacing-tagInput_wrapper_n_paddingX	$spacing-tight	标签输入框标签容器水平内边距
$spacing-tagInput_drag_handler-marginRight	4px	拖拽handler icon的右外边距
$spacing-tagInput_tag_icon_paddingLeft	4px	tag中有handler icon时tag的左内边距
$spacing-tagInput_prefix_suffix-marginX	$spacing-base-tight	标签输入框 prefix/suffix 水平外边距

显示第 1 条-第 7 条，共 7 条

• 1

变量	默认值	用法
$height-tagInput-large	$height-control-large	大尺寸标签输入框高度
$height-tagInput-default	$height-control-default	默认尺寸标签输入框高度
$height-tagInput-small	$height-control-small	小尺寸标签输入框高度
$height-tagInput_input_small	20px	小尺寸标签输入框Input框高度
$height-tagInput_input_default	24px	默认尺寸标签输入框Input框高度
$height-tagInput_input_large	24px	大尺寸标签输入框Input框高度

显示第 1 条-第 6 条，共 6 条

• 1

变量	默认值	用法
$width-tagInput-clear-medium	$width-icon-medium * 2	标签输入框清空按钮宽度
$width-tagInput-border-default	$border-thickness-control	标签输入框描边描边宽度 - 默认
$width-tagInput-border-hover	$width-tagInput-border-default	标签输入框描边描边宽度 - 悬浮
$width-tagInput-border-focus	$border-thickness-control-focus	标签输入框描边宽度 - 选中态
$width-tagInput_sortable_item_over	2px	拖拽经过的元素前竖线宽度

显示第 1 条-第 5 条，共 5 条

• 1

变量	默认值	用法
$radius-tagInput	var(--semi-border-radius-small)	标签输入框圆角

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

• 1

变量	默认值	用法
$z-tagInput_drag_item_move	2000 !default	标签输入框中正在拖拽元素的z-index

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

• 1

变量	默认值	用法
$font-tagInput_prefix_suffix-fontWeight	$font-weight-bold	标签输入框 prefix/suffix 文字字重

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

• 1

变量	默认值	用法
$transition_duration-tagInput-bg	var(--semi-transition_duration-none)	标签输入框-背景色-动画持续时间
$transition_function-tagInput-bg	var(--semi-transition_function-easeIn)	标签输入框-背景色-过渡曲线
$transition_delay-tagInput-bg	var(--semi-transition_delay-none)	标签输入框-背景色-延迟时间
$transition_duration-tagInput-border	var(--semi-transition_duration-none)	标签输入框-边框-动画持续时间
$transition_function-tagInput-border	var(--semi-transition_function-easeIn)	标签输入框-边框-过渡曲线
$transition_delay-tagInput-border	var(--semi-transition_delay-none)	标签输入框-边框-延迟时间

显示第 1 条-第 6 条，共 6 条

• 1