BrutxUI

简体中文

English

简体中文

English

外观

TagsInput 标签输入 ​

新粗野主义风格的标签录入组件，基于 reka-ui 原语构建，常用于文章标签、邮件收件人、关键词筛选等表单场景。支持键盘快捷键、分隔符自动添加和多种配色变体。

预览 ​

Preview

默认

vue
tailwind
brutalism

主要

typescript
vite
cva

次要

reka-ui
lucide
pnpm

强调

neo-brutalism
design
tokens

危险

bug
deprecated
breaking

成功

stable
tested
released

自定义 aria-label

vue
a11y

安装 ​

pnpm dlx brutx-vue@latest add tags-input

用法 ​

vue
<script setup>
import { ref } from 'vue'
import {
    TagsInput,
    TagsInputInput,
    TagsInputItem,
    TagsInputItemText,
    TagsInputItemDelete
} from 'brutx-ui-vue'

const tags = ref(['vue', 'css'])
</script>

<template>
    <TagsInput v-model="tags">
        <TagsInputItem v-for="tag in tags" :key="tag" :value="tag">
            <TagsInputItemText>{{ tag }}</TagsInputItemText>
            <TagsInputItemDelete />
        </TagsInputItem>
        <TagsInputInput placeholder="Add tag..." />
    </TagsInput>
</template>

变体 ​

可以使用 TagsInputItem 的 variant 属性定制单个标签的配色方案：

变体说明
primary默认珊瑚红背景，配黑色粗边框
secondary薄荷青背景
accent粗野黄色背景
success经典绿色背景
danger经典红色背景
default纯白背景
vue
<template>
    <TagsInputItem value="css" variant="secondary">
        <TagsInputItemText>CSS</TagsInputItemText>
        <TagsInputItemDelete />
    </TagsInputItem>
</template>

子组件 ​

组件说明
TagsInput根组件，管理标签列表状态
TagsInputInput文本输入框
TagsInputItem单个标签项容器
TagsInputItemText标签文本内容
TagsInputItemDelete标签删除按钮

API 参考 ​

TagsInput

TagsInput — 属性
名称类型默认值说明
modelValue
可空
AcceptableInputValue[] | null | undefined
—
受控的标签值列表，可通过 v-model 同步；每项可以是字符串、数字、bigint 或对象。
详情

声明类型

AcceptableInputValue[] | null | undefined

字面量

  • null

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

defaultValue
AcceptableInputValue[] | undefined
—
非受控模式使用的初始标签值列表；需要从外部同步时请改用 modelValue。
详情

声明类型

AcceptableInputValue[] | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

addOnPaste
boolean | undefined
—
粘贴文本时按 delimiter 拆分并尝试添加标签；是否成功仍受 max 和 duplicate 限制。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

addOnTab
boolean | undefined
—
按 Tab 键时将当前输入提交为标签。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

addOnBlur
boolean | undefined
—
输入框失焦时将当前输入提交为标签。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

duplicate
boolean | undefined
—
允许列表中存在重复标签值；关闭时重复值会被视为无效。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

disabled
boolean | undefined
—
禁用标签输入组及其子项的用户交互。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

delimiter
string | RegExp | undefined
—
用于提交输入和拆分粘贴内容的分隔符；可以传入单个字符串或正则表达式。
详情

声明类型

string | RegExp | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

dir
Direction | undefined
—
设置组合框内容的阅读方向；未指定时继承 ConfigProvider 配置，否则按从左到右处理。
详情

声明类型

Direction | undefined

字面量

  • "ltr"
  • "rtl"

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

max
number | undefined
—
允许的最大标签数量；达到上限后不再添加标签并发出 invalid，设为 0 表示不限制。
详情

声明类型

number | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

id
string | undefined
—
传递给标签输入根原语的 DOM ID，用于标识该输入组。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

convertValue
((value: string) => AcceptableInputValue) | undefined
—
将输入字符串转换为标签值的函数；使用对象标签并通过 TagsInputInput 输入时必须提供。
详情

