king-design-analyzer 2.1.9 → 2.2.1

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": "单个检索项的数据结构，描述筛选条件的键、展示文案和值。"
+        }
+    ]
+}

package/components/searchselect.json

@@ -0,0 +1,195 @@
+{
+    "id": "searchselect",
+    "name": "SearchSelect",
+    "displayName": "搜索下拉框",
+    "category": "form",
+    "description": "面向搜索维度或搜索值选择的业务下拉组件，适合在搜索框左侧选择字段，也适合承载小规模筛选选项。",
+    "importStatement": "import { SearchSelect } from '@ksyun-internal/versatile';",
+    "inherits": [
+        {
+            "component": "Select",
+            "include": [
+                "props"
+            ],
+            "exclude": [
+                "value"
+            ]
+        }
+    ],
+    "props": [
+        {
+            "name": "label",
+            "description": "下拉框前置标题或说明文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "helper",
+            "description": "辅助提示文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "modelValue",
+            "description": "当前选中的值",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "searches",
+            "description": "搜索选项列表",
+            "type": {
+                "raw": "SearchType[] | Record<string, SearchType>",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "[]"
+        },
+        {
+            "name": "searchKeyName",
+            "description": "搜索项中 value 字段名",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"key\""
+        },
+        {
+            "name": "searchLabelName",
+            "description": "搜索项中 label 字段名",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"label\""
+        },
+        {
+            "name": "searchGroups",
+            "description": "搜索项分组配置",
+            "type": {
+                "raw": "SearchGroupItem[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "showValue",
+            "description": "选项展示时是否同时显示 value",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false"
+        }
+    ],
+    "events": [
+        {
+            "name": "change:value",
+            "vueEventName": "@change:value",
+            "description": "下拉选中值变化时触发，通常用于联动输入框占位或直接发起查询。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "当前选中的搜索项 key。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [],
+    "examples": [
+        {
+            "id": "searchselect_type",
+            "title": "选择搜索维度",
+            "description": "在组合搜索中用下拉框切换当前搜索字段。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchSelect } from '@ksyun-internal/versatile';\n\nconst searchKey = ref('name');\nconst searches = [\n  { key: 'name', label: '实例名称' },\n  { key: 'id', label: '实例 ID' },\n  { key: 'ip', label: '内网 IP' },\n];\n</script>\n\n<template>\n  <SearchSelect\n    v-model=\"searchKey\"\n    label=\"搜索字段\"\n    :searches=\"searches\"\n  />\n</template>",
+            "tags": [
+                "search",
+                "select"
+            ],
+            "usedProps": [
+                "modelValue",
+                "label",
+                "searches"
+            ],
+            "usedEvents": [
+                "change:value"
+            ],
+            "usedMethods": [],
+            "scenario": "在列表搜索区切换当前按哪个字段检索。"
+        },
+        {
+            "id": "searchselect_show_value",
+            "title": "同时展示标签和值",
+            "description": "在选项较多时同时展示 value，方便用户准确识别字段。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SearchSelect } from '@ksyun-internal/versatile';\n\nconst searchKey = ref('instanceId');\nconst searches = [\n  { key: 'instanceId', label: '实例 ID' },\n  { key: 'privateIp', label: '内网 IP' },\n  { key: 'projectId', label: '项目 ID' },\n];\n</script>\n\n<template>\n  <SearchSelect\n    v-model=\"searchKey\"\n    :searches=\"searches\"\n    helper=\"请选择检索字段\"\n    :show-value=\"true\"\n  />\n</template>",
+            "tags": [
+                "search",
+                "value"
+            ],
+            "usedProps": [
+                "modelValue",
+                "searches",
+                "helper",
+                "showValue"
+            ],
+            "usedEvents": [
+                "change:value"
+            ],
+            "usedMethods": [],
+            "scenario": "在字段名称可能重复或歧义较大时同时展示 key 和 label。"
+        }
+    ],
+    "searchKeywords": [
+        "search select",
+        "search field select",
+        "filter select",
+        "下拉搜索",
+        "搜索下拉框",
+        "检索字段选择",
+        "筛选字段",
+        "条件下拉"
+    ],
+    "useCases": [
+        "搜索类型选择",
+        "业务下拉筛选",
+        "组合搜索左侧字段切换",
+        "小规模筛选项选择"
+    ],
+    "relatedComponents": [
+        "Search",
+        "Select"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "SearchType",
+            "definition": "type SearchType = {\n  key: string\n  label: string\n  helper?: string\n  disabled?: boolean\n}",
+            "description": "下拉中可选的搜索字段配置，至少包含 key 和 label。"
+        },
+        {
+            "name": "SearchGroupItem",
+            "definition": "type SearchGroupItem = {\n  label: string\n  keys: string[]\n}",
+            "description": "搜索字段分组配置，用于按资源域或功能域展示下拉选项。"
+        }
+    ]
+}