king-design-analyzer 1.0.0

package/components/select.json

@@ -0,0 +1,676 @@
+{
+    "id": "select",
+    "name": "Select",
+    "displayName": "选择框",
+    "category": "form",
+    "description": "下拉选择器组件，支持单选、多选、分组、搜索筛选、可创建新选项等功能。配合 Option 和 OptionGroup 子组件使用。",
+    "importStatement": "import { Select, Option, OptionGroup } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "value",
+            "description": "当前选择的元素，可用 v-model 双向绑定",
+            "type": {
+                "raw": "any",
+                "kind": "custom"
+            },
+            "required": false,
+            "default": "\"\"",
+            "usageExample": "<Select v-model=\"selected\">"
+        },
+        {
+            "name": "multiple",
+            "description": "是否支持多选",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select v-model=\"selectedList\" multiple>"
+        },
+        {
+            "name": "filterable",
+            "description": "是否支持筛选，输入时可过滤选项",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select v-model=\"selected\" filterable>"
+        },
+        {
+            "name": "loading",
+            "description": "数据加载状态",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select v-model=\"selected\" :loading=\"isLoading\">"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select disabled>"
+        },
+        {
+            "name": "name",
+            "description": "表单元素的 name 属性",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Select name=\"city\">"
+        },
+        {
+            "name": "size",
+            "description": "尺寸",
+            "type": {
+                "raw": "\"large\" | \"default\" | \"small\" | \"mini\"",
+                "kind": "union",
+                "unionTypes": [
+                    "large",
+                    "default",
+                    "small",
+                    "mini"
+                ]
+            },
+            "required": false,
+            "default": "\"default\"",
+            "allowedValues": [
+                {
+                    "value": "large",
+                    "label": "大尺寸"
+                },
+                {
+                    "value": "default",
+                    "label": "默认尺寸",
+                    "isDefault": true
+                },
+                {
+                    "value": "small",
+                    "label": "小尺寸"
+                },
+                {
+                    "value": "mini",
+                    "label": "迷你尺寸"
+                }
+            ],
+            "usageExample": "<Select size=\"small\">"
+        },
+        {
+            "name": "hideIcon",
+            "description": "是否隐藏后面的下拉图标",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select hideIcon>"
+        },
+        {
+            "name": "clearable",
+            "description": "是否可清空已选内容",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select v-model=\"selected\" clearable>"
+        },
+        {
+            "name": "fluid",
+            "description": "是否宽度 100%",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select fluid>"
+        },
+        {
+            "name": "inline",
+            "description": "展示内联模式，该模式下组件没有边框，宽度和高度由内容撑开",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select inline>"
+        },
+        {
+            "name": "placeholder",
+            "description": "占位文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"请选择\"",
+            "usageExample": "<Select placeholder=\"请选择城市\">"
+        },
+        {
+            "name": "container",
+            "description": "指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body",
+            "type": {
+                "raw": "string | ((parentDom: Element, anchor: Node | null) => Element)",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Select :container=\"() => document.body\">"
+        },
+        {
+            "name": "width",
+            "description": "指定宽度，组件自动添加单位 px",
+            "type": {
+                "raw": "number | string",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Select :width=\"200\">"
+        },
+        {
+            "name": "filter",
+            "description": "当支持筛选时，可以自定义筛选规则",
+            "type": {
+                "raw": "(keywords: string, props: any) => boolean",
+                "kind": "function",
+                "functionSignature": "(keywords: string, props: any) => boolean"
+            },
+            "required": false,
+            "default": "(keywords, props) => props.label.toLowerCase().includes(keywords) || props.value.toLowerCase().includes(keywords)",
+            "usageExample": "<Select filterable :filter=\"(kw, props) => props.label.includes(kw)\">"
+        },
+        {
+            "name": "searchable",
+            "description": "是否在弹出菜单中展示搜索框",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select searchable>"
+        },
+        {
+            "name": "creatable",
+            "description": "是否支持创建新的选项，可以配合 filterable 使用",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select filterable creatable>"
+        },
+        {
+            "name": "labelMap",
+            "description": "建立 value 到 label 的映射，可以在 value 不在 Option 集合中时正确展示 label",
+            "type": {
+                "raw": "Map<any, string>",
+                "kind": "object"
+            },
+            "required": false,
+            "default": "new Map()",
+            "usageExample": "<Select :labelMap=\"new Map([['custom', '自定义选项']])\">"
+        },
+        {
+            "name": "card",
+            "description": "是否展示 card 模式",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select card>"
+        },
+        {
+            "name": "autoDisableArrow",
+            "description": "是否在没有更多可选项时，给箭头一个 disabled 状态来提示用户",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select autoDisableArrow>"
+        },
+        {
+            "name": "keepKeywords",
+            "description": "是否在选中选项后保留搜索关键字，配合 filterable 使用",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Select filterable :keepKeywords=\"false\">"
+        },
+        {
+            "name": "show",
+            "description": "是否展示菜单项（受控模式）",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select :show=\"isMenuVisible\">"
+        },
+        {
+            "name": "position",
+            "description": "菜单弹出的位置",
+            "type": {
+                "raw": "Position | \"left\" | \"bottom\" | \"right\" | \"top\"",
+                "kind": "union",
+                "unionTypes": [
+                    "left",
+                    "bottom",
+                    "right",
+                    "top"
+                ]
+            },
+            "required": false,
+            "default": "{my: 'left top+8', at: 'left bottom'}",
+            "usageExample": "<Select position=\"top\">"
+        },
+        {
+            "name": "flat",
+            "description": "是否展示扁平样式",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select flat>"
+        },
+        {
+            "name": "draggable",
+            "description": "多选值是否支持拖动排序",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select multiple draggable>"
+        },
+        {
+            "name": "virtual",
+            "description": "是否开启虚拟列表，用于大数据量场景",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Select virtual>"
+        }
+    ],
+    "events": [
+        {
+            "name": "show",
+            "vueEventName": "@show",
+            "description": "菜单弹出时触发",
+            "payload": [],
+            "usageExample": "<Select @show=\"handleShow\">",
+            "handlerExample": "const handleShow = () => {\n  console.log('下拉菜单已展开');\n};"
+        },
+        {
+            "name": "hide",
+            "vueEventName": "@hide",
+            "description": "菜单隐藏时触发",
+            "payload": [],
+            "usageExample": "<Select @hide=\"handleHide\">",
+            "handlerExample": "const handleHide = () => {\n  console.log('下拉菜单已关闭');\n};"
+        }
+    ],
+    "slots": [
+        {
+            "name": "value",
+            "description": "自定义选择结果的展示",
+            "params": "([value: any, label: Children]) => Children"
+        },
+        {
+            "name": "values",
+            "description": "自定义多选的选择结果的展示",
+            "params": "([values: any[], labels: Children[]]) => Children"
+        },
+        {
+            "name": "prefix",
+            "description": "自定义输入框前面展示的内容"
+        },
+        {
+            "name": "suffix",
+            "description": "自定义输入框后面展示的内容"
+        },
+        {
+            "name": "menu",
+            "description": "自定义整个菜单的内容"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "Option",
+            "description": "选项组件，用于定义下拉选项",
+            "props": [
+                {
+                    "name": "value",
+                    "description": "选中的值",
+                    "type": {
+                        "raw": "any",
+                        "kind": "custom"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<Option value=\"apple\" label=\"苹果\" />"
+                },
+                {
+                    "name": "label",
+                    "description": "展示文案，同时也作为筛选的内容。不存在时使用 children 的文本",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<Option value=\"apple\" label=\"苹果\" />"
+                },
+                {
+                    "name": "disabled",
+                    "description": "是否禁用该项选择",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<Option value=\"apple\" label=\"苹果\" disabled />"
+                }
+            ]
+        },
+        {
+            "name": "OptionGroup",
+            "description": "选项分组组件，用于对选项进行分组展示",
+            "props": [
+                {
+                    "name": "label",
+                    "description": "分组标签名",
+                    "type": {
+                        "raw": "string | number | VNode",
+                        "kind": "union"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<OptionGroup label=\"水果\">\n  <Option value=\"apple\" label=\"苹果\" />\n</OptionGroup>"
+                }
+            ],
+            "slots": [
+                {
+                    "name": "label",
+                    "description": "定义复杂的分组标签名"
+                }
+            ]
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "Position",
+            "definition": "type Position = {\n  my?: string | [string, string]\n  at?: string | [string, string]\n  collision?: Collision | [Collision, Collision]\n  collisionDirection?: ['left'] | ['top'] | ['left', 'top']\n}",
+            "description": "菜单弹出位置配置"
+        },
+        {
+            "name": "Collision",
+            "definition": "type Collision = 'fit' | 'flip' | 'flipfit' | 'none'",
+            "description": "碰撞检测行为"
+        },
+        {
+            "name": "Container",
+            "definition": "type Container = string | ((parentDom: Element, anchor: Node | null) => Element)",
+            "description": "容器类型，可以是选择器字符串或返回元素的函数"
+        }
+    ],
+    "examples": [
+        {
+            "id": "select_basic",
+            "title": "基础用法",
+            "description": "基本的下拉选择框",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('');\n</script>\n<template>\n  <Select v-model=\"selected\" placeholder=\"请选择\">\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" />\n    <Option value=\"banana\" label=\"香蕉\" />\n  </Select>\n</template>",
+            "tags": [
+                "basic",
+                "single"
+            ],
+            "usedProps": [
+                "value",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个基本的单选下拉框"
+        },
+        {
+            "id": "select_multiple",
+            "title": "多选",
+            "description": "支持选择多个选项",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref<string[]>([]);\n</script>\n<template>\n  <Select v-model=\"selected\" multiple placeholder=\"请选择多项\">\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" />\n    <Option value=\"banana\" label=\"香蕉\" />\n    <Option value=\"grape\" label=\"葡萄\" />\n  </Select>\n</template>",
+            "tags": [
+                "multiple",
+                "multi-select"
+            ],
+            "usedProps": [
+                "value",
+                "multiple",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个支持多选的下拉框"
+        },
+        {
+            "id": "select_filterable",
+            "title": "可搜索",
+            "description": "可以通过输入关键字筛选选项",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('');\n</script>\n<template>\n  <Select v-model=\"selected\" filterable placeholder=\"输入关键字搜索\">\n    <Option value=\"beijing\" label=\"北京\" />\n    <Option value=\"shanghai\" label=\"上海\" />\n    <Option value=\"guangzhou\" label=\"广州\" />\n    <Option value=\"shenzhen\" label=\"深圳\" />\n  </Select>\n</template>",
+            "tags": [
+                "filterable",
+                "search",
+                "filter"
+            ],
+            "usedProps": [
+                "value",
+                "filterable",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个可以通过关键字搜索的下拉框"
+        },
+        {
+            "id": "select_clearable",
+            "title": "可清空",
+            "description": "支持一键清空已选内容",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('apple');\n</script>\n<template>\n  <Select v-model=\"selected\" clearable>\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" />\n  </Select>\n</template>",
+            "tags": [
+                "clearable",
+                "clear"
+            ],
+            "usedProps": [
+                "value",
+                "clearable"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个可以清空已选值的下拉框"
+        },
+        {
+            "id": "select_group",
+            "title": "分组选项",
+            "description": "使用 OptionGroup 对选项进行分组",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option, OptionGroup } from '@king-design/vue';\n\nconst selected = ref('');\n</script>\n<template>\n  <Select v-model=\"selected\" placeholder=\"请选择\">\n    <OptionGroup label=\"水果\">\n      <Option value=\"apple\" label=\"苹果\" />\n      <Option value=\"orange\" label=\"橙子\" />\n    </OptionGroup>\n    <OptionGroup label=\"蔬菜\">\n      <Option value=\"tomato\" label=\"番茄\" />\n      <Option value=\"potato\" label=\"土豆\" />\n    </OptionGroup>\n  </Select>\n</template>",
+            "tags": [
+                "group",
+                "OptionGroup",
+                "category"
+            ],
+            "usedProps": [
+                "value",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建带有分组的下拉选择框"
+        },
+        {
+            "id": "select_disabled_option",
+            "title": "禁用选项",
+            "description": "禁用特定的选项",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('');\n</script>\n<template>\n  <Select v-model=\"selected\">\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" disabled />\n    <Option value=\"banana\" label=\"香蕉\" />\n  </Select>\n</template>",
+            "tags": [
+                "disabled",
+                "option"
+            ],
+            "usedProps": [
+                "value"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "禁用下拉框中的某些选项"
+        },
+        {
+            "id": "select_creatable",
+            "title": "可创建选项",
+            "description": "允许用户创建新的选项",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('');\n</script>\n<template>\n  <Select v-model=\"selected\" filterable creatable placeholder=\"可输入创建新选项\">\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" />\n  </Select>\n</template>",
+            "tags": [
+                "creatable",
+                "create",
+                "filterable"
+            ],
+            "usedProps": [
+                "value",
+                "filterable",
+                "creatable",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个允许用户输入新选项的下拉框"
+        },
+        {
+            "id": "select_loading",
+            "title": "加载状态",
+            "description": "展示数据加载中的状态",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Select, Option } from '@king-design/vue';\n\nconst selected = ref('');\nconst loading = ref(true);\n\n// 模拟异步加载\nsetTimeout(() => {\n  loading.value = false;\n}, 2000);\n</script>\n<template>\n  <Select v-model=\"selected\" :loading=\"loading\" placeholder=\"加载中...\">\n    <Option value=\"apple\" label=\"苹果\" />\n    <Option value=\"orange\" label=\"橙子\" />\n  </Select>\n</template>",
+            "tags": [
+                "loading",
+                "async"
+            ],
+            "usedProps": [
+                "value",
+                "loading",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "展示异步加载数据时的加载状态"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "select_multiple_type",
+            "description": "多选模式下 value 类型错误",
+            "wrongCode": "const selected = ref('');\n<Select v-model=\"selected\" multiple>",
+            "correctCode": "const selected = ref<string[]>([]);\n<Select v-model=\"selected\" multiple>",
+            "explanation": "使用 multiple 多选模式时，value 必须是数组类型，而非字符串",
+            "relatedProps": [
+                "multiple",
+                "value"
+            ]
+        },
+        {
+            "id": "select_option_value",
+            "description": "Option 未设置 value 属性",
+            "wrongCode": "<Select v-model=\"selected\">\n  <Option label=\"苹果\" />\n</Select>",
+            "correctCode": "<Select v-model=\"selected\">\n  <Option value=\"apple\" label=\"苹果\" />\n</Select>",
+            "explanation": "Option 必须设置 value 属性，否则无法正确绑定选中值",
+            "relatedProps": [
+                "value"
+            ]
+        },
+        {
+            "id": "select_size_typo",
+            "description": "使用不存在的 size 值 (Select)",
+            "wrongCode": "<Select size=\"medium\">",
+            "correctCode": "<Select size=\"default\">",
+            "explanation": "Select 的 size 只支持 large, default, small, mini。常见错误是使用 medium 值。",
+            "relatedProps": [
+                "size"
+            ]
+        },
+        {
+            "id": "select_creatable_without_filterable",
+            "description": "使用 creatable 但未启用 filterable",
+            "wrongCode": "<Select creatable>",
+            "correctCode": "<Select filterable creatable>",
+            "explanation": "creatable 属性需要配合 filterable 使用，因为创建新选项需要用户输入",
+            "relatedProps": [
+                "filterable",
+                "creatable"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "选择框",
+        "select",
+        "下拉",
+        "dropdown",
+        "option",
+        "多选",
+        "multiple",
+        "筛选",
+        "filterable",
+        "分组",
+        "OptionGroup"
+    ],
+    "useCases": [
+        "表单中的下拉选择",
+        "城市/地区选择器",
+        "多标签选择",
+        "分类筛选器",
+        "动态加载选项",
+        "可创建新选项的标签选择"
+    ],
+    "relatedComponents": [
+        "Option",
+        "OptionGroup",
+        "Cascader",
+        "TreeSelect"
+    ]
+}