声明类型

((value: string) => AcceptableInputValue) | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

displayValue
((value: AcceptableInputValue) => string) | undefined
—
将标签值转换为显示文本；适用于对象标签或需要添加后缀等展示格式的场景。
详情

声明类型

((value: AcceptableInputValue) => string) | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

asChild
boolean | undefined
—
将组件的属性与交互行为合并到唯一子元素上，并由该子元素替代默认渲染元素。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

as
AsTag | Component | undefined
—
指定此标签输入子组件使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情

声明类型

AsTag | Component | undefined

字面量

  • "a"
  • "button"
  • "div"
  • "form"
  • "h2"
  • "h3"
  • "img"
  • "input"
  • "label"
  • "li"
  • "nav"
  • "ol"
  • "p"
  • "span"
  • "svg"
  • "template"
  • "ul"

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

name
string | undefined
—
表单字段名；提交所属表单时，标签值会以此名称参与表单数据提交。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

required
boolean | undefined
—
将标签输入标记为所属表单的必填字段。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

class
string | undefined
—
追加到标签输入根容器的 CSS 类。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue:7

packages/ui/src/components/tags-input/TagsInput.vue

ariaLabel
string | undefined
—
标签输入组的无障碍名称；未提供时使用当前语言的 tagsInput.label 文案。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInput.vue:7

packages/ui/src/components/tags-input/TagsInput.vue

TagsInput — 事件
名称签名或类型说明
@update:modelValue
[payload: AcceptableInputValue[]]
标签列表变化时发出新数组，用于同步受控 v-model。
详情

声明类型

[payload: AcceptableInputValue[]]

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

@invalid
[payload: AcceptableInputValue]
尝试添加重复值或超过 max 上限的标签时发出被拒绝的标签值。
详情

声明类型

[payload: AcceptableInputValue]

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

@addTag
[payload: AcceptableInputValue]
成功添加标签后发出新增的标签值。
详情

声明类型

[payload: AcceptableInputValue]

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

@removeTag
[payload: AcceptableInputValue]
成功移除标签后发出被移除的标签值。
详情

声明类型

[payload: AcceptableInputValue]

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

TagsInput — 插槽
名称签名或类型说明
#default
{}
组合标签项和输入框的内容；作用域中提供当前 modelValue，通常放置 TagsInputItem 与 TagsInputInput。
详情

声明类型

{}

来源

TagsInput.vue

packages/ui/src/components/tags-input/TagsInput.vue

TagsInputInput

TagsInputInput — 属性
名称类型默认值说明
placeholder
string | undefined
—
输入框为空时显示的占位文本。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInputInput.vue

packages/ui/src/components/tags-input/TagsInputInput.vue

autoFocus
boolean | undefined
—
组件挂载后自动将焦点移到输入框。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputInput.vue

packages/ui/src/components/tags-input/TagsInputInput.vue

maxLength
number | undefined
—
限制输入框中可输入的字符数。
详情

声明类型

number | undefined

默认值详情

未声明默认值
—

来源

TagsInputInput.vue

packages/ui/src/components/tags-input/TagsInputInput.vue

asChild
boolean | undefined
—
将组件的属性与交互行为合并到唯一子元素上，并由该子元素替代默认渲染元素。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputInput.vue

packages/ui/src/components/tags-input/TagsInputInput.vue

as
AsTag | Component | undefined
—
指定此标签输入子组件使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情

声明类型

AsTag | Component | undefined

字面量

  • "a"
  • "button"
  • "div"
  • "form"
  • "h2"
  • "h3"
  • "img"
  • "input"
  • "label"
  • "li"
  • "nav"
  • "ol"
  • "p"
  • "span"
  • "svg"
  • "template"
  • "ul"

默认值详情

未声明默认值
—

来源

TagsInputInput.vue

packages/ui/src/components/tags-input/TagsInputInput.vue

