king-design-analyzer 2.1.7 → 2.2.0

package/components/sidebar.json

@@ -0,0 +1,198 @@
+{
+    "id": "sidebar",
+    "name": "Sidebar",
+    "displayName": "侧边导航",
+    "category": "navigation",
+    "description": "用于控制台左侧导航的多层级菜单组件，支持路由联动、展开状态管理和默认选中逻辑。",
+    "importStatement": "import { Sidebar } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "title",
+            "description": "侧边栏标题",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false
+        },
+        {
+            "name": "selectedKey",
+            "description": "当前选中的菜单 key",
+            "type": {
+                "raw": "Key",
+                "kind": "custom"
+            },
+            "required": false
+        },
+        {
+            "name": "expandedKeys",
+            "description": "当前展开的菜单 key 列表",
+            "type": {
+                "raw": "Key[]",
+                "kind": "array"
+            },
+            "required": false
+        },
+        {
+            "name": "menus",
+            "description": "菜单配置树",
+            "type": {
+                "raw": "Menus",
+                "kind": "array"
+            },
+            "required": true
+        },
+        {
+            "name": "router",
+            "description": "是否启用路由模式",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false"
+        },
+        {
+            "name": "autoSelectDefault",
+            "description": "未匹配到路由时是否自动选中默认菜单项",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true"
+        }
+    ],
+    "events": [
+        {
+            "name": "update:selectedKey",
+            "vueEventName": "@update:selectedKey",
+            "description": "当前选中菜单 key 变化时触发，可用于同步路由或高亮状态。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前选中的菜单 key。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "update:expandedKeys",
+            "vueEventName": "@update:expandedKeys",
+            "description": "展开的菜单节点变化时触发，适合持久化用户展开习惯。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string[]",
+                    "description": "当前处于展开状态的菜单 key 列表。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "update:menuItem",
+            "vueEventName": "@update:menuItem",
+            "description": "当前选中的完整菜单项变化时触发，便于读取标题、路由等附加字段。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "SidebarMenuItem",
+                    "description": "当前命中的菜单项对象，包含标题、路由参数和 children 等扩展字段。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "change:menus",
+            "vueEventName": "@change:menus",
+            "description": "菜单结构变化时触发，适合动态菜单加载后重新同步状态。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "SidebarMenuItem[]",
+                    "description": "当前可渲染的菜单树数组，常用于动态菜单加载后做缓存或二次处理。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "sidebar_console_nav",
+            "title": "控制台侧边导航",
+            "description": "渲染一个带二级菜单的控制台导航树。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Sidebar } from '@ksyun-internal/versatile';\n\nconst selectedKey = ref('instances');\nconst expandedKeys = ref(['compute']);\nconst menus = [\n  {\n    key: 'compute',\n    label: '计算',\n    children: [\n      { key: 'instances', label: '实例列表' },\n      { key: 'images', label: '镜像' },\n    ],\n  },\n];\n</script>\n\n<template>\n  <Sidebar\n    title=\"云服务器\"\n    v-model:selected-key=\"selectedKey\"\n    v-model:expanded-keys=\"expandedKeys\"\n    :menus=\"menus\"\n  />\n</template>",
+            "tags": [
+                "navigation",
+                "sidebar"
+            ],
+            "usedProps": [
+                "title",
+                "selectedKey",
+                "expandedKeys",
+                "menus"
+            ],
+            "usedEvents": [
+                "update:selectedKey",
+                "update:expandedKeys"
+            ],
+            "usedMethods": [],
+            "scenario": "在控制台左侧展示资源管理导航。"
+        },
+        {
+            "id": "sidebar_router_mode",
+            "title": "路由模式侧边导航",
+            "description": "在路由驱动的控制台中让侧边栏自动和当前页面同步。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Sidebar } from '@ksyun-internal/versatile';\n\nconst selectedKey = ref('dashboard');\nconst expandedKeys = ref(['overview']);\nconst menus = [\n  {\n    key: 'overview',\n    label: '概览',\n    children: [\n      { key: 'dashboard', label: '仪表盘' },\n      { key: 'alerts', label: '告警中心' },\n    ],\n  },\n];\n</script>\n\n<template>\n  <Sidebar\n    v-model:selected-key=\"selectedKey\"\n    v-model:expanded-keys=\"expandedKeys\"\n    :menus=\"menus\"\n    :router=\"true\"\n    :auto-select-default=\"false\"\n  />\n</template>",
+            "tags": [
+                "navigation",
+                "router"
+            ],
+            "usedProps": [
+                "selectedKey",
+                "expandedKeys",
+                "menus",
+                "router",
+                "autoSelectDefault"
+            ],
+            "usedEvents": [
+                "update:selectedKey",
+                "update:expandedKeys"
+            ],
+            "usedMethods": [],
+            "scenario": "在多级控制台中让菜单选中状态与 URL 同步。"
+        }
+    ],
+    "searchKeywords": [
+        "sidebar",
+        "navigation",
+        "menu tree",
+        "侧边栏",
+        "菜单导航",
+        "多级菜单",
+        "控制台导航",
+        "左侧导航"
+    ],
+    "useCases": [
+        "控制台左侧导航",
+        "多级菜单导航",
+        "资源中心侧边菜单",
+        "路由驱动的后台导航"
+    ],
+    "relatedComponents": [
+        "Header",
+        "LayoutContent"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SidebarMenuItem",
+            "definition": "type SidebarMenuItem = {\n  key: string\n  label: string\n  children?: SidebarMenuItem[]\n}",
+            "description": "侧边导航菜单项配置，支持嵌套 children 构建多层菜单。"
+        }
+    ]
+}

