king-design-analyzer 2.1.9 → 2.2.0

package/components/projects.json

@@ -0,0 +1,129 @@
+{
+    "id": "projects",
+    "name": "Projects",
+    "displayName": "项目选择",
+    "category": "form",
+    "description": "用于拉取并选择当前账号项目归属的业务组件，适合在创建资源、共享资源和权限分配场景中选择项目上下文。",
+    "importStatement": "import { Projects } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "当前选中的项目 ID",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false
+        },
+        {
+            "name": "href",
+            "description": "跳转到项目管理页的链接",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false
+        }
+    ],
+    "events": [
+        {
+            "name": "update:modelValue",
+            "vueEventName": "@update:modelValue",
+            "description": "选中的项目 ID 变化时触发，适合与表单主值同步。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "number",
+                    "description": "当前选中的项目 ID。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "update:project",
+            "vueEventName": "@update:project",
+            "description": "选中的完整项目对象变化时触发，便于读取项目名称或配额信息。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "ProjectItem",
+                    "description": "当前选中的完整项目对象。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "projects_resource_owner",
+            "title": "选择资源所属项目",
+            "description": "在创建资源时把项目选择作为基础表单项。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Projects } from '@ksyun-internal/versatile';\n\nconst projectId = ref(1001);\n</script>\n\n<template>\n  <Projects v-model=\"projectId\" href=\"/project/list\" />\n</template>",
+            "tags": [
+                "project",
+                "form"
+            ],
+            "usedProps": [
+                "modelValue",
+                "href"
+            ],
+            "usedEvents": [
+                "update:modelValue",
+                "update:project"
+            ],
+            "usedMethods": [],
+            "scenario": "在创建资源或授权时指定资源归属项目。"
+        },
+        {
+            "id": "projects_sync_entity",
+            "title": "同步项目实体信息",
+            "description": "监听项目实体变化，在选择项目后立即拿到完整项目信息。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Projects } from '@ksyun-internal/versatile';\n\nconst projectId = ref<number | undefined>(undefined);\nconst projectName = ref('未选择');\nconst handleProjectChange = (project: { name?: string }) => {\n  projectName.value = project?.name || '未选择';\n};\n</script>\n\n<template>\n  <Projects\n    v-model=\"projectId\"\n    href=\"/project/list\"\n    @update:project=\"handleProjectChange\"\n  />\n  <div>当前项目：{{ projectName }}</div>\n</template>",
+            "tags": [
+                "project",
+                "entity"
+            ],
+            "usedProps": [
+                "modelValue",
+                "href"
+            ],
+            "usedEvents": [
+                "update:modelValue",
+                "update:project"
+            ],
+            "usedMethods": [],
+            "scenario": "在选择项目后联动展示项目名称、配额或权限等附加信息。"
+        }
+    ],
+    "searchKeywords": [
+        "projects",
+        "project selector",
+        "项目选择",
+        "项目归属",
+        "资源所属项目",
+        "project select",
+        "项目下拉",
+        "项目切换"
+    ],
+    "useCases": [
+        "项目归属选择",
+        "资源所属项目配置",
+        "按项目切换资源上下文",
+        "选择后联动项目实体信息"
+    ],
+    "relatedComponents": [
+        "Region",
+        "AZ"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "ProjectItem",
+            "definition": "type ProjectItem = {\n  id: number\n  name: string\n}",
+            "description": "项目数据项，描述项目的主键和展示名称。"
+        }
+    ]
+}

package/components/protable.json

@@ -5,6 +5,14 @@
     "category": "data",
     "description": "集成了搜索、筛选、排序、分页、工具栏等功能的高级表格组件。",
     "importStatement": "import { ProTable } from '@ksyun-internal/versatile';",
