king-design-analyzer 2.1.7 → 2.2.0

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/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": "搜索项分组配置，用于把多个搜索字段按业务域归类展示。"
+        }
+    ]
+}

package/components/searchinput.json

@@ -0,0 +1,132 @@
+{
+    "id": "searchinput",
+    "name": "SearchInput",
+    "displayName": "搜索输入框",
+    "category": "form",
+    "description": "轻量搜索输入框组件，适合工具栏关键词过滤、输入即搜或与列表查询按钮配套使用。",
+    "importStatement": "import { SearchInput } from '@ksyun-internal/versatile';",
+    "inherits": [
+        {
+            "component": "Input",
+            "include": [
+                "props"
+            ],
+            "exclude": [
+                "value",
+                "defaultValue"
+            ]
+        }
+    ],
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "输入框当前值",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "clearable",
+            "description": "是否显示清空按钮",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false"
+        }
+    ],
+    "events": [
+        {
+            "name": "clear",
+            "vueEventName": "@clear",
+            "description": "用户清空关键词时触发，通常用于恢复默认列表数据。"
+        },
+        {
+            "name": "change:value",
+            "vueEventName": "@change:value",
+            "description": "搜索关键词完成一次确认输入时触发，适合发起查询请求。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "本次确认提交的关键词。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "searchinput_toolbar",
+            "title": "工具栏关键字过滤",
+            "description": "在列表工具栏放置一个轻量搜索框，按名称快速过滤资源。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchInput } from '@ksyun-internal/versatile';\n\nconst keyword = ref('');\n</script>\n\n<template>\n  <SearchInput v-model=\"keyword\" :clearable=\"true\" placeholder=\"搜索实例名称\" />\n</template>",
+            "tags": [
+                "search",
+                "input"
+            ],
+            "usedProps": [
+                "modelValue",
+                "clearable",
+                "placeholder"
+            ],
+            "usedEvents": [
+                "change:value",
+                "clear"
+            ],
+            "usedMethods": [],
+            "scenario": "在工具栏中提供单关键字快速搜索。"
+        },
+        {
+            "id": "searchinput_confirm_query",
+            "title": "监听确认输入发起搜索",
+            "description": "通过 change:value 在用户确认输入后发起查询。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchInput } from '@ksyun-internal/versatile';\n\nconst keyword = ref('');\nconst handleChange = (value: string) => {\n  console.log('query keyword:', value);\n};\n</script>\n\n<template>\n  <SearchInput\n    v-model=\"keyword\"\n    placeholder=\"请输入镜像名称\"\n    @change:value=\"handleChange\"\n  />\n</template>",
+            "tags": [
+                "search",
+                "event"
+            ],
+            "usedProps": [
+                "modelValue",
+                "placeholder"
+            ],
+            "usedEvents": [
+                "change:value"
+            ],
+            "usedMethods": [],
+            "scenario": "在用户回车或确认输入时再发起一次正式查询。"
+        }
+    ],
+    "searchKeywords": [
+        "search input",
+        "keyword search",
+        "输入搜索",
+        "搜索输入框",
+        "关键字过滤",
+        "单字段搜索"
+    ],
+    "useCases": [
+        "列表页关键字输入",
+        "工具栏快捷搜索",
+        "确认输入后发起查询"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SearchInputValue",
+            "definition": "type SearchInputValue = string",
+            "description": "搜索输入框绑定值类型。"
+        }
+    ],
+    "relatedComponents": [
+        "Search",
+        "Input"
+    ]
+}

package/components/searchitems.json