package/components/skeleton.json

@@ -0,0 +1,233 @@
+{
+    "id": "skeleton",
+    "name": "Skeleton",
+    "displayName": "骨架屏",
+    "category": "feedback",
+    "description": "骨架屏组件，用于在内容加载阶段展示占位结构，减轻页面空白感。支持内置文本行、头像骨架和自定义骨架项。",
+    "importStatement": "import { Skeleton, SkeletonItem } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "loading",
+            "description": "是否处于加载中。为 true 时显示骨架内容，否则渲染为空或交由外层控制真实内容展示。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": true,
+            "usageExample": "<Skeleton :loading=\"loading\" />"
+        },
+        {
+            "name": "animated",
+            "description": "是否启用骨架闪动动画。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Skeleton :loading=\"loading\" animated />"
+        },
+        {
+            "name": "rows",
+            "description": "文本骨架行数，最小按 1 处理。",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "2",
+            "usageExample": "<Skeleton :loading=\"loading\" :rows=\"4\" />"
+        },
+        {
+            "name": "avator",
+            "description": "是否展示头像占位。注意组件属性名为 avator，与常见 avatar 拼写不同。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Skeleton :loading=\"loading\" avator />"
+        },
+        {
+            "name": "size",
+            "description": "骨架尺寸，影响占位块的高度与间距。",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"large\"",
+            "usageExample": "<Skeleton :loading=\"loading\" size=\"small\" />"
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "default",
+            "description": "自定义骨架内容。当 loading 为 true 时，默认插槽内容会作为骨架结构渲染。",
+            "vueTemplate": "<Skeleton :loading=\"loading\">...</Skeleton>",
+            "usageExample": "<Skeleton :loading=\"loading\"><div style=\"display:flex; gap:12px;\"><SkeletonItem type=\"avator\" /><div style=\"flex:1;\"><SkeletonItem type=\"text\" /><SkeletonItem type=\"text\" /></div></div></Skeleton>"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "SkeletonItem",
+            "description": "单个骨架项组件，用于组合更复杂的骨架布局。",
+            "props": [
+                {
+                    "name": "type",
+                    "description": "骨架项类型。",
+                    "type": {
+                        "raw": "\"text\" | \"avator\" | \"image\" | \"button\" | \"input\"",
+                        "kind": "union",
+                        "unionTypes": [
+                            "text",
+                            "avator",
+                            "image",
+                            "button",
+                            "input"
+                        ]
+                    },
+                    "required": false,
+                    "default": "\"text\"",
+                    "allowedValues": [
+                        {
+                            "value": "text",
+                            "label": "文本行",
+                            "isDefault": true
+                        },
+                        {
+                            "value": "avator",
+                            "label": "头像占位"
+                        },
+                        {
+                            "value": "image",
+                            "label": "图片占位"
+                        },
+                        {
+                            "value": "button",
+                            "label": "按钮占位"
+                        },
+                        {
+                            "value": "input",
+                            "label": "输入框占位"
+                        }
+                    ],
+                    "usageExample": "<SkeletonItem type=\"image\" />"
+                }
+            ]
+        }
+    ],
+    "examples": [
+        {
+            "id": "skeleton_basic",
+            "title": "基础用法",
+            "description": "展示默认文本骨架。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Skeleton } from '@king-design/vue';\n\nconst loading = ref(true);\n</script>\n<template>\n  <Skeleton :loading=\"loading\" :rows=\"3\" animated />\n</template>",
+            "tags": [
+                "basic",
+                "loading"
+            ],
+            "usedProps": [
+                "loading",
+                "rows",
+                "animated"
+            ],
+            "usedEvents": [],
+            "usedSlots": [],
+            "usedMethods": [],
+            "scenario": "列表请求中展示文本占位"
+        },
+        {
+            "id": "skeleton_avatar",
+            "title": "带头像骨架",
+            "description": "适合用户卡片、评论列表等结构。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Skeleton } from '@king-design/vue';\n\nconst loading = ref(true);\n</script>\n<template>\n  <Skeleton :loading=\"loading\" avator :rows=\"2\" />\n</template>",
+            "tags": [
+                "avator",
+                "card"
+            ],
+            "usedProps": [
+                "loading",
+                "avator",
+                "rows"
+            ],
+            "usedEvents": [],
+            "usedSlots": [],
+            "usedMethods": [],
+            "scenario": "个人信息卡片加载态"
+        },
+        {
+            "id": "skeleton_custom_layout",
+            "title": "自定义骨架布局",
+            "description": "通过 SkeletonItem 自定义表单或卡片骨架。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Skeleton, SkeletonItem } from '@king-design/vue';\n\nconst loading = ref(true);\n</script>\n<template>\n  <Skeleton :loading=\"loading\">\n    <div style=\"display: flex; gap: 12px; align-items: flex-start;\">\n      <SkeletonItem type=\"image\" />\n      <div style=\"flex: 1; display: grid; gap: 8px;\">\n        <SkeletonItem type=\"text\" />\n        <SkeletonItem type=\"input\" />\n        <SkeletonItem type=\"button\" />\n      </div>\n    </div>\n  </Skeleton>\n</template>",
+            "tags": [
+                "custom",
+                "item"
+            ],
+            "usedProps": [
+                "loading"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "自定义复杂卡片骨架"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "skeleton_expect_real_content_switch",
+            "description": "误以为 Skeleton 会自动在 loading=false 时渲染真实内容",
+            "wrongCode": "<Skeleton :loading=\"loading\"><RealContent /></Skeleton>",
+            "correctCode": "<Skeleton :loading=\"loading\"><SkeletonItem type=\"text\" /></Skeleton>\n<RealContent v-if=\"!loading\" />",
+            "explanation": "当前 Skeleton 在 loading 为 true 时负责渲染骨架结构，真实内容建议由外层通过条件渲染控制。",
+            "relatedProps": [
+                "loading"
+            ]
+        },
+        {
+            "id": "skeleton_avatar_spelling",
+            "description": "把 avator 错写成 avatar",
+            "wrongCode": "<Skeleton :loading=\"loading\" avatar />",
+            "correctCode": "<Skeleton :loading=\"loading\" avator />",
+            "explanation": "该组件实际属性名是 avator，需按源码字段使用，否则不会展示头像骨架。",
+            "relatedProps": [
+                "avator"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "skeleton",
+        "骨架屏",
+        "loading",
+        "占位",
+        "avator",
+        "SkeletonItem"
+    ],
+    "useCases": [
+        "列表加载占位",
+        "详情页内容预加载",
+        "卡片骨架",
+        "表单异步初始化"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SkeletonItemType",
+            "definition": "type SkeletonItemType = 'text' | 'title' | 'avatar' | 'image' | 'button'",
+            "description": "骨架子项类型枚举，用于描述不同占位形态。"
+        }
+    ],
+    "relatedComponents": [
+        "Spin",
+        "Card",
+        "Image"
+    ]
+}

package/components/spin.json

@@ -225,8 +225,15 @@
         "表单提交等待",
         "卡片内容加载"
     ],
+    "typeDefinitions": [
+        {
+            "name": "SpinSize",
+            "definition": "type SpinSize = 'large' | 'default' | 'small' | 'mini'",
+            "description": "加载器尺寸枚举。"
+        }
+    ],
     "relatedComponents": [
         "Skeleton",
         "Progress"
     ]
-}
+}