+    "inherits": [
+        {
+            "component": "Table",
+            "include": [
+                "props"
+            ]
+        }
+    ],
     "props": [
         {
             "name": "data",
@@ -78,27 +86,86 @@
         {
             "name": "change:searchValue",
             "vueEventName": "@change:searchValue",
-            "description": "搜索框内容变更时触发"
+            "description": "搜索框内容变更时触发",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前搜索框中的检索值。"
+                },
+                {
+                    "name": "label",
+                    "type": "string",
+                    "description": "当前搜索值对应的展示文案，选择型搜索时可直接用于回显。",
+                    "optional": true
+                },
+                {
+                    "name": "current",
+                    "type": "SearchType",
+                    "description": "当前正在使用的搜索项配置。",
+                    "optional": true
+                },
+                {
+                    "name": "obj",
+                    "type": "Record<string, any> | null",
+                    "description": "选择型搜索命中的原始选项对象；纯输入搜索通常为 `null`。",
+                    "optional": true
+                }
+            ]
         },
         {
             "name": "change:searchKey",
             "vueEventName": "@change:searchKey",
-            "description": "搜索 Key 变更时触发"
+            "description": "搜索 Key 变更时触发",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前选中的搜索字段 key。"
+                },
+                {
+                    "name": "current",
+                    "type": "SearchType",
+                    "description": "当前激活的搜索项配置对象。",
+                    "optional": true
+                }
+            ]
         },
         {
             "name": "change:columns",
             "vueEventName": "@change:columns",
-            "description": "列设置变更时触发"
+            "description": "列设置变更时触发",
+            "params": [
+                {
+                    "name": "data",
+                    "type": "string[]",
+                    "description": "当前保留展示的列 key 列表，可直接用于持久化用户列设置。"
+                }
+            ]
         },
         {
             "name": "change:filters",
             "vueEventName": "@change:filters",
-            "description": "筛选条件变更时触发"
+            "description": "筛选条件变更时触发",
+            "params": [
+                {
+                    "name": "data",
+                    "type": "TableGroupValue",
+                    "description": "当前表格分组或筛选条件对象，通常用于组装请求参数。"
+                }
+            ]
         },
         {
             "name": "change:export",
             "vueEventName": "@change:export",
-            "description": "导出配置变更时触发，payload 包含 selectedKeys 和 exportRange"
+            "description": "导出配置变更时触发，payload 包含 selectedKeys 和 exportRange",
+            "params": [
+                {
+                    "name": "data",
+                    "type": "ExportConfig",
+                    "description": "当前导出配置，包含待导出列 key 和导出范围标识。"
+                }
+            ]
         }
     ],
     "slots": [
@@ -123,10 +190,32 @@
         "filter",
         "list",
         "表格",
-        "pro"
+        "pro",
+        "高级表格",
+        "资源列表"
     ],
     "useCases": [
         "资源列表页",
-        "复杂数据展示"
+        "复杂数据展示",
+        "带搜索导出和列设置的高级列表",
+        "资源管理后台表格页"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "TableHeaderProps",
+            "definition": "type TableHeaderProps = {\\n  show?: boolean\\n  toolbar?: Record<string, any>\\n  search?: Record<string, any>\\n  filter?: Record<string, any>\\n}",
+            "description": "ProTable 头部工具栏配置结构，包含搜索、刷新、导出和列设置等区域。"
+        },
+        {
+            "name": "ExportConfig",
+            "definition": "type ExportConfig = {\\n  selectedKeys: string[]\\n  exportRange: string\\n}",
+            "description": "导出动作回调中的配置对象，描述导出列范围和导出范围类型。"
+        }
+    ],
+    "relatedComponents": [
+        "Table",
+        "Search",
+        "SearchItems",
+        "PaginationPlus"
     ]
-}
+}

package/components/queuevisualrange.json

