king-design-analyzer 1.0.0

package/components/tree.json

@@ -0,0 +1,480 @@
+{
+    "id": "tree",
+    "name": "Tree",
+    "displayName": "树形控件",
+    "category": "data-display",
+    "description": "树形控件组件，用于展示多层级数据结构。支持节点展开/收起、复选框选择、节点拖拽、异步加载、节点过滤等功能。",
+    "importStatement": "import { Tree } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "data",
+            "description": "要渲染的树形数据",
+            "type": {
+                "raw": "TreeDataItem[]",
+                "kind": "array"
+            },
+            "required": true,
+            "usageExample": "<Tree :data=\"treeData\">"
+        },
+        {
+            "name": "expandedKeys",
+            "description": "指定展开的节点 key 数组，可用 v-model:expandedKeys",
+            "type": {
+                "raw": "K[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree v-model:expandedKeys=\"expandedKeys\">"
+        },
+        {
+            "name": "defaultExpandAll",
+            "description": "是否默认展开所有节点",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tree defaultExpandAll>"
+        },
+        {
+            "name": "checkbox",
+            "description": "是否展示复选框",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tree checkbox>"
+        },
+        {
+            "name": "checkedKeys",
+            "description": "指定勾选的节点 key 数组，可用 v-model:checkedKeys",
+            "type": {
+                "raw": "K[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree checkbox v-model:checkedKeys=\"checkedKeys\">"
+        },
+        {
+            "name": "uncorrelated",
+            "description": "父子 checkbox 选中状态是否互不关联",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tree checkbox uncorrelated>"
+        },
+        {
+            "name": "selectable",
+            "description": "节点是否可选中",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Tree :selectable=\"false\">"
+        },
+        {
+            "name": "selectedKeys",
+            "description": "指定选中的节点 key 数组，可用 v-model:selectedKeys",
+            "type": {
+                "raw": "K[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree v-model:selectedKeys=\"selectedKeys\">"
+        },
+        {
+            "name": "multiple",
+            "description": "selectedKeys 是否支持多选",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tree multiple>"
+        },
+        {
+            "name": "filter",
+            "description": "节点过滤函数，返回 true 则展示，否则过滤掉",
+            "type": {
+                "raw": "(data: TreeDataItem, node: TreeNode) => boolean",
+                "kind": "function",
+                "functionSignature": "(data: TreeDataItem, node: TreeNode) => boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree :filter=\"filterFn\">"
+        },
+        {
+            "name": "load",
+            "description": "异步加载节点数据的函数",
+            "type": {
+                "raw": "(node: TreeNode) => Promise<void> | void",
+                "kind": "function",
+                "functionSignature": "(node: TreeNode) => Promise<void> | void"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree :load=\"loadData\">"
+        },
+        {
+            "name": "showLine",
+            "description": "是否展示左侧对齐线",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Tree :showLine=\"false\">"
+        },
+        {
+            "name": "draggable",
+            "description": "是否支持拖拽",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tree draggable>"
+        },
+        {
+            "name": "allowDrag",
+            "description": "指定哪些节点可拖拽",
+            "type": {
+                "raw": "(node: TreeNode) => boolean",
+                "kind": "function",
+                "functionSignature": "(node: TreeNode) => boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree draggable :allowDrag=\"allowDragFn\">"
+        },
+        {
+            "name": "allowDrop",
+            "description": "指定哪些节点可以插入子节点",
+            "type": {
+                "raw": "(node: TreeNode, srcNode: TreeNode) => boolean",
+                "kind": "function",
+                "functionSignature": "(node: TreeNode, srcNode: TreeNode) => boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tree draggable :allowDrop=\"allowDropFn\">"
+        }
+    ],
+    "events": [
+        {
+            "name": "dragend",
+            "vueEventName": "@dragend",
+            "description": "拖拽完成时触发",
+            "payload": [
+                {
+                    "name": "data",
+                    "type": "DragEndData",
+                    "description": "拖拽数据，包含 srcNode、toNode、mode"
+                }
+            ],
+            "usageExample": "<Tree @dragend=\"handleDragEnd\">",
+            "handlerExample": "const handleDragEnd = (data) => {\n  console.log(`${data.srcNode.data.label} -> ${data.toNode.data.label}`);\n};"
+        },
+        {
+            "name": "denydrag",
+            "vueEventName": "@denydrag",
+            "description": "拖拽不允许拖拽的节点时触发",
+            "payload": [
+                {
+                    "name": "node",
+                    "type": "TreeNode",
+                    "description": "被拒绝拖拽的节点"
+                }
+            ],
+            "usageExample": "<Tree @denydrag=\"handleDenyDrag\">"
+        },
+        {
+            "name": "denydrop",
+            "vueEventName": "@denydrop",
+            "description": "插入到不允许插入的节点时触发",
+            "payload": [
+                {
+                    "name": "node",
+                    "type": "TreeNode",
+                    "description": "目标节点"
+                },
+                {
+                    "name": "srcNode",
+                    "type": "TreeNode",
+                    "description": "源节点"
+                },
+                {
+                    "name": "mode",
+                    "type": "TreeMode",
+                    "description": "插入模式"
+                }
+            ],
+            "usageExample": "<Tree @denydrop=\"handleDenyDrop\">"
+        }
+    ],
+    "methods": [
+        {
+            "name": "getCheckedData",
+            "description": "获取勾选的节点数据",
+            "arguments": [
+                {
+                    "name": "leafOnly",
+                    "type": "boolean",
+                    "description": "是否只返回叶子节点，默认 false"
+                }
+            ],
+            "returnType": "TreeDataItem[]",
+            "usageExample": "const checkedData = treeRef.value?.getCheckedData();"
+        },
+        {
+            "name": "getSelectedData",
+            "description": "获取选中的节点数据",
+            "returnType": "TreeDataItem[]",
+            "usageExample": "const selectedData = treeRef.value?.getSelectedData();"
+        },
+        {
+            "name": "expand",
+            "description": "展开指定节点",
+            "arguments": [
+                {
+                    "name": "key",
+                    "type": "K",
+                    "description": "要展开的节点 key"
+                }
+            ],
+            "returnType": "void",
+            "usageExample": "treeRef.value?.expand('node1');"
+        },
+        {
+            "name": "shrink",
+            "description": "收起指定节点",
+            "arguments": [
+                {
+                    "name": "key",
+                    "type": "K",
+                    "description": "要收起的节点 key"
+                }
+            ],
+            "returnType": "void",
+            "usageExample": "treeRef.value?.shrink('node1');"
+        },
+        {
+            "name": "expandAll",
+            "description": "展开所有节点",
+            "returnType": "void",
+            "usageExample": "treeRef.value?.expandAll();"
+        },
+        {
+            "name": "getNodes",
+            "description": "返回一级节点数组",
+            "returnType": "TreeNode[]",
+            "usageExample": "const nodes = treeRef.value?.getNodes();"
+        }
+    ],
+    "slots": [
+        {
+            "name": "label",
+            "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": "树节点数据项类型"
+        },
+        {
+            "name": "TreeNode",
+            "definition": "class TreeNode<K> {\n  data: TreeDataItem<K>\n  parent: TreeNode<K> | null\n  key: K\n  checked: boolean\n  indeterminate: boolean\n  children: TreeNode<K>[] | null\n  loaded: boolean | null | undefined\n  filter: boolean\n}",
+            "description": "树节点对象类型"
+        },
+        {
+            "name": "TreeMode",
+            "definition": "enum TreeMode {\n  Before,\n  After,\n  Inner\n}",
+            "description": "拖拽插入模式"
+        }
+    ],
+    "examples": [
+        {
+            "id": "tree_basic",
+            "title": "基础用法",
+            "description": "基本的树形控件",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Tree } from '@king-design/vue';\n\nconst data = reactive([\n  {\n    label: '一级节点-1',\n    key: '1',\n    children: [\n      {\n        label: '二级节点-1.1',\n        key: '1-1',\n        children: [{ label: '三级节点-1.1.1', key: '1-1-1' }]\n      }\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  <Tree :data=\"data\" :expandedKeys=\"['1', '2']\" />\n</template>",
+            "tags": [
+                "basic"
+            ],
+            "usedProps": [
+                "data",
+                "expandedKeys"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个基本的树形控件"
+        },
+        {
+            "id": "tree_checkbox",
+            "title": "带复选框",
+            "description": "带复选框的树形控件",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Tree, Button } from '@king-design/vue';\n\nconst data = reactive([\n  {\n    label: '父节点',\n    key: 'parent',\n    children: [\n      { label: '子节点1', key: 'child1' },\n      { label: '子节点2', key: 'child2' },\n      { label: '子节点3', key: 'child3' }\n    ]\n  }\n]);\nconst checkedKeys = ref<string[]>(['child1']);\nconst tree = ref<InstanceType<typeof Tree>>();\n\nconst getChecked = () => {\n  console.log(tree.value?.getCheckedData());\n};\n</script>\n<template>\n  <div>\n    <Button @click=\"getChecked\">获取选中数据</Button>\n    <Tree ref=\"tree\" :data=\"data\" checkbox v-model:checkedKeys=\"checkedKeys\" :expandedKeys=\"['parent']\" />\n  </div>\n</template>",
+            "tags": [
+                "checkbox",
+                "checked"
+            ],
+            "usedProps": [
+                "data",
+                "checkbox",
+                "checkedKeys",
+                "expandedKeys"
+            ],
+            "usedEvents": [],
+            "usedMethods": [
+                "getCheckedData"
+            ],
+            "scenario": "创建带复选框的树形控件"
+        },
+        {
+            "id": "tree_expand_all",
+            "title": "默认展开全部",
+            "description": "默认展开所有节点",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Tree } from '@king-design/vue';\n\nconst data = reactive([\n  {\n    label: '一级节点',\n    key: '1',\n    children: [\n      {\n        label: '二级节点',\n        key: '1-1',\n        children: [{ label: '三级节点', key: '1-1-1' }]\n      }\n    ]\n  }\n]);\n</script>\n<template>\n  <Tree :data=\"data\" defaultExpandAll />\n</template>",
+            "tags": [
+                "defaultExpandAll"
+            ],
+            "usedProps": [
+                "data",
+                "defaultExpandAll"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "默认展开所有节点"
+        },
+        {
+            "id": "tree_async_load",
+            "title": "异步加载",
+            "description": "异步加载子节点",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Tree } from '@king-design/vue';\nimport type { TreeNode } from '@king-design/vue';\n\nconst data = reactive([\n  { label: '父节点', key: 'parent', children: [] }\n]);\n\nconst loadData = (node: TreeNode<string>) => {\n  return new Promise<void>(resolve => {\n    setTimeout(() => {\n      node.data.children = [\n        { label: '异步加载的节点1', key: 'async1' },\n        { label: '异步加载的节点2', key: 'async2', children: [] }\n      ];\n      resolve();\n    }, 1000);\n  });\n};\n</script>\n<template>\n  <Tree :data=\"data\" :load=\"loadData\" />\n</template>",
+            "tags": [
+                "load",
+                "async"
+            ],
+            "usedProps": [
+                "data",
+                "load"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "异步加载子节点数据"
+        },
+        {
+            "id": "tree_filter",
+            "title": "节点过滤",
+            "description": "搜索过滤节点",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Tree, Input } from '@king-design/vue';\nimport type { TreeDataItem } from '@king-design/vue';\n\nconst keywords = ref('');\nconst data = reactive([\n  {\n    label: '文档',\n    key: '1',\n    children: [\n      { label: '产品介绍', key: '1-1' },\n      { label: '使用指南', key: '1-2' }\n    ]\n  },\n  {\n    label: '代码',\n    key: '2',\n    children: [\n      { label: '组件代码', key: '2-1' },\n      { label: '工具函数', key: '2-2' }\n    ]\n  }\n]);\n\nconst filter = (item: TreeDataItem<string>) => {\n  if (!keywords.value) return true;\n  return item.label?.toString().includes(keywords.value);\n};\n</script>\n<template>\n  <div>\n    <Input v-model=\"keywords\" placeholder=\"输入关键字过滤\" />\n    <Tree :data=\"data\" :filter=\"filter\" defaultExpandAll />\n  </div>\n</template>",
+            "tags": [
+                "filter",
+                "search"
+            ],
+            "usedProps": [
+                "data",
+                "filter",
+                "defaultExpandAll"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "搜索过滤树节点"
+        },
+        {
+            "id": "tree_draggable",
+            "title": "可拖拽",
+            "description": "支持拖拽的树形控件",
+            "difficulty": "hard",
+            "code": "<script setup lang=\"ts\">\nimport { reactive } from 'vue';\nimport { Tree, Message } from '@king-design/vue';\nimport type { TreeNode, TreeDragEndData } from '@king-design/vue';\n\nconst data = reactive([\n  { label: '节点1', key: 'node1' },\n  { label: '节点2', key: 'node2', children: [{ label: '子节点', key: 'child' }] },\n  { label: '节点3', key: 'node3' }\n]);\nconst expandedKeys = reactive<string[]>(['node2']);\n\nconst onDragEnd = (dragData: TreeDragEndData<string>) => {\n  Message.success(`拖拽完成: ${dragData.srcNode.data.label} -> ${dragData.toNode.data.label}`);\n};\n\nconst allowDrag = (node: TreeNode<string>) => node.key !== 'node1';\n</script>\n<template>\n  <Tree \n    v-model:data=\"data\" \n    v-model:expandedKeys=\"expandedKeys\"\n    draggable \n    :allowDrag=\"allowDrag\" \n    @dragend=\"onDragEnd\" \n  />\n</template>",
+            "tags": [
+                "draggable",
+                "drag"
+            ],
+            "usedProps": [
+                "data",
+                "expandedKeys",
+                "draggable",
+                "allowDrag"
+            ],
+            "usedEvents": [
+                "dragend"
+            ],
+            "usedMethods": [],
+            "scenario": "创建可拖拽的树形控件"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "tree_data_key",
+            "description": "data 中缺少 key 属性",
+            "wrongCode": "const data = [{ label: '节点1' }]; // 缺少 key",
+            "correctCode": "const data = [{ label: '节点1', key: 'node1' }];",
+            "explanation": "每个节点必须有唯一的 key 属性",
+            "relatedProps": [
+                "data"
+            ]
+        },
+        {
+            "id": "tree_async_children",
+            "description": "异步加载时未设置 children 为空数组",
+            "wrongCode": "const data = [{ label: '父节点', key: 'parent' }]; // 无 children，不会显示展开箭头",
+            "correctCode": "const data = [{ label: '父节点', key: 'parent', children: [] }];",
+            "explanation": "异步加载节点需要设置 children 为空数组，才会显示展开箭头",
+            "relatedProps": [
+                "data",
+                "load"
+            ]
+        },
+        {
+            "id": "tree_checkbox_keys",
+            "description": "checkbox 模式下 checkedKeys 类型错误",
+            "wrongCode": "const checkedKeys = ref('node1'); // 应该是数组",
+            "correctCode": "const checkedKeys = ref<string[]>(['node1']);",
+            "explanation": "checkedKeys 必须是数组类型",
+            "relatedProps": [
+                "checkedKeys"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "树形",
+        "tree",
+        "树控件",
+        "层级",
+        "目录",
+        "文件树"
+    ],
+    "useCases": [
+        "文件目录",
+        "组织架构",
+        "分类导航",
+        "菜单目录",
+        "权限树"
+    ],
+    "relatedComponents": [
+        "TreeSelect"
+    ]
+}