docs(agents): add design references

2026-08-10 23:34:28 +08:00
parent a2383fc8a1
commit 72a83f5fcd
86 changed files with 8889 additions and 0 deletions
--- a/.agents/skills/arco-design-vue/references/components/data-entry/form.md
+++ b/.agents/skills/arco-design-vue/references/components/data-entry/form.md
@@ -0,0 +1,206 @@
+---
+name: arco-vue-form
+description: "Arco Design Vue 表单 Form 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-form>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 表单 Form
+
+## 简介
+
+表单的基本用法。
+
+## 基本用法
+
+```vue
+<template>
+  <a-form :model="form" :style="{ width: '600px' }" @submit="handleSubmit">
+    <a-form-item field="name" tooltip="Please enter username" label="Username">
+      <a-input
+        v-model="form.name"
+        placeholder="please enter your username..."
+      />
+    </a-form-item>
+    <a-form-item field="post" label="Post">
+      <a-input v-model="form.post" placeholder="please enter your post..." />
+    </a-form-item>
+    <a-form-item field="isRead">
+      <a-checkbox v-model="form.isRead"> I have read the manual </a-checkbox>
+    </a-form-item>
+    <a-form-item>
+      <a-button html-type="submit">Submit</a-button>
+    </a-form-item>
+  </a-form>
+  {{ form }}
+</template>
+
+<script>
+import { reactive } from 'vue';
+
+export default {
+  setup() {
+    const form = reactive({
+      name: '',
+      post: '',
+      isRead: false,
+    });
+    const handleSubmit = (data) => {
+      console.log(data);
+    };
+
+    return {
+      form,
+      handleSubmit,
+    };
+  },
+};
+</script>
+```
+
+## API
+
+### `<form>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|model **(必填)**|表单数据对象|`object`|`-`||
+|layout|表单的布局方式，包括水平、垂直、多列|`'horizontal' \| 'vertical' \| 'inline'`|`'horizontal'`||
+|size|表单控件的尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`||
+|label-col-props|标签元素布局选项。参数同 `<col>` 组件一致|`object`|` span: 5, offset: 0 `||
+|wrapper-col-props|表单控件布局选项。参数同 `<col>` 组件一致|`object`|` span: 19, offset: 0 `||
+|label-align|标签的对齐方向|`'left' \| 'right'`|`'right'`||
+|disabled|是否禁用表单|`boolean`|`-`||
+|rules|表单项校验规则|`Record<string, FieldRule \| FieldRule[]>`|`-`||
+|auto-label-width|是否开启自动标签宽度，仅在 `layout="horizontal"` 下生效。|`boolean`|`false`|2.13.0|
+|id|表单 `id` 属性和表单控件 `id` 前缀|`string`|`-`||
+|scroll-to-first-error|验证失败后滚动到第一个错误字段|`boolean`|`false`|2.51.0|
+
+### `<form>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|submit|表单提交时触发|data: `{values: Record<string, any>; errors: Record<string, ValidatedError> \| undefined}`<br>ev: `Event`|
+|submit-success|验证成功时触发|values: `Record<string, any>`<br>ev: `Event`|
+|submit-failed|验证失败时触发|data: `{values: Record<string, any>; errors: Record<string, ValidatedError>}`<br>ev: `Event`|
+
+### `<form>` 方法
+
+|方法名|描述|参数|返回值|版本|
+|---|---|---|---|:---|
+|validate|校验全部表单数据|callback: `(errors: undefined \| Record<string, ValidatedError>) => void`|Promise<undefined \| Record<string, ValidatedError>>||
+|validateField|校验部分表单数据|field: `string \| string[]`<br>callback: `(errors: undefined \| Record<string, ValidatedError>) => void`|Promise<undefined \| Record<string, ValidatedError>>||
+|resetFields|重置表单数据|field: `string \| string[]`|-||
+|clearValidate|清除校验状态|field: `string \| string[]`|-||
+|setFields|设置表单项的值和状态|data: `Record<string, FieldData>`|-||
+|scrollToField|滚动到指定表单项|field: `string`|-|2.51.0|
+
+### `<form-item>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|field|表单元素在数据对象中的path（数据项必填）|`string`|`''`||
+|label|标签的文本|`string`|`-`||
+|tooltip|提示内容|`string`|`-`|2.41.0|
+|show-colon|是否显示冒号|`boolean`|`false`||
+|no-style|是否去除样式|`boolean`|`false`||
+|disabled|是否禁用|`boolean`|`-`||
+|help|帮助文案|`string`|`-`||
+|extra|额外显示的文案|`string`|`-`||
+|required|是否必须填写|`boolean`|`false`||
+|asterisk-position|可选择将星号置于 label 前/后|`'start' \| 'end'`|`'start'`|2.41.0|
+|rules|表单项校验规则（优先级高于 form 的 rules）|`FieldRule \| FieldRule[]`|`-`||
+|validate-status|校验状态|`'success' \| 'warning' \| 'error' \| 'validating'`|`-`||
+
+> 仅列出常用项，低频属性按需查阅官方 API。
+
+### `<form-item>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|label|标签|-|
+|help|帮助信息|-|
+|extra|额外内容|-|
+
+### 类型定义
+
+### FieldRule
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|type|校验的值的类型，默认为 `'string'`|`'string'    \| 'number'    \| 'boolean'    \| 'array'    \| 'object'    \| 'email'    \| 'url'    \| 'ip'`|`-`|
+|required|是否必填|`boolean`|`false`|
+|message|校验失败时展示的信息|`string`|`-`|
+|length|校验长度（string, array）|`number`|`-`|
+|maxLength|最大长度（string）|`number`|`-`|
+|minLength|最小长度（string）|`number`|`-`|
+|match|匹配校验（string）|`RegExp`|`-`|
+|uppercase|大写（string）|`boolean`|`false`|
+|lowercase|小写（string）|`boolean`|`false`|
+|min|最小值（number）|`number`|`-`|
+|max|最大值（number）|`number`|`-`|
+|equal|校验数值（number）|`number`|`-`|
+
+> 仅列出常用项，低频属性按需查阅官方 API。
+
+### FieldData
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|value|字段的值|`any`|`-`|
+|status|字段的状态|`ValidateStatus`|`-`|
+|message|字段的错误信息|`string`|`-`|
+
+### ValidatedError
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|label|标签的文本|`string`|`-`|2.18.0|
+|field|字段名|`string`|`-`||
+|value|字段值|`any`|`-`||
+|type|字段类型|`string`|`-`||
+|isRequiredError|是否为 `required` 错误|`boolean`|`false`||
+|message|错误信息|`string`|`-`||
+
+### FormItemEventHandler
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|onChange|onChange|`(ev?: Event) => void`|`-`|
+|onInput|onInput|`(ev?: Event) => void`|`-`|
+|onFocus|onFocus|`(ev?: Event) => void`|`-`|
+|onBlur|onBlur|`(ev?: Event) => void`|`-`|
+
+### useFormItem
+
+```ts
+const useFormItem = (data: {
+  size?: Ref<Size | undefined>;
+  disabled?: Ref<boolean>;
+  error?: Ref<boolean>;
+}) => {
+  mergedSize:Ref<Size>;
+  mergedDisabled:Ref<boolean>;
+  mergedError:Ref<boolean>;
+  feedback:Ref<string>;
+  eventHandlers:Ref<FormItemEventHandler>;
+}
+```
+
+## 常用模式
+
+- **表单布局**：表单支持三种布局方式： `horizontal` - 水平排列 **（默认）**， `vertical` - 垂直排列， `inline` - 行内排列。
+- **额外信息和帮助信息**：可以使用 `extra` 添加额外信息。如果需要在外部自定义校验信息，可以使用 `help` 属性或插槽。设置 `help` 时校验信息会被屏蔽。
+- **嵌套数据**：展示了多种表单项嵌套的方式。表单项组件默认会将表单项状态和事件绑定到第一子组件，如果想要使用表单项进行布局设置，请设置 `:merge-props="false"` 以关闭绑定，或者使用函数指定需要绑定的数据。
+- **栅格布局**：展示了使用栅格布局的方式。可以使用 `label-col-flex` 属性指定标签的具体宽度。
+- **自动标签宽度**：设置 `auto-label-width` 开启自动标签宽度。仅在 `layout="horizontal"` 布局下生效。_* 目前仅在首次加载后生效。_
+- **验证表单**：展示了表单校验的使用方法。
+- **验证表单2**：展示了表单校验`rules`使用在`a-form`上的使用方法，以及可以直接校验`email`、`ip`、`url`
+- **自定义表单校验状态**：开启 `feedback` 可以让部分输入组件展示当前状态信息
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 需要进入表单校验或提交流程的控件，优先放在 `a-form-item` 中并绑定明确的 `field`。
+- 输入值优先使用 `v-model`；范围、弹窗类状态使用组件文档中的命名 `v-model:*`。