@@ -0,0 +1,110 @@
+{
+    "id": "queuevisualrange",
+    "name": "QueueVisualRange",
+    "displayName": "队列可见范围",
+    "category": "form",
+    "description": "用于配置队列、任务或资源可见范围的业务组件，适合在私有、项目共享、全员可见等可见性策略之间切换。",
+    "importStatement": "import { QueueVisualRange } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "当前可见范围值",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "tip",
+            "description": "说明提示文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false
+        }
+    ],
+    "events": [
+        {
+            "name": "update:modelValue",
+            "vueEventName": "@update:modelValue",
+            "description": "可见范围变化时触发，可据此同步权限或共享策略配置。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前选中的可见范围标识。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "queuevisualrange_visibility",
+            "title": "设置队列可见范围",
+            "description": "在新建队列时选择私有或共享范围。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { QueueVisualRange } from '@ksyun-internal/versatile';\n\nconst visualRange = ref('project');\n</script>\n\n<template>\n  <QueueVisualRange v-model=\"visualRange\" tip=\"共享范围越大，越需要关注访问控制\" />\n</template>",
+            "tags": [
+                "visibility",
+                "permission"
+            ],
+            "usedProps": [
+                "modelValue",
+                "tip"
+            ],
+            "usedEvents": [
+                "update:modelValue"
+            ],
+            "usedMethods": [],
+            "scenario": "在任务或资源配置页选择共享和可见性范围。"
+        },
+        {
+            "id": "queuevisualrange_share_scope",
+            "title": "共享范围选择联动说明",
+            "description": "在切换可见范围时同步展示额外说明文案。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { QueueVisualRange } from '@ksyun-internal/versatile';\n\nconst visualRange = ref('private');\n</script>\n\n<template>\n  <QueueVisualRange\n    v-model=\"visualRange\"\n    tip=\"选择项目共享后，同项目成员均可查看该队列\"\n  />\n</template>",
+            "tags": [
+                "visibility",
+                "share"
+            ],
+            "usedProps": [
+                "modelValue",
+                "tip"
+            ],
+            "usedEvents": [
+                "update:modelValue"
+            ],
+            "usedMethods": [],
+            "scenario": "在队列和任务创建时明确不同共享范围的含义。"
+        }
+    ],
+    "searchKeywords": [
+        "queue visual range",
+        "visibility scope",
+        "队列可见范围",
+        "可见性",
+        "共享范围"
+    ],
+    "useCases": [
+        "队列权限范围配置",
+        "资源共享范围设置",
+        "共享范围说明和切换"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "QueueVisualRangeValue",
+            "definition": "type QueueVisualRangeValue = string | number",
+            "description": "可见范围选项值类型，可用字符串或数值标识不同共享范围。"
+        }
+    ],
+    "relatedComponents": [
+        "Visibility"
+    ]
+}

package/components/radio.json

@@ -48,7 +48,80 @@
             },
             "required": false,
             "default": "undefined",
-            "usageExample": "<Radio name=\"gender\" trueValue=\"male\">男</Radio>\n<Radio name=\"gender\" trueValue=\"female\">女</Radio>"
+            "usageExample": "<Radio name=\"gender\" trueValue=\"male\">男</Radio>\n<Radio name=\"gender\" trueValue=\"female\">女</Radio>",
+            "tags": [
+                "native"
+            ]
+        },
+        {
+            "name": "autocomplete",
+            "description": "原生 autocomplete 属性，指定浏览器自动补全行为",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Radio autocomplete=\"off\">选项</Radio>",
+            "tags": [
+                "native"
+            ]
+        },
+        {
+            "name": "autofocus",
+            "description": "原生 autofocus 属性，页面加载后自动聚焦单选框",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Radio autofocus trueValue=\"a\">选项 A</Radio>",
+            "tags": [
+                "native"
+            ]
+        },
+        {
+            "name": "form",
+            "description": "原生 form 属性，指定单选框关联的表单 id",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Radio form=\"myForm\" trueValue=\"a\">选项 A</Radio>",
+            "tags": [
+                "native"
+            ]
+        },
+        {
+            "name": "maxlength",
+            "description": "原生 maxlength 属性，组件透传到内部 input 元素",
+            "type": {
+                "raw": "number | string",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Radio :maxlength=\"1\" trueValue=\"a\">选项 A</Radio>",
+            "tags": [
+                "native"
+            ]
+        },
+        {
+            "name": "required",
+            "description": "原生 required 属性，标记为必选输入项",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Radio required trueValue=\"a\">选项 A</Radio>",
+            "tags": [
+                "native"
+            ]
         }
     ],
     "events": [
@@ -238,9 +311,16 @@
         "等级/类型选择",
         "问卷中的单选题"
     ],
+    "typeDefinitions": [
+        {
+            "name": "RadioValue",
+            "definition": "type RadioValue = string | number | boolean",
+            "description": "单选框绑定值类型，可通过 trueValue 自定义为字符串、数字或布尔值。"
+        }
+    ],
     "relatedComponents": [
         "Checkbox",
         "ButtonGroup",
         "Select"
     ]
-}
+}

package/components/rate.json

