king-design-analyzer 1.0.0

package/components/form.json

@@ -0,0 +1,638 @@
+{
+    "id": "form",
+    "name": "Form",
+    "displayName": "表单",
+    "category": "form",
+    "description": "用于数据采集和验证的表单组件，支持多种布局方式、丰富的内置验证规则、自定义验证规则，以及表单项的统一管理。",
+    "importStatement": "import { Form, FormItem } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "labelWidth",
+            "description": "定义所有子孙 FormItem 组件的 label 宽度",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Form :labelWidth=\"120\">"
+        },
+        {
+            "name": "layout",
+            "description": "指定表单布局方式",
+            "type": {
+                "raw": "\"horizontal\" | \"vertical\" | \"inline\"",
+                "kind": "union",
+                "unionTypes": [
+                    "horizontal",
+                    "vertical",
+                    "inline"
+                ]
+            },
+            "required": false,
+            "default": "\"horizontal\"",
+            "allowedValues": [
+                {
+                    "value": "horizontal",
+                    "label": "水平布局，label 在左，表单项在右",
+                    "isDefault": true
+                },
+                {
+                    "value": "vertical",
+                    "label": "垂直布局，label 在上，表单项在下"
+                },
+                {
+                    "value": "inline",
+                    "label": "内联布局，所有表单项在一行显示"
+                }
+            ],
+            "usageExample": "<Form layout=\"vertical\">"
+        },
+        {
+            "name": "starOnRequired",
+            "description": "当 FormItem 必填时，是否在 label 前面展示 *",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Form starOnRequired>"
+        },
+        {
+            "name": "size",
+            "description": "定义表单之间的间隔大小",
+            "type": {
+                "raw": "\"default\" | \"small\" | \"mini\"",
+                "kind": "union",
+                "unionTypes": [
+                    "default",
+                    "small",
+                    "mini"
+                ]
+            },
+            "required": false,
+            "default": "\"default\"",
+            "allowedValues": [
+                {
+                    "value": "default",
+                    "label": "默认间隔",
+                    "isDefault": true
+                },
+                {
+                    "value": "small",
+                    "label": "小间隔"
+                },
+                {
+                    "value": "mini",
+                    "label": "迷你间隔"
+                }
+            ],
+            "usageExample": "<Form size=\"small\">"
+        }
+    ],
+    "events": [
+        {
+            "name": "submit",
+            "vueEventName": "@submit",
+            "description": "当表单提交并且所有规则都验证通过时触发",
+            "payload": [
+                {
+                    "name": "event",
+                    "type": "Event",
+                    "description": "原生表单提交事件对象"
+                }
+            ],
+            "usageExample": "<Form @submit=\"handleSubmit\">",
+            "handlerExample": "const handleSubmit = (e: Event) => {\n  console.log('表单验证通过，提交中...');\n};"
+        }
+    ],
+    "methods": [
+        {
+            "name": "validate",
+            "description": "验证表单所有规则",
+            "params": [],
+            "returnType": "Promise<boolean>",
+            "usageExample": "const formRef = ref<InstanceType<typeof Form>>();\n\nconst handleSubmit = async () => {\n  const valid = await formRef.value?.validate();\n  if (valid) {\n    console.log('验证通过');\n  }\n};"
+        },
+        {
+            "name": "reset",
+            "description": "重置表单验证状态",
+            "params": [],
+            "returnType": "void",
+            "usageExample": "formRef.value?.reset();"
+        },
+        {
+            "name": "getFirstInvalidFormItem",
+            "description": "获取第一条出错的 FormItem",
+            "params": [],
+            "returnType": "FormItem",
+            "usageExample": "const firstError = formRef.value?.getFirstInvalidFormItem();"
+        },
+        {
+            "name": "getAllInvalidFormItems",
+            "description": "获取所有校验失败的 FormItem",
+            "params": [],
+            "returnType": "FormItem[]",
+            "usageExample": "const allErrors = formRef.value?.getAllInvalidFormItems();"
+        }
+    ],
+    "staticMethods": [
+        {
+            "name": "addMethod",
+            "description": "添加全局验证规则，在所有 FormItem 中可以通过规则名使用",
+            "params": [
+                {
+                    "name": "name",
+                    "type": "string",
+                    "description": "规则名称，不能重复"
+                },
+                {
+                    "name": "method",
+                    "type": "(value: any, param: any) => boolean | string | Promise<boolean | string>",
+                    "description": "验证函数，返回 true 表示验证通过，false 或字符串表示失败"
+                },
+                {
+                    "name": "message",
+                    "type": "string | ((value: any, param: any) => string)",
+                    "description": "验证失败时的错误提示文案",
+                    "optional": true
+                },
+                {
+                    "name": "className",
+                    "type": "string | ((value: any, param: any) => string)",
+                    "description": "验证失败时添加的类名",
+                    "optional": true
+                }
+            ],
+            "returnType": "void",
+            "usageExample": "Form.addMethod('phone', (value: string) => {\n  return /^1[3-9]\\d{9}$/.test(value) || '请输入正确的手机号';\n});"
+        }
+    ],
+    "builtinRules": [
+        {
+            "name": "required",
+            "description": "必须填写",
+            "usage": ":rules=\"{required: true}\""
+        },
+        {
+            "name": "digits",
+            "description": "请输入数字",
+            "usage": ":rules=\"{digits: true}\""
+        },
+        {
+            "name": "email",
+            "description": "请输入正确的邮箱地址",
+            "usage": ":rules=\"{email: true}\""
+        },
+        {
+            "name": "url",
+            "description": "请输入正确的网址",
+            "usage": ":rules=\"{url: true}\""
+        },
+        {
+            "name": "date",
+            "description": "请输入正确的日期",
+            "usage": ":rules=\"{date: true}\""
+        },
+        {
+            "name": "dateISO",
+            "description": "请输入正确的日期（YYYY-MM-DD）",
+            "usage": ":rules=\"{dateISO: true}\""
+        },
+        {
+            "name": "number",
+            "description": "请输入正确的数",
+            "usage": ":rules=\"{number: true}\""
+        },
+        {
+            "name": "maxLength",
+            "description": "最多输入/选择 n 项",
+            "usage": ":rules=\"{maxLength: 10}\""
+        },
+        {
+            "name": "minLength",
+            "description": "最少输入/选择 n 项",
+            "usage": ":rules=\"{minLength: 2}\""
+        },
+        {
+            "name": "rangeLength",
+            "description": "长度范围验证",
+            "usage": ":rules=\"{rangeLength: [2, 10]}\""
+        },
+        {
+            "name": "max",
+            "description": "请输入不大于 n 的数",
+            "usage": ":rules=\"{max: 100}\""
+        },
+        {
+            "name": "min",
+            "description": "请输入不小于 n 的数",
+            "usage": ":rules=\"{min: 0}\""
+        },
+        {
+            "name": "range",
+            "description": "请输入 min 到 max 之间的数",
+            "usage": ":rules=\"{range: [0, 100]}\""
+        },
+        {
+            "name": "step",
+            "description": "请输入步长为 n 的数",
+            "usage": ":rules=\"{step: 5}\""
+        },
+        {
+            "name": "equal",
+            "description": "两次输入不一致",
+            "usage": ":rules=\"{equal: password}\""
+        }
+    ],
+    "subComponents": [
+        {
+            "name": "FormItem",
+            "description": "表单项组件，用于包裹表单控件并提供验证功能",
+            "props": [
+                {
+                    "name": "value",
+                    "description": "指定需要验证的数据",
+                    "type": {
+                        "raw": "any",
+                        "kind": "custom"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem :value=\"model.username\" :rules=\"{required: true}\">"
+                },
+                {
+                    "name": "rules",
+                    "description": "指定验证规则，可使用内置规则或自定义规则",
+                    "type": {
+                        "raw": "Record<string, any>",
+                        "kind": "object"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem :rules=\"{required: true, email: true, maxLength: 50}\">"
+                },
+                {
+                    "name": "messages",
+                    "description": "指定验证失败时错误提示文案，key 为规则名",
+                    "type": {
+                        "raw": "Record<string, string | ((value: any, param: any) => string)>",
+                        "kind": "object"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem :messages=\"{required: '此项必填', email: '邮箱格式不正确'}\">"
+                },
+                {
+                    "name": "classNames",
+                    "description": "指定验证失败时添加的 className，key 为规则名",
+                    "type": {
+                        "raw": "Record<string, string | ((value: any, param: any) => string)>",
+                        "kind": "object"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem :classNames=\"{required: 'error-required'}\">"
+                },
+                {
+                    "name": "errorClassName",
+                    "description": "指定验证失败时统一添加的 className，不管是哪个规则导致的失败",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem errorClassName=\"form-error\">"
+                },
+                {
+                    "name": "label",
+                    "description": "指定表单每一项前面展示的标题",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem label=\"用户名\">"
+                },
+                {
+                    "name": "htmlFor",
+                    "description": "指定 label 的 for 属性，用于关联表单控件",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<FormItem label=\"用户名\" htmlFor=\"username\">"
+                },
+                {
+                    "name": "hideLabel",
+                    "description": "是否隐藏 label，默认会展示 label，即使该属性为空，也会展示占位元素",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<FormItem hideLabel>"
+                },
+                {
+                    "name": "fluid",
+                    "description": "FormItem 的宽度默认是被子元素撑开的，添加该属性可以渲染 100% 的宽度",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<FormItem fluid>"
+                },
+                {
+                    "name": "validateOnStart",
+                    "description": "是否组件一渲染就开始验证，而不是等用户输入完成再验证",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<FormItem validateOnStart>"
+                }
+            ],
+            "slots": [
+                {
+                    "name": "label",
+                    "description": "扩展前面的标题label"
+                },
+                {
+                    "name": "content",
+                    "description": "扩展后面的内容，也可以使用children代替"
+                },
+                {
+                    "name": "append",
+                    "description": "往后面追加的内容"
+                }
+            ]
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "Method",
+            "definition": "type Method = (value: any, param: any) => boolean | string | Promise<boolean | string>",
+            "description": "验证函数类型，返回 true 表示验证通过，false 或字符串表示失败"
+        },
+        {
+            "name": "Message",
+            "definition": "type Message = string | ((value: any, param: any) => string)",
+            "description": "错误提示文案类型，可以是字符串或返回字符串的函数"
+        },
+        {
+            "name": "ClassName",
+            "definition": "type ClassName = string | ((value: any, param: any) => string)",
+            "description": "错误类名类型，可以是字符串或返回字符串的函数"
+        }
+    ],
+    "examples": [
+        {
+            "id": "form_basic",
+            "title": "基础表单验证",
+            "description": "基本的表单验证用法",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Form, FormItem, Input, Button, Message } from '@king-design/vue';\n\nconst form = ref<InstanceType<typeof Form>>();\nconst model = reactive({\n  username: '',\n  email: ''\n});\n\nconst handleSubmit = async () => {\n  if (await form.value?.validate()) {\n    Message.success('验证通过');\n  }\n};\n</script>\n<template>\n  <Form ref=\"form\" @submit=\"handleSubmit\">\n    <FormItem label=\"用户名\" :value=\"model.username\" :rules=\"{required: true}\">\n      <Input v-model=\"model.username\" />\n    </FormItem>\n    <FormItem label=\"邮箱\" :value=\"model.email\" :rules=\"{required: true, email: true}\">\n      <Input v-model=\"model.email\" />\n    </FormItem>\n    <FormItem>\n      <Button type=\"primary\" htmlType=\"submit\">提交</Button>\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "basic",
+                "validation",
+                "required",
+                "email"
+            ],
+            "usedProps": [
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [
+                "submit"
+            ],
+            "usedMethods": [
+                "validate"
+            ],
+            "scenario": "创建一个带有用户名和邮箱验证的基础表单"
+        },
+        {
+            "id": "form_layout_vertical",
+            "title": "垂直布局表单",
+            "description": "使用垂直布局的表单",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Form, FormItem, Input } from '@king-design/vue';\n\nconst model = reactive({\n  name: ''\n});\n</script>\n<template>\n  <Form layout=\"vertical\">\n    <FormItem label=\"姓名\" :value=\"model.name\" :rules=\"{required: true}\">\n      <Input v-model=\"model.name\" />\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "layout",
+                "vertical"
+            ],
+            "usedProps": [
+                "layout",
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建垂直布局的表单，label 显示在输入框上方"
+        },
+        {
+            "id": "form_layout_inline",
+            "title": "内联布局表单",
+            "description": "使用内联布局的搜索表单",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Form, FormItem, Input, Button } from '@king-design/vue';\n\nconst model = reactive({\n  keyword: ''\n});\n</script>\n<template>\n  <Form layout=\"inline\">\n    <FormItem label=\"关键词\">\n      <Input v-model=\"model.keyword\" placeholder=\"请输入\" />\n    </FormItem>\n    <FormItem>\n      <Button type=\"primary\">搜索</Button>\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "layout",
+                "inline",
+                "search"
+            ],
+            "usedProps": [
+                "layout"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建内联布局的搜索表单，所有表单项在一行显示"
+        },
+        {
+            "id": "form_custom_rule",
+            "title": "自定义验证规则",
+            "description": "添加自定义的手机号验证规则",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { onMounted, reactive } from 'vue';\nimport { Form, FormItem, Input } from '@king-design/vue';\n\nconst model = reactive({\n  phone: ''\n});\n\nonMounted(() => {\n  Form.addMethod('phone', (value: string) => {\n    return /^1[3-9]\\d{9}$/.test(value) || '请输入正确的手机号';\n  });\n});\n</script>\n<template>\n  <Form>\n    <FormItem label=\"手机号\" :value=\"model.phone\" :rules=\"{required: true, phone: true}\">\n      <Input v-model=\"model.phone\" />\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "custom",
+                "validation",
+                "addMethod",
+                "phone"
+            ],
+            "usedProps": [
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "使用 Form.addMethod 添加自定义的手机号验证规则"
+        },
+        {
+            "id": "form_password_confirm",
+            "title": "密码确认验证",
+            "description": "使用 equal 规则实现密码确认",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Form, FormItem, Input } from '@king-design/vue';\n\nconst model = reactive({\n  password: '',\n  confirmPassword: ''\n});\n</script>\n<template>\n  <Form>\n    <FormItem label=\"密码\" :value=\"model.password\" :rules=\"{required: true}\">\n      <Input type=\"password\" v-model=\"model.password\" />\n    </FormItem>\n    <FormItem label=\"确认密码\" :value=\"model.confirmPassword\" \n      :rules=\"{required: true, equal: model.password}\">\n      <Input type=\"password\" v-model=\"model.confirmPassword\" />\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "password",
+                "equal",
+                "confirm"
+            ],
+            "usedProps": [
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建密码和确认密码字段，验证两次输入是否一致"
+        },
+        {
+            "id": "form_custom_messages",
+            "title": "自定义错误提示",
+            "description": "自定义验证失败时的错误提示文案",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Form, FormItem, Input } from '@king-design/vue';\n\nconst model = reactive({\n  email: ''\n});\n</script>\n<template>\n  <Form>\n    <FormItem label=\"邮箱\" :value=\"model.email\" \n      :rules=\"{required: true, email: true}\"\n      :messages=\"{required: '邮箱不能为空', email: '邮箱格式不正确'}\">\n      <Input v-model=\"model.email\" />\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "messages",
+                "custom",
+                "error"
+            ],
+            "usedProps": [
+                "label",
+                "value",
+                "rules",
+                "messages"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "自定义表单验证失败时显示的错误提示文案"
+        },
+        {
+            "id": "form_reset",
+            "title": "重置表单",
+            "description": "重置表单验证状态",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Form, FormItem, Input, Button } from '@king-design/vue';\n\nconst form = ref<InstanceType<typeof Form>>();\nconst model = reactive({\n  name: ''\n});\n\nconst handleReset = () => {\n  form.value?.reset();\n  model.name = '';\n};\n</script>\n<template>\n  <Form ref=\"form\">\n    <FormItem label=\"姓名\" :value=\"model.name\" :rules=\"{required: true}\">\n      <Input v-model=\"model.name\" />\n    </FormItem>\n    <FormItem>\n      <Button @click=\"handleReset\">重置</Button>\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "reset",
+                "clear"
+            ],
+            "usedProps": [
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [],
+            "usedMethods": [
+                "reset"
+            ],
+            "scenario": "重置表单的验证状态和数据"
+        },
+        {
+            "id": "form_star_required",
+            "title": "必填项显示星号",
+            "description": "在必填项 label 前显示红色星号",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Form, FormItem, Input } from '@king-design/vue';\n\nconst model = reactive({\n  name: '',\n  nickname: ''\n});\n</script>\n<template>\n  <Form starOnRequired>\n    <FormItem label=\"姓名\" :value=\"model.name\" :rules=\"{required: true}\">\n      <Input v-model=\"model.name\" />\n    </FormItem>\n    <FormItem label=\"昵称\">\n      <Input v-model=\"model.nickname\" />\n    </FormItem>\n  </Form>\n</template>",
+            "tags": [
+                "starOnRequired",
+                "required",
+                "asterisk"
+            ],
+            "usedProps": [
+                "starOnRequired",
+                "label",
+                "value",
+                "rules"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "在必填表单项的 label 前显示红色星号标记"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "form_missing_value",
+            "description": "FormItem 配置了 rules 但未绑定 value",
+            "wrongCode": "<FormItem label=\"用户名\" :rules=\"{required: true}\">\n  <Input v-model=\"model.username\" />\n</FormItem>",
+            "correctCode": "<FormItem label=\"用户名\" :value=\"model.username\" :rules=\"{required: true}\">\n  <Input v-model=\"model.username\" />\n</FormItem>",
+            "explanation": "使用验证规则时，必须通过 :value 属性绑定需要验证的数据，否则验证不会生效",
+            "relatedProps": [
+                "value",
+                "rules"
+            ]
+        },
+        {
+            "id": "form_layout_typo",
+            "description": "使用不存在的 layout 值",
+            "wrongCode": "<Form layout=\"flex\">",
+            "correctCode": "<Form layout=\"horizontal\">",
+            "explanation": "Form 的 layout 只支持 horizontal, vertical, inline 三种值",
+            "relatedProps": [
+                "layout"
+            ]
+        },
+        {
+            "id": "form_rules_format",
+            "description": "rules 格式错误",
+            "wrongCode": "<FormItem :rules=\"'required'\">",
+            "correctCode": "<FormItem :rules=\"{required: true}\">",
+            "explanation": "rules 必须是对象格式，key 为规则名，value 为规则参数（通常为 true 或具体值）",
+            "relatedProps": [
+                "rules"
+            ]
+        },
+        {
+            "id": "form_validate_sync",
+            "description": "validate 方法未使用 await",
+            "wrongCode": "const valid = form.value?.validate();\nif (valid) { /* ... */ }",
+            "correctCode": "const valid = await form.value?.validate();\nif (valid) { /* ... */ }",
+            "explanation": "validate() 返回 Promise，必须使用 await 或 .then() 获取验证结果",
+            "relatedProps": []
+        }
+    ],
+    "searchKeywords": [
+        "表单",
+        "form",
+        "验证",
+        "validation",
+        "FormItem",
+        "校验",
+        "必填",
+        "required",
+        "规则",
+        "rules",
+        "提交",
+        "submit"
+    ],
+    "useCases": [
+        "用户登录/注册表单",
+        "数据采集表单",
+        "搜索筛选表单",
+        "设置配置表单",
+        "多步骤表单向导",
+        "弹窗内的表单"
+    ],
+    "relatedComponents": [
+        "FormItem",
+        "Input",
+        "Select",
+        "Checkbox",
+        "Radio",
+        "Button"
+    ]
+}