class
string | undefined
—
追加到标签输入原生输入元素的 CSS 类。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInputInput.vue:10

packages/ui/src/components/tags-input/TagsInputInput.vue

TagsInputItem

TagsInputItem — 属性
名称类型默认值说明
variant
"accent" | "danger" | "default" | "primary" | "secondary" | "success" | undefined
"primary"
设置单个标签的配色变体。
详情

声明类型

NonNullable<"default" | "primary" | "secondary" | "success" | "danger" | "accent" | null | undefined> | undefined

字面量

  • "accent"
  • "danger"
  • "default"
  • "primary"
  • "secondary"
  • "success"

默认值详情

声明
'primary'

来源: packages/ui/src/components/tags-input/TagsInputItem.vue

解析值
"primary"

来源

TagsInputItem.vue:15

packages/ui/src/components/tags-input/TagsInputItem.vue

class
string | undefined
undefined
追加到单个标签容器的 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tags-input/TagsInputItem.vue

解析值
undefined

来源

TagsInputItem.vue:16

packages/ui/src/components/tags-input/TagsInputItem.vue

value
必填
AcceptableInputValue
—
此标签对应的值，必须与根组件标签列表中的一项匹配。
详情

声明类型

AcceptableInputValue

默认值详情

未声明默认值
—

来源

TagsInputItem.vue

packages/ui/src/components/tags-input/TagsInputItem.vue

disabled
boolean | undefined
—
禁止对此标签执行交互操作。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputItem.vue

packages/ui/src/components/tags-input/TagsInputItem.vue

asChild
boolean | undefined
—
将组件的属性与交互行为合并到唯一子元素上，并由该子元素替代默认渲染元素。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputItem.vue

packages/ui/src/components/tags-input/TagsInputItem.vue

as
AsTag | Component | undefined
—
指定此标签输入子组件使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情

声明类型

AsTag | Component | undefined

字面量

  • "a"
  • "button"
  • "div"
  • "form"
  • "h2"
  • "h3"
  • "img"
  • "input"
  • "label"
  • "li"
  • "nav"
  • "ol"
  • "p"
  • "span"
  • "svg"
  • "template"
  • "ul"

默认值详情

未声明默认值
—

来源

TagsInputItem.vue

packages/ui/src/components/tags-input/TagsInputItem.vue

TagsInputItem — 插槽
名称签名或类型说明
#default
{}
渲染标签项内容，通常包含 TagsInputItemText 和 TagsInputItemDelete。
详情

声明类型

{}

来源

TagsInputItem.vue

packages/ui/src/components/tags-input/TagsInputItem.vue

TagsInputItemDelete

TagsInputItemDelete — 属性
名称类型默认值说明
class
string | undefined
undefined
追加到标签删除按钮的 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tags-input/TagsInputItemDelete.vue

解析值
undefined

来源

TagsInputItemDelete.vue:14

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

ariaLabel
string | undefined
undefined
删除按钮的无障碍名称；未提供时使用当前语言的默认删除文案。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/tags-input/TagsInputItemDelete.vue

解析值
undefined

来源

TagsInputItemDelete.vue:15

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

type
"button" | "submit" | "reset" | undefined
"button"
设置原生按钮类型，默认 button 可避免在表单中误触发提交。
详情

声明类型

"button" | "submit" | "reset" | undefined

字面量

  • "button"
  • "reset"
  • "submit"

默认值详情

声明
'button'

来源: packages/ui/src/components/tags-input/TagsInputItemDelete.vue

解析值
"button"

来源

TagsInputItemDelete.vue:16

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

asChild
boolean | undefined
—
将组件的属性与交互行为合并到唯一子元素上，并由该子元素替代默认渲染元素。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputItemDelete.vue

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

as
AsTag | Component | undefined
—
指定此标签输入子组件使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情

声明类型

AsTag | Component | undefined

