king-design-analyzer 2.1.9 → 2.2.1

package/components/rate.json

@@ -0,0 +1,200 @@
+{
+    "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": "自定义每一项评分图标，默认使用星形图标。",
+            "bindingType": "none",
+            "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"
+    ]
+}

package/components/region.json

@@ -106,10 +106,22 @@
     "area",
     "location",
     "地域",
-    "区域"
+    "区域",
+    "大区",
+    "region select",
+    "地域选择"
   ],
   "useCases": [
     "购买页选择地域",
-    "列表页筛选地域"
+    "列表页筛选地域",
+    "资源创建时切换可售卖地域",
+    "和 AZ 联动选择地域与可用区"
+  ],
+  "typeDefinitions": [
+    {
+      "name": "RegionItem",
+      "definition": "type RegionItem = {\\n  code: string\\n  name: string\\n  areaCode?: string\\n}",
+      "description": "地域配置项结构，包含地域编码、展示名称和所属大区。"
+    }
   ]
 }

package/components/scrollselect.json

@@ -0,0 +1,140 @@
+{
+    "id": "scrollselect",
+    "name": "ScrollSelect",
+    "displayName": "滚动选择器",
+    "category": "form",
+    "description": "滚动选择器组件，通过滚轮、拖拽或点击来选择值。适合时间、年份、数值区间等连续选项场景，也可以通过函数动态生成可选数据。",
+    "importStatement": "import { ScrollSelect } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "value",
+            "description": "当前选中值，可用 v-model 双向绑定",
+            "type": {
+                "raw": "T",
+                "kind": "generic"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<ScrollSelect v-model=\"year\" :data=\"years\" />"
+        },
+        {
+            "name": "count",
+            "description": "可视区域中渲染的数据个数",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "5",
+            "usageExample": "<ScrollSelect :count=\"10\" />"
+        },
+        {
+            "name": "data",
+            "description": "可选数据列表，或根据当前值动态生成数据的方法",
+            "type": {
+                "raw": "Data<T> = DataItem<T>[] | ((v: T) => DataItem<T>[])",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "[]",
+            "usageExample": "<ScrollSelect :data=\"[{ value: 1, label: '一月' }]\" />"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用整个选择器",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<ScrollSelect disabled :data=\"years\" />"
+        },
+        {
+            "name": "disable",
+            "description": "按值控制单项是否禁用",
+            "type": {
+                "raw": "(v: T) => boolean",
+                "kind": "function"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<ScrollSelect :disable=\"(v) => v < 2020\" />"
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "append",
+            "description": "在滚动选择器后追加额外内容，例如单位说明",
+            "bindingType": "none",
+            "vueTemplate": "#append",
+            "usageExample": "<ScrollSelect v-model=\"hour\" :data=\"hours\"><template #append>时</template></ScrollSelect>"
+        }
+    ],
+    "methods": [],
+    "examples": [
+        {
+            "id": "scrollselect_basic",
+            "title": "基础用法",
+            "description": "使用静态数据创建一个年份选择器。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { ScrollSelect } from '@king-design/vue';\n\nconst year = ref(2024);\nconst years = Array.from({ length: 7 }, (_, index) => ({\n  value: 2021 + index,\n  label: `${2021 + index} 年`,\n}));\n</script>\n<template>\n  <ScrollSelect v-model=\"year\" :data=\"years\" />\n</template>",
+            "tags": [
+                "basic",
+                "static-data"
+            ],
+            "usedProps": [
+                "value",
+                "data"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "在时间和数值选择场景中提供滚动选择交互。"
+        },
+        {
+            "id": "scrollselect_dynamic",
+            "title": "动态生成数据",
+            "description": "根据当前选中值动态生成附近的年份选项。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { ScrollSelect } from '@king-design/vue';\n\nconst currentYear = ref(2025);\nconst generateYears = (value: number) => {\n  const start = value - 3;\n  return Array.from({ length: 7 }, (_, index) => {\n    const year = start + index;\n    return {\n      value: year,\n      label: `${year} 年`,\n    };\n  });\n};\n</script>\n<template>\n  <ScrollSelect v-model=\"currentYear\" :count=\"7\" :data=\"generateYears\">\n    <template #append>年份</template>\n  </ScrollSelect>\n</template>",
+            "tags": [
+                "dynamic-data",
+                "append"
+            ],
+            "usedProps": [
+                "value",
+                "count",
+                "data"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "append"
+            ],
+            "usedMethods": [],
+            "scenario": "在时间滚轮或区间选择中按需生成可见窗口数据。"
+        }
+    ],
+    "searchKeywords": [
+        "scrollselect",
+        "滚动选择器",
+        "时间滚轮",
+        "year picker"
+    ],
+    "useCases": [
+        "年份或月份选择",
+        "时间滚轮",
+        "连续数值选择"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "ScrollSelectDataItem",
+            "definition": "type ScrollSelectDataItem<T = any> = { value: T; label: Children }",
+            "description": "滚动选择器的数据项结构。"
+        }
+    ],
+    "relatedComponents": [
+        "Datepicker",
+        "Timepicker"
+    ]
+}

package/components/search.json

@@ -0,0 +1,221 @@
+{
+    "id": "search",
+    "name": "Search",
+    "displayName": "组合搜索框",
+    "category": "form",
+    "description": "由搜索类型选择器和输入区域组合而成的业务搜索组件，适合列表页按名称、ID、状态等不同维度快速检索。",
+    "importStatement": "import { Search } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "searchKey",
+            "description": "当前选中的搜索类型 key",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "searchValue",
+            "description": "当前输入或选择的搜索值",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "searches",
+            "description": "搜索配置集合，支持数组或 key-value 对象",
+            "type": {
+                "raw": "SearchType[] | Record<string, SearchType>",
+                "kind": "union"
+            },
+            "required": true
+        },
+        {
+            "name": "searchGroups",
+            "description": "搜索类型分组配置",
+            "type": {
+                "raw": "SearchGroupItem[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "clearable",
+            "description": "是否允许清空搜索值",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false"
+        },
+        {
+            "name": "leftWidth",
+            "description": "左侧搜索类型选择区域宽度",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "120"
+        },
+        {
+            "name": "rightWidth",
+            "description": "右侧搜索输入区域宽度",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "240"
+        }
+    ],
+    "events": [
+        {
+            "name": "clear",
+            "vueEventName": "@clear",
+            "description": "用户点击清空按钮后触发，通常用于重置搜索值并刷新列表。"
+        },
+        {
+            "name": "change:searchKey",
+            "vueEventName": "@change:searchKey",
+            "description": "搜索维度切换时触发，可据此切换占位提示或请求参数。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前选中的搜索字段 key，例如 `name`、`project`、`privateIp`。"
+                },
+                {
+                    "name": "current",
+                    "type": "SearchType",
+                    "description": "当前激活的搜索项配置对象，包含 label、type、placeholder 等信息。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "change:searchValue",
+            "vueEventName": "@change:searchValue",
+            "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
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "search_instance_filters",
+            "title": "实例列表组合搜索",
+            "description": "在一个搜索框内切换按名称、实例 ID 或 IP 搜索。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Search } from '@ksyun-internal/versatile';\n\nconst searchKey = ref('name');\nconst searchValue = ref('web-prod');\nconst searches = [\n  { key: 'name', label: '实例名称', type: 'input', placeholder: '请输入实例名称' },\n  { key: 'id', label: '实例 ID', type: 'input', placeholder: '请输入实例 ID' },\n  { key: 'ip', label: '内网 IP', type: 'input', placeholder: '请输入内网 IP' },\n];\n</script>\n\n<template>\n  <Search\n    v-model:search-key=\"searchKey\"\n    v-model:search-value=\"searchValue\"\n    :searches=\"searches\"\n    :clearable=\"true\"\n  />\n</template>",
+            "tags": [
+                "search",
+                "filter"
+            ],
+            "usedProps": [
+                "searchKey",
+                "searchValue",
+                "searches",
+                "clearable"
+            ],
+            "usedEvents": [
+                "change:searchKey",
+                "change:searchValue",
+                "clear"
+            ],
+            "usedMethods": [],
+            "scenario": "在列表页顶部提供按不同字段切换的统一搜索入口。"
+        },
+        {
+            "id": "search_grouped_filters",
+            "title": "按分组组织搜索条件",
+            "description": "通过 searchGroups 将资源类和网络类搜索条件分组展示。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Search } from '@ksyun-internal/versatile';\n\nconst searchKey = ref('project');\nconst searchValue = ref('core');\nconst searches = {\n  name: { key: 'name', label: '实例名称', type: 'input', placeholder: '请输入实例名称' },\n  project: { key: 'project', label: '项目名称', type: 'input', placeholder: '请输入项目名称' },\n  privateIp: { key: 'privateIp', label: '内网 IP', type: 'input', placeholder: '请输入内网 IP' },\n};\nconst searchGroups = [\n  { label: '资源信息', keys: ['name', 'project'] },\n  { label: '网络信息', keys: ['privateIp'] },\n];\n</script>\n\n<template>\n  <Search\n    v-model:search-key=\"searchKey\"\n    v-model:search-value=\"searchValue\"\n    :searches=\"searches\"\n    :search-groups=\"searchGroups\"\n    :left-width=\"140\"\n    :right-width=\"280\"\n  />\n</template>",
+            "tags": [
+                "search",
+                "groups"
+            ],
+            "usedProps": [
+                "searchKey",
+                "searchValue",
+                "searches",
+                "searchGroups",
+                "leftWidth",
+                "rightWidth"
+            ],
+            "usedEvents": [
+                "change:searchKey",
+                "change:searchValue"
+            ],
+            "usedMethods": [],
+            "scenario": "在复杂列表页中把搜索条件按业务域分组，降低用户选择成本。"
+        }
+    ],
+    "searchKeywords": [
+        "search",
+        "filter",
+        "search bar",
+        "search by field",
+        "组合搜索",
+        "搜索框",
+        "多条件搜索",
+        "字段筛选"
+    ],
+    "useCases": [
+        "列表页关键字搜索",
+        "按类型切换搜索条件",
+        "和 SearchItems 联动的高级检索",
+        "控制台资源列表顶部搜索区"
+    ],
+    "relatedComponents": [
+        "SearchInput",
+        "SearchSelect",
+        "SearchItems",
+        "ProTable"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SearchType",
+            "definition": "type SearchType = {\n  key: string\n  label: string\n  type?: 'input' | 'select' | 'custom'\n  placeholder?: string\n  list?: Array<{ key: string | number; label: string }>\n}",
+            "description": "单个搜索项配置，描述搜索字段、展示文案、输入类型和候选值。"
+        },
+        {
+            "name": "SearchGroupItem",
+            "definition": "type SearchGroupItem = {\n  label: string\n  keys: string[]\n}",
+            "description": "搜索项分组配置，用于把多个搜索字段按业务域归类展示。"
+        }
+    ]
+}