@@ -0,0 +1,215 @@
+{
+    "id": "searchitems",
+    "name": "SearchItems",
+    "displayName": "检索项",
+    "category": "form",
+    "description": "用于展示和管理当前检索条件标签的组件，适合复杂筛选场景中回显用户已选条件，并支持快速删除和清空。",
+    "importStatement": "import { SearchItems } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "检索项数据对象",
+            "type": {
+                "raw": "Record<string, string | number>",
+                "kind": "object"
+            },
+            "required": false,
+            "default": "{}"
+        },
+        {
+            "name": "searchKey",
+            "description": "持久化存储时使用的 key",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "title",
+            "description": "检索项区域标题",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"检索项\""
+        },
+        {
+            "name": "separator",
+            "description": "多值拼接分隔符",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"|\""
+        },
+        {
+            "name": "placeholderSeparator",
+            "description": "占位分隔符匹配规则",
+            "type": {
+                "raw": "string | RegExp",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "/,+|\\|+/g"
+        }
+    ],
+    "events": [
+        {
+            "name": "delete:item",
+            "vueEventName": "@delete:item",
+            "description": "删除单个检索条件时触发，可用于同步列表查询参数。",
+            "params": [
+                {
+                    "name": "key",
+                    "type": "string",
+                    "description": "被删除检索项所属的分组 key，通常对应当前列表或筛选区的唯一标识。",
+                    "optional": true
+                },
+                {
+                    "name": "value",
+                    "type": "SearchItem",
+                    "description": "被删除的检索项对象，包含 label、key、text、value 等字段。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "delete:all",
+            "vueEventName": "@delete:all",
+            "description": "清空全部检索条件时触发，通常配合重置分页和重新拉取数据。"
+        }
+    ],
+    "slots": [],
+    "methods": [
+        {
+            "name": "get",
+            "description": "获取当前组件维护的全部检索项，用于外部读取当前筛选状态。",
+            "returnType": "SearchItem[]"
+        },
+        {
+            "name": "add",
+            "description": "追加一个新的检索条件，并立即同步到当前检索项列表中。",
+            "params": [
+                {
+                    "name": "searchItem",
+                    "type": "SearchItem",
+                    "description": "待追加的检索项对象，通常包含 key、label 和 value。"
+                }
+            ],
+            "returnType": "void"
+        },
+        {
+            "name": "del",
+            "description": "按照给定条件删除一个已存在的检索项。",
+            "params": [
+                {
+                    "name": "item",
+                    "type": "Partial<SearchItem>",
+                    "description": "用于匹配删除目标的条件对象，可传 key、label 或 value。"
+                },
+                {
+                    "name": "unique",
+                    "type": "boolean",
+                    "description": "是否按唯一条件精确删除匹配项，适合区分同 key 下的多个候选值。",
+                    "optional": true,
+                    "default": "false"
+                },
+                {
+                    "name": "isTriggerEmit",
+                    "type": "boolean",
+                    "description": "删除后是否继续触发组件事件，批量同步内部状态时可按需关闭。",
+                    "optional": true,
+                    "default": "true"
+                }
+            ],
+            "returnType": "void"
+        },
+        {
+            "name": "clear",
+            "description": "清空当前 searchKey 下保存的检索项，常用于重置单个列表视图的筛选状态。",
+            "returnType": "void"
+        },
+        {
+            "name": "clearAll",
+            "description": "清空组件维护的全部检索项，通常用于一键重置筛选条件。",
+            "returnType": "void"
+        }
+    ],
+    "examples": [
+        {
+            "id": "searchitems_filters",
+            "title": "复杂筛选条件回显",
+            "description": "把当前列表的多个过滤条件展示为可删除的检索项。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchItems } from '@ksyun-internal/versatile';\n\nconst filters = ref({\n  name: 'web-prod',\n  status: 'running',\n  project: '核心项目',\n});\n</script>\n\n<template>\n  <SearchItems v-model=\"filters\" search-key=\"instance-list\" title=\"当前筛选\" />\n</template>",
+            "tags": [
+                "search",
+                "filters"
+            ],
+            "usedProps": [
+                "modelValue",
+                "searchKey",
+                "title"
+            ],
+            "usedEvents": [
+                "delete:item",
+                "delete:all"
+            ],
+            "usedMethods": [],
+            "scenario": "在复杂列表页中回显并管理用户已选择的过滤条件。"
+        },
+        {
+            "id": "searchitems_ref_methods",
+            "title": "通过组件方法清空检索项",
+            "description": "使用 ref 调用 clearAll，在切换列表视图时统一重置筛选条件。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchItems } from '@ksyun-internal/versatile';\n\nconst searchItemsRef = ref<InstanceType<typeof SearchItems>>();\nconst filters = ref({\n  name: 'web-prod',\n  project: '核心项目',\n});\nconst resetFilters = () => {\n  searchItemsRef.value?.clearAll();\n};\n</script>\n\n<template>\n  <button @click=\"resetFilters\">重置全部筛选</button>\n  <SearchItems ref=\"searchItemsRef\" v-model=\"filters\" search-key=\"instance-list\" />\n</template>",
+            "tags": [
+                "search",
+                "methods"
+            ],
+            "usedProps": [
+                "modelValue",
+                "searchKey"
+            ],
+            "usedEvents": [
+                "delete:all"
+            ],
+            "usedMethods": [
+                "clearAll"
+            ],
+            "scenario": "在切换页签或重置查询条件时，从外部统一清空当前检索项。"
+        }
+    ],
+    "searchKeywords": [
+        "search items",
+        "filters",
+        "filter tags",
+        "检索项",
+        "筛选条件",
+        "条件回显",
+        "搜索标签",
+        "已选条件"
+    ],
+    "useCases": [
+        "复杂检索条件回显",
+        "列表页多条件筛选",
+        "已选条件快速删除",
+        "列表页筛选状态持久化"
+    ],
+    "relatedComponents": [
+        "Search",
+        "ProTable"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SearchItem",
+            "definition": "type SearchItem = {\n  key: string\n  label?: string\n  value: string | number\n}",
+            "description": "单个检索项的数据结构，描述筛选条件的键、展示文案和值。"
+        }
+    ]
+}