king-design-analyzer 1.0.0

package/components/treeselect.json

@@ -0,0 +1,478 @@
+{
+    "id": "treeselect",
+    "name": "TreeSelect",
+    "displayName": "下拉树选择",
+    "category": "form",
+    "description": "下拉树选择组件，结合了 Select 和 Tree 的功能。支持单选/多选、复选框、筛选搜索、异步加载等功能。TreeSelect 继承自 Select，与 Select 共享许多属性。",
+    "importStatement": "import { TreeSelect } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "value",
+            "description": "当前选择的值，可用 v-model 双向绑定",
+            "type": {
+                "raw": "any",
+                "kind": "custom"
+            },
+            "required": false,
+            "default": "\"\"",
+            "usageExample": "<TreeSelect v-model=\"value\">"
+        },
+        {
+            "name": "data",
+            "description": "要渲染的树形数据",
+            "type": {
+                "raw": "TreeDataItem[]",
+                "kind": "array"
+            },
+            "required": true,
+            "usageExample": "<TreeSelect :data=\"treeData\">"
+        },
+        {
+            "name": "multiple",
+            "description": "是否支持多选",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect multiple>"
+        },
+        {
+            "name": "checkbox",
+            "description": "是否展示复选框",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect checkbox>"
+        },
+        {
+            "name": "uncorrelated",
+            "description": "父子 checkbox 选中状态是否互不关联",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect checkbox uncorrelated>"
+        },
+        {
+            "name": "filterable",
+            "description": "是否支持筛选",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect filterable>"
+        },
+        {
+            "name": "filter",
+            "description": "自定义筛选规则函数",
+            "type": {
+                "raw": "(keywords: string, data: TreeDataItem) => boolean",
+                "kind": "function",
+                "functionSignature": "(keywords: string, data: TreeDataItem) => boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<TreeSelect filterable :filter=\"customFilter\">"
+        },
+        {
+            "name": "load",
+            "description": "异步加载节点数据的函数",
+            "type": {
+                "raw": "(node: TreeNode) => Promise<void> | void",
+                "kind": "function",
+                "functionSignature": "(node: TreeNode) => Promise<void> | void"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<TreeSelect :load=\"loadData\">"
+        },
+        {
+            "name": "defaultExpandAll",
+            "description": "是否默认展开所有节点",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect defaultExpandAll>"
+        },
+        {
+            "name": "showLine",
+            "description": "是否展示 Tree 的对齐线",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<TreeSelect :showLine=\"false\">"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect disabled>"
+        },
+        {
+            "name": "clearable",
+            "description": "是否可清空",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect clearable>"
+        },
+        {
+            "name": "loading",
+            "description": "数据加载状态",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect :loading=\"isLoading\">"
+        },
+        {
+            "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": "<TreeSelect size=\"small\">"
+        },
+        {
+            "name": "placeholder",
+            "description": "占位文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"请选择\"",
+            "usageExample": "<TreeSelect placeholder=\"请选择节点\">"
+        },
+        {
+            "name": "fluid",
+            "description": "是否宽度 100%",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect fluid>"
+        },
+        {
+            "name": "width",
+            "description": "指定宽度，自动添加单位 px",
+            "type": {
+                "raw": "number | string",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<TreeSelect :width=\"300\">"
+        },
+        {
+            "name": "hideIcon",
+            "description": "是否隐藏后面的图标",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect hideIcon>"
+        },
+        {
+            "name": "inline",
+            "description": "是否展示内联模式",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect inline>"
+        },
+        {
+            "name": "flat",
+            "description": "是否展示扁平样式",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<TreeSelect flat>"
+        }
+    ],
+    "events": [
+        {
+            "name": "show",
+            "vueEventName": "@show",
+            "description": "菜单弹出时触发",
+            "payload": [],
+            "usageExample": "<TreeSelect @show=\"handleShow\">",
+            "handlerExample": "const handleShow = () => {\n  console.log('下拉菜单已打开');\n};"
+        },
+        {
+            "name": "hide",
+            "vueEventName": "@hide",
+            "description": "菜单隐藏时触发",
+            "payload": [],
+            "usageExample": "<TreeSelect @hide=\"handleHide\">",
+            "handlerExample": "const handleHide = () => {\n  console.log('下拉菜单已关闭');\n};"
+        }
+    ],
+    "methods": [
+        {
+            "name": "expandAll",
+            "description": "展开所有节点",
+            "returnType": "void",
+            "usageExample": "treeSelectRef.value?.expandAll();"
+        }
+    ],
+    "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": "自定义整个菜单的内容"
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "TreeDataItem",
+            "definition": "type TreeDataItem<K> = {\n  label?: string | VNode\n  key?: K\n  disabled?: boolean\n  loaded?: boolean\n  children?: TreeDataItem<K>[]\n}",
+            "description": "树节点数据项类型"
+        }
+    ],
+    "examples": [
+        {
+            "id": "treeselect_basic",
+            "title": "基础用法",
+            "description": "基本的下拉树选择",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst value = ref('');\nconst data = ref([\n  {\n    label: '一级节点-1',\n    key: '1',\n    children: [\n      { label: '二级节点-1.1', key: '1-1' },\n      { label: '二级节点-1.2', key: '1-2' }\n    ]\n  },\n  {\n    label: '一级节点-2',\n    key: '2',\n    children: [\n      { label: '二级节点-2.1', key: '2-1' },\n      { label: '二级节点-2.2', key: '2-2', disabled: true }\n    ]\n  }\n]);\n</script>\n<template>\n  <TreeSelect v-model=\"value\" :data=\"data\" placeholder=\"请选择节点\" />\n</template>",
+            "tags": [
+                "basic"
+            ],
+            "usedProps": [
+                "value",
+                "data",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个基本的下拉树选择"
+        },
+        {
+            "id": "treeselect_multiple",
+            "title": "多选",
+            "description": "支持多选的下拉树",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst values = ref<string[]>([]);\nconst data = ref([\n  {\n    label: '一级节点-1',\n    key: '1',\n    children: [\n      { label: '二级节点-1.1', key: '1-1' },\n      { label: '二级节点-1.2', key: '1-2' }\n    ]\n  },\n  {\n    label: '一级节点-2',\n    key: '2',\n    children: [\n      { label: '二级节点-2.1', key: '2-1' },\n      { label: '二级节点-2.2', key: '2-2' }\n    ]\n  }\n]);\n</script>\n<template>\n  <TreeSelect v-model=\"values\" :data=\"data\" multiple />\n</template>",
+            "tags": [
+                "multiple"
+            ],
+            "usedProps": [
+                "value",
+                "data",
+                "multiple"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建多选下拉树"
+        },
+        {
+            "id": "treeselect_checkbox",
+            "title": "带复选框",
+            "description": "带复选框的下拉树",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst values = ref<string[]>(['1-1']);\nconst data = ref([\n  {\n    label: '父节点',\n    key: 'parent',\n    children: [\n      { label: '子节点1', key: '1-1' },\n      { label: '子节点2', key: '1-2' },\n      { label: '子节点3', key: '1-3' }\n    ]\n  }\n]);\n</script>\n<template>\n  <TreeSelect v-model=\"values\" :data=\"data\" checkbox />\n</template>",
+            "tags": [
+                "checkbox"
+            ],
+            "usedProps": [
+                "value",
+                "data",
+                "checkbox"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建带复选框的下拉树"
+        },
+        {
+            "id": "treeselect_filterable",
+            "title": "可搜索",
+            "description": "支持搜索过滤的下拉树",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst value = ref('');\nconst data = ref([\n  {\n    label: '北京',\n    key: 'beijing',\n    children: [\n      { label: '朝阳区', key: 'chaoyang' },\n      { label: '海淀区', key: 'haidian' }\n    ]\n  },\n  {\n    label: '上海',\n    key: 'shanghai',\n    children: [\n      { label: '浦东新区', key: 'pudong' },\n      { label: '黄浦区', key: 'huangpu' }\n    ]\n  }\n]);\n</script>\n<template>\n  <TreeSelect v-model=\"value\" :data=\"data\" filterable placeholder=\"输入搜索\" />\n</template>",
+            "tags": [
+                "filterable",
+                "search"
+            ],
+            "usedProps": [
+                "value",
+                "data",
+                "filterable",
+                "placeholder"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建可搜索的下拉树"
+        },
+        {
+            "id": "treeselect_async",
+            "title": "异步加载",
+            "description": "异步加载子节点",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst data = reactive([\n  {\n    label: '父节点',\n    key: 'parent',\n    children: [\n      { label: '子节点1', key: 'child1', children: [] },\n      { label: '子节点2', key: 'child2', children: [], loaded: true }\n    ]\n  }\n]);\n\nconst loadData = (node: any) => {\n  return new Promise<void>(resolve => {\n    setTimeout(() => {\n      node.data.children = [\n        { label: `异步节点1`, key: `${node.key}-1` },\n        { label: `异步节点2`, key: `${node.key}-2`, children: [] }\n      ];\n      resolve();\n    }, 1000);\n  });\n};\n</script>\n<template>\n  <TreeSelect :data=\"data\" :load=\"loadData\" />\n</template>",
+            "tags": [
+                "load",
+                "async"
+            ],
+            "usedProps": [
+                "data",
+                "load"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "异步加载子节点数据"
+        },
+        {
+            "id": "treeselect_clearable",
+            "title": "可清空",
+            "description": "可清空的下拉树",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TreeSelect } from '@king-design/vue';\n\nconst value = ref('node1');\nconst data = ref([\n  { label: '节点1', key: 'node1' },\n  { label: '节点2', key: 'node2' },\n  { label: '节点3', key: 'node3' }\n]);\n</script>\n<template>\n  <TreeSelect v-model=\"value\" :data=\"data\" clearable />\n</template>",
+            "tags": [
+                "clearable"
+            ],
+            "usedProps": [
+                "value",
+                "data",
+                "clearable"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建可清空的下拉树"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "treeselect_data_key",
+            "description": "data 中缺少 key 属性",
+            "wrongCode": "const data = [{ label: '节点1' }]; // 缺少 key",
+            "correctCode": "const data = [{ label: '节点1', key: 'node1' }];",
+            "explanation": "每个节点必须有唯一的 key 属性，key 同时也是选中时的取值",
+            "relatedProps": [
+                "data"
+            ]
+        },
+        {
+            "id": "treeselect_multiple_value_type",
+            "description": "多选时 value 类型错误",
+            "wrongCode": "const value = ref('');\n<TreeSelect v-model=\"value\" multiple />",
+            "correctCode": "const values = ref<string[]>([]);\n<TreeSelect v-model=\"values\" multiple />",
+            "explanation": "multiple 模式下 value 必须是数组类型",
+            "relatedProps": [
+                "value",
+                "multiple"
+            ]
+        },
+        {
+            "id": "treeselect_checkbox_vs_multiple",
+            "description": "混淆 checkbox 和 multiple",
+            "wrongCode": "<TreeSelect checkbox multiple /> <!-- 通常不需要同时使用 -->",
+            "correctCode": "<TreeSelect checkbox /> <!-- checkbox 已隐含多选 -->",
+            "explanation": "checkbox 模式已经支持多选，通常不需要同时设置 multiple",
+            "relatedProps": [
+                "checkbox",
+                "multiple"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "下拉树",
+        "treeselect",
+        "树形选择",
+        "树选择器",
+        "级联选择"
+    ],
+    "useCases": [
+        "组织架构选择",
+        "地区选择",
+        "分类选择",
+        "部门选择",
+        "文件夹选择"
+    ],
+    "relatedComponents": [
+        "Tree",
+        "Select",
+        "Cascader"
+    ]
+}