---
title: "TagInput 标签输入"
description: "以回车或分隔符录入标签的输入框"
category: Form
syncStatus: reviewed
status: beta
since: 0.3.4
tags: [tag, input, form]
verified: true
---

## 用法

### 基础
::TuffDemoWrapper{demo="TagInputTagInputDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const tags = ref(['Design', 'Docs'])
  </script>

  <template>
    <TxTagInput v-model="tags" placeholder="输入标签后回车" />
  </template>
---
::

### 发布策略配置
`TxTagInput` 承载检索用的元数据，`max` 限制数量。
::TuffDemoWrapper{demo="ComponentsReleasePolicyDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const riskSegments = [
    { value: 1, label: '低' },
    { value: 2, label: '中' },
    { value: 3, label: '高' },
    { value: 4, label: '冻结' },
  ]
  </script>

  <template>
    <TxCascader v-model="releasePath" :options="scopeOptions" placeholder="发布范围" />
    <TxFlatSelect v-model="rolloutMode" placeholder="发布模式">
      <TxFlatSelectItem value="phased" label="分阶段" />
      <TxFlatSelectItem value="guarded" label="护栏发布" />
    </TxFlatSelect>
    <TxSegmentedSlider v-model="riskLevel" :segments="riskSegments" />
    <TxSlider v-model="traffic" :min="5" :max="100" :step="5" show-value :format-value="value => value + '%'" />
    <TxTagInput v-model="labels" placeholder="输入标签后回车" :max="5" />
  </template>
---
::

### 最佳实践

- 标签只放短元数据；发布备注、审批原因等长文本用文本域或详情表单。
- `max` 设为流程真正需要的最小值。
- 除非重复标签有业务含义，否则保持 `allowDuplicates` 关闭。
- 帮助文案里提到的分隔符都写进 `separators`。
- 说明、帮助与校验提示放在组件外层。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|------|------|
| `modelValue` | `string[]` | `[]` | 标签列表，也是唯一数据源；每次增删都以新数组派发更新。 |
| `placeholder` | `string` | `'Add tag'` | 占位文本。 |
| `disabled` | `boolean` | `false` | 禁止增删，已有标签的关闭按钮也失效。 |
| `max` | `number` | `20` | 标签数量上限；达到后输入框禁用、占位文本隐藏。 |
| `allowDuplicates` | `boolean` | `false` | 允许重复；关闭时按 trim 后精确匹配去重，区分大小写。 |
| `separators` | `string[]` | `[',']` | 拆分粘贴或键入文本的分隔符。 |
| `confirmOnBlur` | `boolean` | `true` | 失焦时提交未确认的输入。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(tags: string[])` | 携带下一份完整列表触发。 |
| `change` | `(tags: string[])` | 与 `update:modelValue` 同时触发。 |
| `add` | `(tags: string[])` | 携带本次实际加入的标签触发。 |
| `remove` | `(tag: string)` | 携带被移除的标签触发。 |
| `focus` | `(event: FocusEvent)` | 透传输入框的 focus。 |
| `blur` | `(event: FocusEvent)` | 透传输入框的 blur。 |

## 概述

- 输入先 trim，空标签被忽略。
- `separators` 拆分粘贴或键入的文本；Enter 始终确认当前输入。
- `confirmOnBlur` 开启时，先派发 `blur`，再提交未确认的输入。
- 输入框为空时，Backspace 移除最后一个标签。

## 技术实现

- 已有标签由 `TxTag` 渲染。
- 源码：`packages/tuffex/packages/components/src/tag-input/`；导出类型 `TagInputProps`、`TagInputEmits`。

<TuffDocSourceLink />