x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/form.md

@@ -0,0 +1,454 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Form AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Form, FormItem`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./form-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/form`（包含 base.css、form.css、grid.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/form.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./form-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+承载数据录入、校验和提交，是业务系统里最核心的交互容器。
+
+
+### 何时使用
+
+- 需要把多个输入控件组成一次提交，并统一尺寸、禁用和校验反馈。
+- 需要必填、格式、数值范围或异步业务校验。
+- 需要动态字段、嵌套数据、重置初始值或展示服务端错误。
+
+`validate()` / `validateField()` 成功返回 `undefined`，失败返回字段错误对象。通过返回值判断结果，不使用 try/catch 判断业务校验失败。`resetFields()` 恢复字段挂载时的初始快照，`clearValidate()` 只清理状态。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Checkbox, Button } from 'x-next';
+import { reactive } from 'vue';
+
+const form = reactive({ name: '', post: '', isRead: false });
+const handleSubmit = ({ values, errors }: { values: Record<string, unknown>; errors?: unknown }) => {
+  console.log(values, errors);
+};
+</script>
+<template>
+<Form :model="form" @submit="handleSubmit">
+    <FormItem field="name" tooltip="用于展示在业务列表中" label="名称" required>
+      <Input v-model="form.name" placeholder="请输入名称" />
+    </FormItem>
+    <FormItem field="post" label="职位">
+      <Input v-model="form.post" placeholder="请输入职位" />
+    </FormItem>
+    <FormItem field="isRead">
+      <Checkbox v-model="form.isRead">我已阅读并同意</Checkbox>
+    </FormItem>
+    <FormItem>
+      <Button type="primary" html-type="submit">提交</Button>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 布局
+
+inline 布局的控件列默认宽度为 200px，并在空间不足时换行；可通过 `wrapperColStyle` 调整宽度。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Radio, Form, FormItem, Input } from 'x-next';
+import { reactive, ref } from 'vue';
+
+const layout = ref<'horizontal' | 'vertical' | 'inline'>('horizontal');
+const form = reactive({ name: '', post: '' });
+</script>
+<template>
+<RadioGroup v-model="layout" type="button">
+    <Radio value="horizontal">horizontal</Radio>
+    <Radio value="vertical">vertical</Radio>
+    <Radio value="inline">inline</Radio>
+  </RadioGroup>
+  <Form :model="form" :layout="layout">
+    <FormItem field="name" label="用户名">
+      <Input v-model="form.name" />
+    </FormItem>
+    <FormItem field="post" label="岗位">
+      <Input v-model="form.post" />
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 表单校验
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, InputNumber, Select, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+
+const formRef = ref();
+const form = reactive({ name: '', age: 18, section: '' });
+const rules: Record<string, import('x-next').FieldRule[]> = {
+  name: [
+    { required: true, message: '请输入用户名' },
+    { minLength: 3, message: '用户名至少 3 个字符' },
+  ],
+  age: [{ type: 'number', max: 120, message: '年龄不能超过 120' }],
+  section: [{ match: /section one/, message: '请选择 Section One' }],
+};
+const sectionOptions = [
+  { label: 'Section One', value: 'section one' },
+  { label: 'Section Two', value: 'section two' },
+];
+const handleSubmit = ({ values, errors }: { values: Record<string, unknown>; errors?: unknown }) => {
+  console.log(values, errors);
+};
+</script>
+<template>
+<Form ref="formRef" :model="form" :rules="rules" scroll-to-first-error @submit="handleSubmit">
+    <FormItem field="name" label="用户名" :validate-trigger="['change', 'input']">
+      <Input v-model="form.name" placeholder="至少 3 个字符" />
+    </FormItem>
+    <FormItem field="age" label="年龄">
+      <InputNumber v-model="form.age" :min="0" :max="200" />
+    </FormItem>
+    <FormItem field="section" label="部门">
+      <Select v-model="form.section" :options="sectionOptions" allow-clear />
+    </FormItem>
+    <FormItem>
+      <Button type="primary" html-type="submit">提交校验</Button>
+      <Button @click="formRef?.resetFields()">重置</Button>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 表单方法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Button } from 'x-next';
+const status = ref<'validating' | 'success' | 'warning' | 'error'>('success');
+
+import { reactive, ref } from 'vue';
+
+const formRef = ref();
+const form = reactive({ username: '', email: '' });
+const rules: Record<string, import('x-next').FieldRule[]> = {
+  username: [{ required: true, message: '请输入用户名' }],
+  email: [{ type: 'email', message: '邮箱格式不正确' }],
+};
+const setServerError = () => {
+  formRef.value?.setFields({
+    email: { status: 'error', message: '服务端返回：邮箱已被占用' },
+  });
+};
+</script>
+<template>
+<Form ref="formRef" :model="form" :rules="rules">
+    <FormItem field="username" label="用户名">
+      <Input v-model="form.username" />
+    </FormItem>
+    <FormItem field="email" label="邮箱">
+      <Input v-model="form.email" />
+    </FormItem>
+    <FormItem>
+      <Button @click="formRef?.validate()">validate</Button>
+      <Button @click="setServerError">setFields</Button>
+      <Button @click="formRef?.clearValidate()">clearValidate</Button>
+      <Button @click="formRef?.resetFields()">resetFields</Button>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 状态与反馈
+
+### 校验状态的视觉支持范围
+
+校验失败时，所有控件都会在 FormItem 上展示错误文案与错误色（`x-form--item-error`）；`feedback` 开关控制是否额外展示反馈图标。
+
+控件自身的错误描边支持范围如下：
+
+| 控件 | 控件级错误描边 | 反馈图标 |
+| --- | --- | --- |
+| Input | 支持 | 支持 |
+| Select / InputTag / InputNumber | 支持 | 支持 |
+| DatePicker / TimePicker（含范围形态） | 支持 | 支持 |
+| Textarea | 支持 | 不支持（右下角为字数统计，无图标位） |
+| Radio / RadioGroup / Checkbox / CheckboxGroup | 不支持（仅 FormItem 文案与错误色） | 不支持 |
+| Slider / Switch | 不支持（仅 FormItem 文案与错误色） | 不支持 |
+
+Radio、Checkbox、Slider、Switch 属于无输入边框的控件，参考 Arco Design Vue 的行为，不额外添加控件级错误描边，避免与"选中态"视觉混淆。Textarea 的右下角用于字数统计，同样不放置反馈图标。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, InputTag, DatePicker, TimePicker } from 'x-next';
+import { reactive, ref } from 'vue';
+
+const status = ref<'validating' | 'success' | 'warning' | 'error'>('success');
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('medium');
+const form = reactive({ name: '', tags: [], date: '2026-09-30', time: '09:30:00' });
+</script>
+<template>
+<Form :model="form" :size="size">
+    <FormItem
+      field="name"
+      label="名称"
+      help="当前状态由 validateStatus 手动控制"
+      extra="开启 feedback 后展示反馈图标"
+      :validate-status="status"
+      feedback
+    >
+      <Input v-model="form.name" />
+    </FormItem>
+    <FormItem field="tags" label="标签" :validate-status="status" feedback>
+      <InputTag v-model="form.tags" />
+    </FormItem>
+    <FormItem field="date" label="日期" :validate-status="status" feedback>
+      <DatePicker v-model="form.date" allow-clear />
+    </FormItem>
+    <FormItem field="time" label="时间" :validate-status="status" feedback>
+      <TimePicker v-model="form.time" allow-clear />
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 全局禁用
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Checkbox } from 'x-next';
+import { reactive } from 'vue';
+
+const form = reactive({ name: 'Locked user', isRead: true });
+</script>
+<template>
+<Form :model="form" disabled>
+    <FormItem field="name" label="用户名">
+      <Input v-model="form.name" />
+    </FormItem>
+    <FormItem field="isRead">
+      <Checkbox v-model="form.isRead">已确认</Checkbox>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 帮助信息和插槽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input } from 'x-next';
+import { reactive } from 'vue';
+
+const form = reactive({ name: '', post: '' });
+</script>
+<template>
+<Form :model="form">
+    <FormItem field="name" required validate-trigger="input">
+      <template #label>
+        <span>登录名</span>
+      </template>
+      <Input v-model="form.name" />
+      <template #extra>
+        <span>用于后台账号展示</span>
+      </template>
+    </FormItem>
+    <FormItem field="post" label="岗位" required>
+      <Input v-model="form.post" />
+      <template #help>
+        <span>自定义帮助信息会展示在控件下方</span>
+      </template>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 嵌套字段
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Select } from 'x-next';
+import { reactive, ref } from 'vue';
+
+const formRef = ref();
+const form = reactive({
+  user: { name: '', email: '' },
+  members: ['pm'],
+});
+const rules: Record<string, import('x-next').FieldRule[]> = {
+  'user.name': [{ required: true, message: '请输入姓名' }],
+  'user.email': [{ type: 'email', message: '邮箱格式不正确' }],
+  members: [{ type: 'array', minLength: 2, message: '至少选择 2 个成员' }],
+};
+const memberOptions = [
+  { label: '产品', value: 'pm' },
+  { label: '设计', value: 'design' },
+  { label: '前端', value: 'frontend' },
+];
+const handleSubmit = ({ values, errors }: { values: Record<string, unknown>; errors?: unknown }) => {
+  console.log(values, errors);
+};
+</script>
+<template>
+<Form ref="formRef" :model="form" :rules="rules" @submit="handleSubmit">
+    <FormItem field="user.name" label="姓名">
+      <Input v-model="form.user.name" />
+    </FormItem>
+    <FormItem field="user.email" label="邮箱">
+      <Input v-model="form.user.email" />
+    </FormItem>
+    <FormItem field="members" label="成员">
+      <Select v-model="form.members" :options="memberOptions" multiple />
+    </FormItem>
+  </Form>
+</template>
+```
+
+### 异步校验与过期结果
+
+输入 `admin` 后失焦会得到占用提示；等待时继续修改并失焦，旧请求不会覆盖最新字段状态。也可以在请求完成前重置。
+
+异步 validator 返回 Promise，通过 `addError(message)` 报告错误，再正常完成 Promise。不要把 reject 当作字段错误。`validating` 在等待期间显示；清理状态、重置、切换字段或卸载后，旧请求不会重新写入错误。每次 `validate()` 返回该次校验的结果；等待提交期间修改模型或字段结构会取消旧的提交事件，可重新提交新值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FieldRule, FormInstance } from 'x-next';
+const formRef = ref<FormInstance>();
+const form = reactive({ username: '' });
+const rules: Record<string, FieldRule[]> = {
+  username: [
+    { required: true, message: '请输入用户名' },
+    {
+      validator: async (value, addError) => {
+        await new Promise((resolve) => setTimeout(resolve, 600));
+        if (value === 'admin') addError('admin 已被占用，请换一个名称');
+      },
+    },
+  ],
+};
+</script>
+<template>
+<Form ref="formRef" :model="form" :rules="rules">
+    <FormItem field="username" label="用户名" validate-trigger="blur" feedback>
+      <Input v-model="form.username" placeholder="尝试 admin" allow-clear />
+    </FormItem>
+    <FormItem>
+      <Button @click="formRef?.validateField('username')">校验当前字段</Button>
+      <Button @click="formRef?.resetFields()">重置</Button>
+    </FormItem>
+  </Form>
+</template>
+```
+
+### noStyle 与动态字段
+
+`noStyle` 子项参与校验，错误展示在外层 FormItem。通过 `v-if` 卸载会注销字段并清理其父级错误；模型中的值仍由业务保存。`v-show` 只隐藏 DOM，字段仍参与校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, Form, FormItem, Input, Button } from 'x-next';
+const status = ref<'validating' | 'success' | 'warning' | 'error'>('success');
+
+import { reactive, ref } from 'vue';
+const visible = ref(true);
+const formRef = ref();
+const form = reactive({ email: '' });
+const result = ref('等待校验');
+const validate = async () => {
+  const errors = await formRef.value.validate();
+  result.value = errors ? '邮箱未填写' : '校验通过';
+};
+</script>
+<template>
+<Checkbox v-model="visible" @change="result = visible ? '字段已展开' : '字段已隐藏'">显示邮箱字段</Checkbox>
+  <Form ref="formRef" :model="form">
+    <FormItem label="联系方式">
+      <FormItem v-if="visible" field="email" no-style required>
+        <Input v-model="form.email" placeholder="先校验，再隐藏字段" />
+      </FormItem>
+      <span v-else>当前没有邮箱字段</span>
+    </FormItem>
+    <FormItem><Button @click="validate">校验</Button></FormItem>
+  </Form>
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+### 自动标签、帮助与错误关联
+
+单个原生输入自动获得稳定 ID，并与标签的 `for` 关联。多个输入、选择组、评分、滑块和时间区间通过 `aria-labelledby` 共享标签；`noStyle` 字段继承外层标签。帮助、额外说明和当前错误通过 `aria-describedby` 关联，校验失败时同步 `aria-invalid` 和 `aria-errormessage`，清除校验后恢复帮助说明。
+
+隐藏标签的字段应显式提供 `aria-label`。自定义控件需要自行绑定原生 ID 和 ARIA 属性；自动关联覆盖 x-next 内置表单控件。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input, Textarea, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance } from 'x-next';
+const form = reactive({ name: '', note: '' });
+const formRef = ref<FormInstance>();
+const result = ref('点击姓名标签可聚焦输入框');
+const validate = async () => {
+  result.value = (await formRef.value!.validate()) ? '请补全必填项' : '校验通过';
+};
+</script>
+<template>
+<Form ref="formRef" :model="form">
+    <FormItem field="name" label="姓名" required help="填写真实姓名" extra="用于联系和通知">
+      <Input v-model="form.name" />
+    </FormItem>
+    <FormItem field="note" label="备注" help="可选，支持多行">
+      <Textarea v-model="form.note" />
+    </FormItem>
+    <Button @click="validate">校验姓名</Button>
+    <p>{{ result }}</p>
+  </Form>
+</template>
+```
+
+### 手动标签与原生输入关联
+
+显式 `labelAttrs.for`、原生 `id` 和 ARIA 名称会保留；额外 `aria-describedby` 与 Form 描述合并。重复渲染时请给自定义 ID 使用独立值。Form 的 `id` 前缀用于字段包装层及 `scrollToField`，与原生输入 ID 分开。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Input } from 'x-next';
+import { reactive } from 'vue';
+const form = reactive({ name: '' });
+import type { InputHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "id": "profile-name", "aria-required": "true", "aria-describedby": "profile-name-hint" } satisfies InputHTMLAttributes;
+</script>
+<template>
+<Form :model="form">
+    <FormItem field="name" label="姓名" :label-attrs="{ for: 'profile-name' }" required>
+      <Input :input-attrs="nativeAttrs1"  v-model="form.name"   />
+      <template #extra><span id="profile-name-hint">请填写用于展示的姓名。</span></template>
+    </FormItem>
+  </Form>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./form-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。