标签输入框

标签输入框在输入框内渲染标签，后跟实际文本输入框。

View code

Apple

Banana

功能特点

支持受控与非受控模式
完整的键盘导航
限制标签数量
接受剪贴板内容
清除按钮可重置所有标签值

安装

通过命令行安装该组件。

$ npm add reka-ui

结构

导入所有部件并进行组合。

vue

<script setup>
import { TagsInputClear, TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInputItemText, TagsInputRoot } from 'reka-ui'
</script>

<template>
  <TagsInputRoot>
    <TagsInputItem>
      <TagsInputItemText />
      <TagsInputItemDelete />
    </TagsInputItem>

    <TagsInputInput />
    <TagsInputClear />
  </TagsInputRoot>
</template>

API 参考

Root

包含标签输入组件的所有部件。

Prop	Default	Type
`addOnBlur`		`boolean` When `true` allow adding tags blur input
`addOnPaste`		`boolean` When `true`, allow adding tags on paste. Work in conjunction with delimiter prop.
`addOnTab`		`boolean` When `true` allow adding tags on tab keydown
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`convertValue`		`((value: string) => AcceptableInputValue)` Convert the input value to the desired type. Mandatory when using objects as values and using `TagsInputInput`
`defaultValue`	`[]`	`AcceptableInputValue[]` The value of the tags that should be added. Use when you do not need to control the state of the tags input
`delimiter`	`','`	`string \| RegExp` The character or regular expression to trigger the addition of a new tag. Also used to split tags for `@paste` event
`dir`		`'ltr' \| 'rtl'` The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
`disabled`		`boolean` When `true`, prevents the user from interacting with the tags input.
`displayValue`	`value.toString()`	`((value: AcceptableInputValue) => string)` Display the value of the tag. Useful when you want to apply modifications to the value like adding a suffix or when using object as values
`duplicate`		`boolean` When `true`, allow duplicated tags.
`id`		`string`
`max`	`0`	`number` Maximum number of tags.
`modelValue`		`AcceptableInputValue[] \| null` The controlled value of the tags input. Can be bind as `v-model`.
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.

Emit	Payload
`addTag`	`[payload: AcceptableInputValue]` Event handler called when tag is added
`invalid`	`[payload: AcceptableInputValue]` Event handler called when the value is invalid
`removeTag`	`[payload: AcceptableInputValue]` Event handler called when tag is removed
`update:modelValue`	`[payload: AcceptableInputValue[]]` Event handler called when the value changes

Slots (default)	Payload
`modelValue`	`string \| number \| bigint \| Record<string, any>` Current input values

Data Attribute	Value
`[data-disabled]`	禁用时出现
`[data-focused]`	输入框聚焦时出现
`[data-invalid]`	输入值无效时出现

Item

包含标签的组件。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean` When `true`, prevents the user from interacting with the tags input.
`value*`		`string \| number \| bigint \| Record<string, any>` Value associated with the tags

Data Attribute	Value
`[data-state]`	`"激活" \| "未激活"`
`[data-disabled]`	禁用时出现

ItemText

标签的文本部分。对无障碍访问至关重要。

Prop	Default	Type
`as`	`'span'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

ItemDelete

删除关联标签的按钮。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-state]`	`"激活" \| "未激活"`
`[data-disabled]`	禁用时出现

Input

标签输入框的输入元素。

Prop	Default	Type
`as`	`'input'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`autoFocus`		`boolean` Focus on element when mounted.
`maxLength`		`number` Maximum number of character allowed.
`placeholder`		`string` The placeholder character to use for empty tags input.

Data Attribute	Value
`[data-invalid]`	输入值无效时出现

Clear

移除所有标签的按钮。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-disabled]`	禁用时出现

示例

粘贴行为

通过传递 add-on-paste 属性，可在粘贴时自动添加标签。

vue

<script setup lang="ts">
import { TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInputItemText, TagsInputRoot } from 'reka-ui'
</script>

<template>
  <TagsInputRoot
    v-model="modelValue"
    add-on-paste
  >
    …
  </TagsInputRoot>
</template>

多分隔符

可将 RegExp 作为 delimiter 参数传递，允许多个字符触发新标签的添加。当传递 add-on-paste 时，该正则也将用于 @paste 事件中的标签分割。

vue

<script setup lang="ts">
import { TagsInputInput, TagsInputItem, TagsInputItemDelete, TagsInputItemText, TagsInputRoot } from 'reka-ui'

// 按空格、逗号、分号、制表符或换行符分割
const delimiter = /[ ,;\t\n\r]+/
</script>

<template>
  <TagsInputRoot
    v-model="modelValue"
    :delimiter="delimiter"
    add-on-paste
  >
    …
  </TagsInputRoot>
</template>

无障碍访问

键盘交互

Key	Description
`Delete`	标签激活时，移除该标签并激活右侧标签
`Backspace`	标签激活时，移除该标签并激活左侧标签。若左侧无标签，则聚焦下一个标签或输入框
`ArrowRight`	激活下一个标签
`ArrowLeft`	激活上一个标签
`Home`	激活首个标签
`End`	激活末尾标签

标签输入框 ​

功能特点 ​

安装 ​

结构 ​

API 参考 ​

Root ​

Item ​

ItemText ​

ItemDelete ​

Input ​

Clear ​

示例 ​

粘贴行为 ​

多分隔符 ​

无障碍访问 ​

键盘交互 ​