@@ -0,0 +1,199 @@
+{
+    "id": "rate",
+    "name": "Rate",
+    "displayName": "评分",
+    "category": "form",
+    "description": "评分组件，用于展示和选择星级评分。支持半星、禁用态、自定义总数以及再次点击清空评分。",
+    "importStatement": "import { Rate } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "value",
+            "description": "当前评分值，可用 v-model 双向绑定。",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "0",
+            "usageExample": "<Rate v-model=\"score\" />"
+        },
+        {
+            "name": "count",
+            "description": "总星数。",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "5",
+            "usageExample": "<Rate v-model=\"score\" :count=\"10\" />"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用。禁用后只展示当前值，不响应 hover 和点击。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Rate :value=\"4\" disabled />"
+        },
+        {
+            "name": "half",
+            "description": "是否允许半星评分。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Rate v-model=\"score\" half />"
+        },
+        {
+            "name": "clearable",
+            "description": "是否允许点击当前值后清空评分。",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Rate v-model=\"score\" clearable />"
+        }
+    ],
+    "events": [
+        {
+            "name": "mouseleave",
+            "vueEventName": "@mouseleave",
+            "description": "鼠标离开评分区域时触发，通常用于结束悬停预览。",
+            "payload": [
+                {
+                    "name": "e",
+                    "type": "MouseEvent",
+                    "description": "原生鼠标事件"
+                }
+            ],
+            "usageExample": "<Rate @mouseleave=\"handleMouseLeave\" />",
+            "handlerExample": "const handleMouseLeave = (e: MouseEvent) => {\n  console.log('离开评分区域');\n};"
+        }
+    ],
+    "slots": [
+        {
+            "name": "icon",
+            "description": "自定义每一项评分图标，默认使用星形图标。",
+            "vueTemplate": "<template #icon>...</template>",
+            "usageExample": "<Rate v-model=\"score\"><template #icon><Icon class=\"k-icon-favorite\" /></template></Rate>"
+        }
+    ],
+    "methods": [],
+    "examples": [
+        {
+            "id": "rate_basic",
+            "title": "基础用法",
+            "description": "用户评分输入。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Rate } from '@king-design/vue';\n\nconst score = ref(3);\n</script>\n<template>\n  <Rate v-model=\"score\" />\n</template>",
+            "tags": [
+                "basic",
+                "v-model"
+            ],
+            "usedProps": [
+                "value"
+            ],
+            "usedEvents": [],
+            "usedSlots": [],
+            "usedMethods": [],
+            "scenario": "收集用户星级评分"
+        },
+        {
+            "id": "rate_half_clearable",
+            "title": "半星和可清空",
+            "description": "适合更细粒度的打分场景。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Rate } from '@king-design/vue';\n\nconst score = ref(3.5);\n</script>\n<template>\n  <Rate v-model=\"score\" half clearable />\n</template>",
+            "tags": [
+                "half",
+                "clearable"
+            ],
+            "usedProps": [
+                "value",
+                "half",
+                "clearable"
+            ],
+            "usedEvents": [],
+            "usedSlots": [],
+            "usedMethods": [],
+            "scenario": "允许半星和取消评分"
+        },
+        {
+            "id": "rate_custom_icon",
+            "title": "自定义图标",
+            "description": "使用心形图标替代默认星形。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Icon, Rate } from '@king-design/vue';\n\nconst score = ref(4);\n</script>\n<template>\n  <Rate v-model=\"score\">\n    <template #icon>\n      <Icon class=\"k-icon-heart\" />\n    </template>\n  </Rate>\n</template>",
+            "tags": [
+                "slot",
+                "icon"
+            ],
+            "usedProps": [
+                "value"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "icon"
+            ],
+            "usedMethods": [],
+            "scenario": "在点赞或喜爱度场景中使用心形评分"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "rate_decimal_without_half",
+            "description": "传入小数评分但未开启 half",
+            "wrongCode": "<Rate :value=\"3.5\" />",
+            "correctCode": "<Rate :value=\"3.5\" half />",
+            "explanation": "如果需要展示或选择半星评分，应显式开启 half，否则组件按整星交互处理。",
+            "relatedProps": [
+                "value",
+                "half"
+            ]
+        },
+        {
+            "id": "rate_expect_clear_without_clearable",
+            "description": "期望再次点击清空评分但未开启 clearable",
+            "wrongCode": "<Rate v-model=\"score\" />",
+            "correctCode": "<Rate v-model=\"score\" clearable />",
+            "explanation": "默认再次点击当前星级不会清空值，如需允许取消评分，应开启 clearable。",
+            "relatedProps": [
+                "clearable"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "rate",
+        "评分",
+        "星级",
+        "打分",
+        "半星",
+        "clearable"
+    ],
+    "useCases": [
+        "商品评价",
+        "服务满意度评分",
+        "内容点赞等级",
+        "后台数据展示只读评分"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "RateValue",
+            "definition": "type RateValue = number",
+            "description": "评分值类型，支持整数评分和 half 模式下的小数评分。"
+        }
+    ],
+    "relatedComponents": [
+        "Icon",
+        "Tag",
+        "Tooltip"
+    ]
+}