x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/input-tag.md

@@ -0,0 +1,482 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# InputTag AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`InputTag`；主要模型：v-model、v-model:input-value。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./input-tag-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/form-input-tag`（包含 base.css、form-input-tag.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/input-tag.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./input-tag-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于录入多个短文本项，如标签、关键词、邮箱列表。
+
+
+### 何时使用
+
+- 需要一次录入多个等价的短文本，例如关键词、收件人、分类名。
+- 录入后希望以标签形式回显，并允许逐个删除。
+- 需要限制展示数量、去重、前缀后缀或与 Form 校验联动时。
+
+
+### 基础用法
+
+输入内容后按回车创建标签，点击标签上的关闭按钮删除，`allow-clear` 提供整组清空按钮。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['Vue', 'TypeScript']);
+</script>
+<template>
+<InputTag v-model="tags" placeholder="输入后回车" allow-clear />
+</template>
+```
+
+### 状态
+
+`disabled` 禁用输入与删除，`readonly` 保留展示但不可编辑，`error` 使用错误态边框与背景。切换状态后组件会立即响应。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag, Button } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['Vue', 'TypeScript']);
+const state = ref<'normal' | 'disabled' | 'readonly' | 'error'>('normal');
+</script>
+<template>
+<InputTag
+    v-model="tags"
+    :disabled="state === 'disabled'"
+    :readonly="state === 'readonly'"
+    :error="state === 'error'"
+    placeholder="输入后回车"
+    allow-clear
+  />
+  <Button size="small" @click="state = 'disabled'">禁用</Button>
+  <Button size="small" @click="state = 'readonly'">只读</Button>
+  <Button size="small" @click="state = 'error'">错误</Button>
+</template>
+```
+
+### 尺寸与高度
+
+同一尺寸下，空态、单个标签、多个标签的外框高度保持一致；标签内容过长时标签自身换行增高。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const emptyTags = ref<string[]>([]);
+const singleTags = ref(['Vue']);
+</script>
+<template>
+<InputTag v-model="emptyTags" size="mini" placeholder="空态" />
+  <InputTag v-model="singleTags" size="mini" />
+  <InputTag v-model="emptyTags" size="small" placeholder="空态" />
+  <InputTag v-model="singleTags" size="small" />
+  <InputTag v-model="emptyTags" size="medium" placeholder="空态" />
+  <InputTag v-model="singleTags" size="medium" />
+  <InputTag v-model="emptyTags" size="large" placeholder="空态" />
+  <InputTag v-model="singleTags" size="large" />
+</template>
+```
+
+### 限制展示数量
+
+`maxTagCount` 只限制展示数量，多出的标签折叠为 `+N...`，不限制可创建数量，也不阻止删除。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['one', 'two', 'three', 'four']);
+</script>
+<template>
+<InputTag v-model="tags" :max-tag-count="2" allow-clear />
+</template>
+```
+
+### 前缀和后缀
+
+`prefix` 用于输入框内部的前置装饰，`suffix` 用于后置内容；已有内置清空按钮时两者会共同占用右侧空间。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['Vue', 'TypeScript']);
+</script>
+<template>
+<InputTag v-model="tags" allow-clear>
+    <template #prefix>标签</template>
+    <template #suffix>{{ tags.length }}</template>
+  </InputTag>
+</template>
+```
+
+### 唯一值
+
+`uniqueValue` 阻止创建已存在的标签，比较基于归一化后的 `value`，字符串与数字严格区分（`1` 与 `'1'` 视为不同）。被阻止时仍会触发 `press-enter`，输入内容保留。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+import type { TagData } from 'x-next';
+
+const tags = ref<Array<string | number | TagData>>(['Vue', 1, { value: 'id-a', label: '对象 A' }]);
+</script>
+<template>
+<InputTag v-model="tags" unique-value placeholder="重复值不会再次创建" />
+</template>
+```
+
+### 受控输入值
+
+`v-model` 控制标签数组，`v-model:input-value` 控制输入框中的未提交草稿。草稿受控时，组件的输入只上报变更，由使用方决定是否回写。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag, Button } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['Vue']);
+const draft = ref('草稿');
+const reset = () => {
+  tags.value = ['Vue'];
+  draft.value = '草稿';
+};
+</script>
+<template>
+<InputTag v-model="tags" v-model:input-value="draft" placeholder="输入后回车" allow-clear />
+  <p role="status">标签：{{ tags.join('、') || '无' }}；草稿：{{ draft || '空' }}</p>
+  <Button size="small" @click="reset">重置为初始值</Button>
+</template>
+```
+
+### 保留输入内容
+
+`retainInputValue` 默认 `false`，即创建标签后和失焦时都会清空草稿。传 `true` 两者都保留，也可用对象分别控制 `create` 与 `blur`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['draft']);
+const draft = ref('');
+const blurDraft = ref('');
+const createDraft = ref('');
+</script>
+<template>
+<InputTag v-model="tags" v-model:input-value="draft" retain-input-value />
+  <InputTag
+    v-model="tags"
+    v-model:input-value="blurDraft"
+    :retain-input-value="{ create: false, blur: true }"
+  />
+  <InputTag
+    v-model="tags"
+    v-model:input-value="createDraft"
+    :retain-input-value="{ create: true, blur: false }"
+  />
+</template>
+```
+
+### 对象标签
+
+对象标签用 `fieldNames` 映射 `value`、`label`、`closable`、`tagProps` 四个字段。`label` 缺失时回退为 `String(value)`；缺少有效 `value` 的对象会被忽略。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+import type { InputTagFieldNames, TagData } from 'x-next';
+
+const tags = ref<Array<string | number | TagData>>([
+  { id: 'a', name: '设计', canRemove: false },
+  { id: 'b', name: '研发', canRemove: true },
+]);
+const fieldNames: InputTagFieldNames = {
+  value: 'id',
+  label: 'name',
+  closable: 'canRemove',
+};
+// Enter 新建的字符串标签只有 value，需要回退取值
+const formatTag = (data: TagData) => `#${data.name ?? data.label ?? data.value}`;
+</script>
+<template>
+<InputTag v-model="tags" :field-names="fieldNames" :format-tag="formatTag" allow-clear />
+</template>
+```
+
+### 自定义标签
+
+`tag` 插槽接收归一化后的 `data`，可自定义标签渲染；对象标签与新建字符串标签混用时同样需要回退取值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+import type { InputTagFieldNames, TagData } from 'x-next';
+
+const tags = ref<Array<string | number | TagData>>([{ id: 'a', name: '设计' }]);
+const fieldNames: InputTagFieldNames = { value: 'id', label: 'name' };
+</script>
+<template>
+<InputTag v-model="tags" :field-names="fieldNames">
+    <template #tag="{ data }">
+      {{ data.name ?? data.label ?? data.value }}
+    </template>
+  </InputTag>
+</template>
+```
+
+### 标签不换行
+
+`tagNowrap` 让单个标签的内容不换行，标签列表本身仍可换行。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['这是一段很长很长的标签内容，用于检查不换行时的显示效果']);
+</script>
+<template>
+<InputTag v-model="tags" tag-nowrap />
+</template>
+```
+
+### 标签样式
+
+`tagProps` 透传给内部 Tag，可设置内置颜色、自定义颜色与边框。删除权限只收紧不放开：顶层 `closable: false` 时 `tagProps.closable: true` 无效；顶层可关闭时 `tagProps.closable: false` 会隐藏关闭按钮并让键盘删除跳过该项。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+import type { TagData } from 'x-next';
+
+const tags = ref<Array<string | number | TagData>>([
+  { value: 'blue', label: '内置蓝色', tagProps: { color: 'blue', bordered: true } },
+  { value: 'custom', label: '自定义颜色', tagProps: { color: '#7c3aed' } },
+  { value: 'narrow', label: 'tagProps 禁止删除', closable: true, tagProps: { color: 'green', closable: false } },
+  { value: 'locked', label: '顶层禁止删除', closable: false, tagProps: { color: 'red', closable: true } },
+]);
+</script>
+<template>
+<InputTag v-model="tags" allow-clear />
+</template>
+```
+
+### 事件回调
+
+创建标签依次触发 `change`、`press-enter` 和清空草稿的 `input-value-change`，因此示例用日志列表保留完整顺序。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+import type { TagData } from 'x-next';
+
+const tags = ref(['日志']);
+const logs = ref<string[]>([]);
+let sequence = 0;
+const append = (message: string) => {
+  logs.value = [...logs.value, `${++sequence}. ${message}`].slice(-12);
+};
+const handleChange = (value: Array<string | number | TagData>, event: Event) => {
+  append(`change (${event.type})：${value.length} 个标签`);
+};
+const handleInputValueChange = (value: string, event: Event) => {
+  append(`input-value-change (${event.type})：${value || '空'}`);
+};
+const handlePressEnter = (value: string, event: KeyboardEvent) => {
+  append(`press-enter (${event.type})：${value}`);
+};
+const handleRemove = (value: string | number, event: Event) => {
+  append(`remove (${event.type})：${value}`);
+};
+const handleClear = (event: MouseEvent) => {
+  append(`clear (${event.type})`);
+};
+</script>
+<template>
+<InputTag
+    v-model="tags"
+    allow-clear
+    @change="handleChange"
+    @input-value-change="handleInputValueChange"
+    @press-enter="handlePressEnter"
+    @remove="handleRemove"
+    @clear="handleClear"
+  />
+  <div role="status">
+    <div v-for="log in logs" :key="log">{{ log }}</div>
+  </div>
+</template>
+```
+
+### 方法
+
+`focus`、`blur` 通过组件实例调用。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag, Button } from 'x-next';
+import { ref } from 'vue';
+import type { InputTagInstance } from 'x-next';
+
+const tags = ref(['Vue', 'TypeScript']);
+const inputTagRef = ref<InputTagInstance>();
+</script>
+<template>
+<InputTag ref="inputTagRef" v-model="tags" />
+  <Button @click="inputTagRef?.focus()">聚焦</Button>
+  <Button @click="inputTagRef?.blur()">失焦</Button>
+</template>
+```
+
+### 原生属性
+
+`id`、`name`、`maxlength`、`aria-*` 等原生属性会落到内部 input，而不是外层容器；表单类事件（`input`、`keydown` 等）同样绑定在原生 input 上。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { InputTag } from 'x-next';
+import { ref } from 'vue';
+
+const tags = ref(['Vue']);
+const draft = ref('');
+import type { InputHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "id": "input-tag-native", "name": "keywords", "maxlength": "12", "aria-label": "关键词标签输入" } satisfies InputHTMLAttributes;
+</script>
+<template>
+<InputTag :input-attrs="nativeAttrs1"
+    v-model="tags"
+    v-model:input-value="draft"
+
+
+
+
+  />
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, InputTag, Space, Button } from 'x-next';
+const tags = ref(['Vue', 'TypeScript']);
+
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ tags: [] as string[] });
+const formRules: Record<string, FieldRule[]> = {
+  tags: [{ type: 'array', required: true, message: '至少添加一个标签' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="tags" label="标签">
+      <InputTag v-model="formState.tags" placeholder="请输入标签后回车" />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+### 已知交互说明
+
+- 输入为空时按 Backspace 删除最后一个**可关闭**标签；末尾标签不可关闭时继续向前查找。
+- 输入内容为空时按 Enter 不创建标签，也不触发 `press-enter`。
+- `uniqueValue` 比较归一化后的 `value`，基于严格相等，数字 `1` 与字符串 `'1'` 视为不同值。
+- `maxTagCount` 只影响展示，折叠出的 `+N...` 不可关闭；Backspace 删除的是最后一个真实可关闭标签。
+- 对象标签缺少 `value`（或 `fieldNames.value` 字段）时会被忽略，不会渲染，删除时也会跳过。
+- 标签删除权限只收紧不放开：顶层 `closable` 是总开关，`tagProps.closable: false` 可在其基础上禁用删除。
+- 关闭按钮的无障碍名称包含各标签文案（如“关闭标签 Vue”），便于屏幕阅读器区分。
+- 用键盘激活关闭按钮或清空按钮后，焦点会回到输入框，便于继续输入。
+- 直接使用 InputTag 时，输入法组合结束（`compositionend`）同样会触发 FormItem 的 `input` 校验，与普通输入一致。
+- 同名事件回调：`inputAttrs` 与组件透传的 `attrs` 都提供同一事件（如 `onInput`）时，`inputAttrs` 优先；组件内部处理器仍会执行。
+
+
+### TagData
+
+| 字段 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `value` | 标签值，缺失时整项被忽略 | `string \| number` | `-` |
+| `label` | 标签内容，缺失时回退为 `String(value)` | `string` | `-` |
+| `closable` | 是否可删除 | `boolean` | `true` |
+| `tagProps` | 透传给内部 Tag 的属性 | `TagProps` | `-` |
+
+
+### fieldNames
+
+| 字段 | 说明 | 默认值 |
+| --- | --- | --- |
+| `value` | 取值字段名 | `'value'` |
+| `label` | 内容字段名 | `'label'` |
+| `closable` | 删除开关字段名 | `'closable'` |
+| `tagProps` | Tag 属性字段名 | `'tagProps'` |
+
+
+### 关联能力
+
+- 多选 Select 内部复用 InputTag 渲染标签，`maxTagCount`、`tagNowrap`、标签删除等行为一致。
+- 需要校验、错误提示和布局时配合 `x-form` / `x-form-item` 使用。
+- `InputTag`、`Input`、`Textarea` 同属输入组件族，尺寸与状态命名一致。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./input-tag-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。