字面量

  • "a"
  • "button"
  • "div"
  • "form"
  • "h2"
  • "h3"
  • "img"
  • "input"
  • "label"
  • "li"
  • "nav"
  • "ol"
  • "p"
  • "span"
  • "svg"
  • "template"
  • "ul"

默认值详情

未声明默认值
—

来源

TagsInputItemDelete.vue

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

TagsInputItemDelete — 插槽
名称签名或类型说明
#default
{}
自定义删除按钮内容；未提供时显示 X 图标。
详情

声明类型

{}

来源

TagsInputItemDelete.vue

packages/ui/src/components/tags-input/TagsInputItemDelete.vue

TagsInputItemText

TagsInputItemText — 属性
名称类型默认值说明
asChild
boolean | undefined
—
将组件的属性与交互行为合并到唯一子元素上，并由该子元素替代默认渲染元素。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

未声明默认值
—

来源

TagsInputItemText.vue

packages/ui/src/components/tags-input/TagsInputItemText.vue

as
AsTag | Component | undefined
—
指定此标签输入子组件使用的 HTML 标签或 Vue 组件；与 asChild 同时设置时由 asChild 决定渲染元素。
详情

声明类型

AsTag | Component | undefined

字面量

  • "a"
  • "button"
  • "div"
  • "form"
  • "h2"
  • "h3"
  • "img"
  • "input"
  • "label"
  • "li"
  • "nav"
  • "ol"
  • "p"
  • "span"
  • "svg"
  • "template"
  • "ul"

默认值详情

未声明默认值
—

来源

TagsInputItemText.vue

packages/ui/src/components/tags-input/TagsInputItemText.vue

class
string | undefined
—
追加到标签文本元素的 CSS 类。
详情

声明类型

string | undefined

默认值详情

未声明默认值
—

来源

TagsInputItemText.vue:10

packages/ui/src/components/tags-input/TagsInputItemText.vue

TagsInputItemText — 插槽
名称签名或类型说明
#default
{}
渲染标签的文本内容。
详情

声明类型

{}

来源

TagsInputItemText.vue

packages/ui/src/components/tags-input/TagsInputItemText.vue

可访问性 ​

  • ARIA 属性：TagsInput 默认通过 locale 提供 aria-label（中文为"标签输入"），未提供时回退到 t('tagsInput.label')
  • 自定义标签：当需要更具体的描述（如"文章标签"、"收件人"）时，可通过 ariaLabel prop 自定义
vue
<script setup>
import { ref } from 'vue'
import {
    TagsInput,
    TagsInputInput,
    TagsInputItem,
    TagsInputItemText,
    TagsInputItemDelete
} from 'brutx-ui-vue'

const tags = ref(['vue', 'css'])
</script>

<template>
    <TagsInput v-model="tags" aria-label="文章标签">
        <TagsInputItem v-for="tag in tags" :key="tag" :value="tag">
            <TagsInputItemText>{{ tag }}</TagsInputItemText>
            <TagsInputItemDelete />
        </TagsInputItem>
        <TagsInputInput placeholder="添加标签..." />
    </TagsInput>
</template>

常见问题 ​

Q: 如何使用对象作为标签值而非字符串？

A: 当标签值为对象时，必须提供 convertValue 函数将输入字符串转换为目标对象类型，同时建议提供 displayValue 函数来自定义标签的显示文本。如果未提供 convertValue，组件将使用字符串作为标签值。

Q: 为什么设置了 max 属性后添加标签没有反应？

A: 当标签数量达到 max 限制时，新标签不会被添加，同时会触发 invalid 事件。可以通过监听该事件来向用户展示提示信息。如果 max 设为 0，则表示不限制标签数量。

Q: 粘贴多个标签时如何自动拆分？

A: 设置 addOnPaste 为 true 后，粘贴包含分隔符的文本时会自动拆分为多个标签。默认分隔符为逗号（,），可通过 delimiter 属性自定义，支持字符串和正则表达式。例如设置 delimiter=";" 可以按分号拆分。

蛮力铸就。

© 2026 BrutxUI · MIT License