king-design-analyzer 1.0.0

package/components/dropdown.json

@@ -0,0 +1,407 @@
+{
+    "id": "dropdown",
+    "name": "Dropdown",
+    "displayName": "下拉菜单",
+    "category": "navigation",
+    "description": "下拉菜单组件，用于展示可操作的下拉菜单列表。支持多种触发方式、嵌套菜单、右键菜单等功能。配合 DropdownMenu 和 DropdownItem 子组件使用。",
+    "importStatement": "import { Dropdown, DropdownMenu, DropdownItem } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "trigger",
+            "description": "触发方式",
+            "type": {
+                "raw": "\"hover\" | \"click\" | \"contextmenu\" | \"focus\"",
+                "kind": "union",
+                "unionTypes": [
+                    "hover",
+                    "click",
+                    "contextmenu",
+                    "focus"
+                ]
+            },
+            "required": false,
+            "default": "\"hover\"",
+            "allowedValues": [
+                {
+                    "value": "hover",
+                    "label": "悬停触发",
+                    "isDefault": true
+                },
+                {
+                    "value": "click",
+                    "label": "点击触发"
+                },
+                {
+                    "value": "contextmenu",
+                    "label": "右键触发"
+                },
+                {
+                    "value": "focus",
+                    "label": "聚焦触发"
+                }
+            ],
+            "usageExample": "<Dropdown trigger=\"click\">"
+        },
+        {
+            "name": "value",
+            "description": "是否展示菜单，可用 v-model 双向绑定",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Dropdown v-model=\"visible\">"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用整个菜单",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Dropdown disabled>"
+        },
+        {
+            "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": "<Dropdown position=\"right\">"
+        },
+        {
+            "name": "of",
+            "description": "弹出菜单的位置是相对当前触发元素还是触发元素所在的菜单元素",
+            "type": {
+                "raw": "\"self\" | \"parent\" | Event",
+                "kind": "union",
+                "unionTypes": [
+                    "self",
+                    "parent"
+                ]
+            },
+            "required": false,
+            "default": "\"self\"",
+            "allowedValues": [
+                {
+                    "value": "self",
+                    "label": "相对当前触发元素",
+                    "isDefault": true
+                },
+                {
+                    "value": "parent",
+                    "label": "相对父菜单元素"
+                }
+            ],
+            "usageExample": "<Dropdown of=\"parent\">"
+        },
+        {
+            "name": "container",
+            "description": "指定弹出菜单追加的位置，默认追加到 body",
+            "type": {
+                "raw": "string | ((parentDom: Element, anchor: Node | null) => Element)",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Dropdown :container=\"() => document.body\">"
+        },
+        {
+            "name": "alwaysShowOnClick",
+            "description": "不管什么触发方式，重复点击触发器都不隐藏弹层",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Dropdown alwaysShowOnClick>"
+        }
+    ],
+    "events": [
+        {
+            "name": "show",
+            "vueEventName": "@show",
+            "description": "菜单展示时触发",
+            "payload": [],
+            "usageExample": "<Dropdown @show=\"handleShow\">",
+            "handlerExample": "const handleShow = () => {\n  console.log('菜单已展示');\n};"
+        },
+        {
+            "name": "hide",
+            "vueEventName": "@hide",
+            "description": "菜单隐藏时触发",
+            "payload": [],
+            "usageExample": "<Dropdown @hide=\"handleHide\">",
+            "handlerExample": "const handleHide = () => {\n  console.log('菜单已隐藏');\n};"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "DropdownMenu",
+            "description": "下拉菜单容器，用于包裹菜单项",
+            "props": []
+        },
+        {
+            "name": "DropdownItem",
+            "description": "下拉菜单项组件",
+            "props": [
+                {
+                    "name": "disabled",
+                    "description": "是否禁用该菜单项",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<DropdownItem disabled>禁用项</DropdownItem>"
+                },
+                {
+                    "name": "hideOnSelect",
+                    "description": "选中该菜单后是否隐藏整个菜单",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "true",
+                    "usageExample": "<DropdownItem :hideOnSelect=\"false\">选中不关闭</DropdownItem>"
+                }
+            ],
+            "events": [
+                {
+                    "name": "select",
+                    "vueEventName": "@select",
+                    "description": "菜单项被选中时触发（点击或键盘操作）",
+                    "payload": [
+                        {
+                            "name": "item",
+                            "type": "DropdownItem",
+                            "description": "被选中的菜单项实例"
+                        }
+                    ],
+                    "usageExample": "<DropdownItem @select=\"handleSelect\">",
+                    "handlerExample": "const handleSelect = (item) => {\n  console.log('选中了:', item);\n};"
+                },
+                {
+                    "name": "click",
+                    "vueEventName": "@click",
+                    "description": "菜单项被点击时触发",
+                    "payload": [
+                        {
+                            "name": "e",
+                            "type": "MouseEvent",
+                            "description": "原生鼠标事件"
+                        }
+                    ],
+                    "usageExample": "<DropdownItem @click=\"handleClick\">",
+                    "handlerExample": "const handleClick = (e: MouseEvent) => {\n  console.log('点击了菜单项');\n};"
+                }
+            ]
+        }
+    ],
+    "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": "dropdown_basic",
+            "title": "基础用法",
+            "description": "基本的下拉菜单，悬停触发",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';\n</script>\n<template>\n  <Dropdown>\n    <Button>下拉菜单</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem>菜单项1</DropdownItem>\n        <DropdownItem>菜单项2</DropdownItem>\n        <DropdownItem>菜单项3</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "basic",
+                "hover"
+            ],
+            "usedProps": [],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建一个悬停触发的下拉菜单"
+        },
+        {
+            "id": "dropdown_click",
+            "title": "点击触发",
+            "description": "点击触发的下拉菜单",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';\n</script>\n<template>\n  <Dropdown trigger=\"click\">\n    <Button>点击展开</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem>菜单项1</DropdownItem>\n        <DropdownItem>菜单项2</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "click",
+                "trigger"
+            ],
+            "usedProps": [
+                "trigger"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建点击触发的下拉菜单"
+        },
+        {
+            "id": "dropdown_disabled_item",
+            "title": "禁用菜单项",
+            "description": "禁用特定的菜单项",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';\n</script>\n<template>\n  <Dropdown>\n    <Button>下拉菜单</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem>可用项</DropdownItem>\n        <DropdownItem disabled>禁用项</DropdownItem>\n        <DropdownItem>可用项</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "disabled"
+            ],
+            "usedProps": [
+                "disabled"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "禁用特定的菜单项"
+        },
+        {
+            "id": "dropdown_contextmenu",
+            "title": "右键菜单",
+            "description": "右键触发的上下文菜单",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem } from '@king-design/vue';\n</script>\n<template>\n  <Dropdown trigger=\"contextmenu\">\n    <div style=\"width: 200px; height: 100px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;\">\n      右键点击此区域\n    </div>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem>复制</DropdownItem>\n        <DropdownItem>粘贴</DropdownItem>\n        <DropdownItem>删除</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "contextmenu",
+                "right-click"
+            ],
+            "usedProps": [
+                "trigger"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建右键上下文菜单"
+        },
+        {
+            "id": "dropdown_select_event",
+            "title": "监听选择事件",
+            "description": "监听菜单项的选择",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button, Message } from '@king-design/vue';\n\nconst handleClick = (action: string) => {\n  Message.info(`选择了: ${action}`);\n};\n</script>\n<template>\n  <Dropdown>\n    <Button>操作</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem @click=\"handleClick('编辑')\">编辑</DropdownItem>\n        <DropdownItem @click=\"handleClick('复制')\">复制</DropdownItem>\n        <DropdownItem @click=\"handleClick('删除')\">删除</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "select",
+                "click",
+                "event"
+            ],
+            "usedProps": [],
+            "usedEvents": [
+                "click"
+            ],
+            "usedMethods": [],
+            "scenario": "监听菜单项点击并执行操作"
+        },
+        {
+            "id": "dropdown_nested",
+            "title": "嵌套菜单",
+            "description": "多级嵌套的下拉菜单",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';\n</script>\n<template>\n  <Dropdown>\n    <Button>嵌套菜单</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem>菜单项1</DropdownItem>\n        <Dropdown position=\"right\">\n          <DropdownItem>更多 ></DropdownItem>\n          <template #menu>\n            <DropdownMenu>\n              <DropdownItem>子菜单1</DropdownItem>\n              <DropdownItem>子菜单2</DropdownItem>\n            </DropdownMenu>\n          </template>\n        </Dropdown>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "nested",
+                "submenu"
+            ],
+            "usedProps": [
+                "position"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建多级嵌套的下拉菜单"
+        },
+        {
+            "id": "dropdown_table_action",
+            "title": "表格操作列",
+            "description": "在表格中使用下拉菜单作为操作列",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Dropdown, DropdownMenu, DropdownItem, Button, Message } from '@king-design/vue';\n\nconst handleAction = (action: string, id: number) => {\n  Message.info(`对 ID=${id} 执行 ${action}`);\n};\n</script>\n<template>\n  <!-- 假设在表格的操作列中 -->\n  <Dropdown trigger=\"click\">\n    <Button type=\"link\" size=\"small\">操作</Button>\n    <template #menu>\n      <DropdownMenu>\n        <DropdownItem @click=\"handleAction('查看', 1)\">查看</DropdownItem>\n        <DropdownItem @click=\"handleAction('编辑', 1)\">编辑</DropdownItem>\n        <DropdownItem @click=\"handleAction('删除', 1)\">删除</DropdownItem>\n      </DropdownMenu>\n    </template>\n  </Dropdown>\n</template>",
+            "tags": [
+                "table",
+                "action",
+                "operation"
+            ],
+            "usedProps": [
+                "trigger"
+            ],
+            "usedEvents": [
+                "click"
+            ],
+            "usedMethods": [],
+            "scenario": "在表格操作列中使用下拉菜单"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "dropdown_missing_menu_slot",
+            "description": "未使用 #menu 插槽",
+            "wrongCode": "<Dropdown>\n  <Button>菜单</Button>\n  <DropdownMenu>\n    <DropdownItem>项目</DropdownItem>\n  </DropdownMenu>\n</Dropdown>",
+            "correctCode": "<Dropdown>\n  <Button>菜单</Button>\n  <template #menu>\n    <DropdownMenu>\n      <DropdownItem>项目</DropdownItem>\n    </DropdownMenu>\n  </template>\n</Dropdown>",
+            "explanation": "DropdownMenu 必须放在 #menu 插槽中",
+            "relatedProps": []
+        },
+        {
+            "id": "dropdown_trigger_typo",
+            "description": "trigger 值拼写错误",
+            "wrongCode": "<Dropdown trigger=\"rightclick\">",
+            "correctCode": "<Dropdown trigger=\"contextmenu\">",
+            "explanation": "右键触发应使用 contextmenu，不是 rightclick",
+            "relatedProps": [
+                "trigger"
+            ]
+        },
+        {
+            "id": "dropdown_missing_dropdownmenu",
+            "description": "DropdownItem 未放在 DropdownMenu 中",
+            "wrongCode": "<Dropdown>\n  <Button>菜单</Button>\n  <template #menu>\n    <DropdownItem>项目</DropdownItem>\n  </template>\n</Dropdown>",
+            "correctCode": "<Dropdown>\n  <Button>菜单</Button>\n  <template #menu>\n    <DropdownMenu>\n      <DropdownItem>项目</DropdownItem>\n    </DropdownMenu>\n  </template>\n</Dropdown>",
+            "explanation": "DropdownItem 必须包裹在 DropdownMenu 中",
+            "relatedProps": []
+        }
+    ],
+    "searchKeywords": [
+        "下拉菜单",
+        "dropdown",
+        "菜单",
+        "menu",
+        "右键",
+        "contextmenu",
+        "悬停",
+        "hover"
+    ],
+    "useCases": [
+        "导航下拉菜单",
+        "表格操作列",
+        "右键上下文菜单",
+        "更多操作按钮",
+        "用户头像下拉菜单"
+    ],
+    "relatedComponents": [
+        "DropdownMenu",
+        "DropdownItem",
+        "Menu",
+        "Select"
+    ]
+}