标签输入

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

查看代码

苹果

香蕉

功能

可受控或不受控。
全键盘导航。
限制标签数量。
接受剪贴板中的值。
清除按钮可重置所有标签值。

安装

从命令行安装此组件。

$ 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 参考

根

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

属性	默认	类型
`addOnBlur`		`布尔值` 当 `true` 时，允许在输入框失焦时添加标签
`addOnPaste`		`布尔值` 当 `true` 时，允许在粘贴时添加标签。与 delimiter 属性结合使用。
`addOnTab`		`布尔值` 当 `true` 时，允许在按下 Tab 键时添加标签
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`convertValue`		`((value: string) => AcceptableInputValue)` 将输入值转换为所需类型。当使用对象作为值并使用 `TagsInputInput` 时，这是强制性的。
`defaultValue`	`[]`	`AcceptableInputValue[]` 应添加的标签的值。当您不需要控制标签输入的状态时使用。
`delimiter`	`','`	`string \| RegExp` 用于触发新标签添加的字符或正则表达式。也用于在 `@paste` 事件中拆分标签。
`dir`		`'ltr' \| 'rtl'` 适用时，组合框的阅读方向。如果省略，则全局继承自 `ConfigProvider` 或假定为 LTR（从左到右）阅读模式。
`disabled`		`布尔值` 当 `true` 时，阻止用户与标签输入框交互。
`displayValue`	`value.toString()`	`((value: AcceptableInputValue) => string)` 显示标签的值。当您想对值进行修改（例如添加后缀）或使用对象作为值时很有用。
`duplicate`		`布尔值` 当 `true` 时，允许重复标签。
`id`		`string`
`max`	`0`	`数字` 标签的最大数量。
`modelValue`		`AcceptableInputValue[] \| null` 标签输入框的受控值。可以绑定为 `v-model`。
`name`		`string` 字段的名称。随其所属的表单一起作为名称/值对提交。
`required`		`布尔值` 当为 `true` 时，表示用户必须在所属表单提交前设置值。

事件触发	载荷
`addTag`	`[payload: AcceptableInputValue]` 标签添加时调用的事件处理程序。
`invalid`	`[payload: AcceptableInputValue]` 值无效时调用的事件处理程序。
`removeTag`	`[payload: AcceptableInputValue]` 标签移除时调用的事件处理程序。
`update:modelValue`	`[payload: AcceptableInputValue[]]` 值改变时调用的事件处理程序

插槽（默认）	载荷
`modelValue`	`string \| Record<string, any>` 当前输入值

数据属性	值
`[data-disabled]`	禁用时存在
`[data-focused]`	输入框聚焦时存在。
`[data-invalid]`	输入值无效时存在。

标签项

包含标签的组件。

属性	默认	类型
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`disabled`		`布尔值` 当 `true` 时，阻止用户与标签输入框交互。
`值*`		`string \| Record<string, any>` 与标签关联的值

数据属性	值
`[data-state]`	`"激活" \| "非激活"`
`[data-disabled]`	禁用时存在

标签文本

标签的文本部分。对可访问性很重要。

属性	默认	类型
`as`	`'span'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

标签删除

删除关联标签的按钮。

属性	默认	类型
`as`	`'button'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

数据属性	值
`[data-state]`	`"激活" \| "非激活"`
`[data-disabled]`	禁用时存在

输入

标签输入框的输入元素。

属性	默认	类型
`as`	`'input'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`autoFocus`		`布尔值` 挂载时聚焦元素。
`maxLength`		`数字` 允许的最大字符数。
`placeholder`		`string` 空标签输入框使用的占位符字符。

数据属性	值
`[data-invalid]`	输入值无效时存在。

清除

删除所有标签的按钮。

属性	默认	类型
`as`	`'button'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。

数据属性	值
`[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'

// split by space, comma, semicolon, tab, or newline
const delimiter = /[ ,;\t\n\r]+/
</script>

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

可访问性

键盘交互

键	描述
`删除`	当标签处于激活状态时，移除它并将右侧标签设置为激活状态。
`退格键`	当标签处于激活状态时，移除它并将左侧标签设置为激活状态。如果左侧没有标签，则焦点将移动到下一个标签或输入框。
`向右箭头`	设置下一个标签为激活状态。
`向左箭头`	设置上一个标签为激活状态。
`Home 键`	设置第一个标签为激活状态
`End 键`	设置最后一个标签为激活状态

标签输入 ​

功能 ​

安装 ​

结构 ​

API 参考 ​

根 ​

标签项 ​

标签文本 ​

标签删除 ​

输入 ​

清除 ​

示例 ​

粘贴行为 ​

多个分隔符 ​

可访问性 ​

键盘交互 ​