king-design-analyzer 2.1.7 → 2.2.0

package/hooks/useOpenDialog.json

@@ -0,0 +1,43 @@
+{
+  "id": "useOpenDialog",
+  "name": "useOpenDialog",
+  "displayName": "表格操作弹窗",
+  "category": "dialog",
+  "description": "针对表格单行操作和批量操作封装弹窗打开逻辑，统一维护当前操作项和批量操作项集合。",
+  "importStatement": "import { useOpenDialog } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "tableRef",
+      "type": "Ref<Table | undefined>",
+      "required": false,
+      "description": "表格实例引用，批量操作时可从表格中读取选中项"
+    }
+  ],
+  "returnType": "{ isShowDialog: Ref<boolean>; dialogRef: Ref<any>; opCols: Ref<T[] | undefined>; opCol: Ref<T | undefined>; show: Function; hide: Function; handleClickOpBtn: Function; handleClickBatchOpBtn: Function; }",
+  "examples": [
+    {
+      "id": "table_op_dialog",
+      "title": "表格操作弹窗",
+      "description": "点击单行操作按钮时打开弹窗并记录当前行数据",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useOpenDialog } from '@ksyun-internal/versatile';\n\nconst tableRef = ref();\nconst { isShowDialog, opCol, handleClickOpBtn } = useOpenDialog(tableRef);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_table_ref",
+      "description": "批量操作场景未传入 tableRef，导致无法读取选中项",
+      "wrongCode": "const dialog = useOpenDialog();",
+      "correctCode": "const dialog = useOpenDialog(tableRef);",
+      "explanation": "如果需要 handleClickBatchOpBtn 读取表格选中项，应传入 tableRef。"
+    }
+  ],
+  "searchKeywords": [
+    "useOpenDialog",
+    "批量操作",
+    "表格操作",
+    "dialog",
+    "单行操作",
+    "tableRef"
+  ]
+}

package/hooks/usePagination.json

@@ -0,0 +1,49 @@
+{
+  "id": "usePagination",
+  "name": "usePagination",
+  "displayName": "分页状态管理",
+  "category": "pagination",
+  "description": "管理列表页常用的 page、limit、limits 以及分页变更回调，适合和 ProTable、PaginationPlus、Search 组合使用。",
+  "importStatement": "import { usePagination } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ page?: number; limit?: number; limits?: number[]; callback?: (v: PaginationChangeData) => void }",
+      "required": false,
+      "description": "分页初始化配置，可预设页码、每页条数、可选 limits 及翻页后的回调"
+    }
+  ],
+  "returnType": "{ page: Ref<number>; limit: Ref<number>; limits: Ref<number[]>; pageChange: (pageParams: PaginationChangeData) => void; }",
+  "examples": [
+    {
+      "id": "basic_pagination",
+      "title": "基础分页用法",
+      "description": "通过 hook 统一管理列表页码和每页条数",
+      "code": "<script setup lang=\"ts\">\nimport { PaginationPlus, usePagination } from '@ksyun-internal/versatile';\n\nconst { page, limit, pageChange } = usePagination({\n  page: 1,\n  limit: 20,\n});\n</script>\n\n<template>\n  <PaginationPlus v-model=\"page\" v-model:limit=\"limit\" :total=\"200\" @change=\"pageChange\" />\n</template>"
+    },
+    {
+      "id": "with_callback",
+      "title": "带回调的分页",
+      "description": "在分页变化后触发数据刷新或埋点逻辑",
+      "code": "<script setup lang=\"ts\">\nimport { usePagination } from '@ksyun-internal/versatile';\n\nconst fetchList = () => console.log('reload');\nconst { page, limit, pageChange } = usePagination({\n  callback: () => fetchList(),\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "forget_limit_binding",
+      "description": "只绑定 page，没有同步维护 limit",
+      "wrongCode": "const { page } = usePagination();",
+      "correctCode": "const { page, limit } = usePagination();",
+      "explanation": "如果页面支持切换每页条数，应同时使用 hook 返回的 limit。"
+    }
+  ],
+  "searchKeywords": [
+    "usePagination",
+    "分页",
+    "page",
+    "limit",
+    "PaginationPlus",
+    "列表页"
+  ]
+}

package/hooks/usePersist.json

@@ -0,0 +1,61 @@
+{
+  "id": "usePersist",
+  "name": "usePersist",
+  "displayName": "本地持久化",
+  "category": "state",
+  "description": "将响应式数据持久化到 localStorage 或 sessionStorage，适合保存列表筛选、用户偏好和表格配置。",
+  "importStatement": "import { usePersist } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "key",
+      "type": "string",
+      "required": true,
+      "description": "存储键名"
+    },
+    {
+      "name": "defaultValue",
+      "type": "T",
+      "required": true,
+      "description": "初始化默认值"
+    },
+    {
+      "name": "options",
+      "type": "PersistOptions<T>",
+      "required": false,
+      "description": "持久化配置，可切换 storage、自定义序列化和 watch 行为"
+    }
+  ],
+  "returnType": "Ref<T>",
+  "examples": [
+    {
+      "id": "persist_table_fields",
+      "title": "持久化表格配置",
+      "description": "保存用户的列显隐或筛选配置",
+      "code": "<script setup lang=\"ts\">\nimport { usePersist } from '@ksyun-internal/versatile';\n\nconst tableFields = usePersist('table-fields', ['name', 'status']);\n</script>"
+    },
+    {
+      "id": "session_storage",
+      "title": "使用 sessionStorage",
+      "description": "仅在当前会话内保留搜索状态",
+      "code": "<script setup lang=\"ts\">\nimport { usePersist } from '@ksyun-internal/versatile';\n\nconst searchState = usePersist('instance-search', { key: 'name', value: '' }, {\n  storage: sessionStorage,\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "unstable_key",
+      "description": "使用会变化的 key，导致同一份状态被重复写入",
+      "wrongCode": "usePersist(`table-${Date.now()}`, []);",
+      "correctCode": "usePersist('instance-table-fields', []);",
+      "explanation": "key 应保持稳定，否则无法复用持久化结果。"
+    }
+  ],
+  "searchKeywords": [
+    "usePersist",
+    "localStorage",
+    "sessionStorage",
+    "持久化",
+    "列表偏好",
+    "缓存状态"
+  ]
+}

package/hooks/usePoll.json

@@ -0,0 +1,43 @@
+{
+  "id": "usePoll",
+  "name": "usePoll",
+  "displayName": "查询轮询",
+  "category": "data",
+  "description": "包装 Apollo 查询结果并启用轮询场景，适合在列表页、详情页中持续刷新接口数据。",
+  "importStatement": "import { usePoll } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "result",
+      "type": "UseQueryReturn<any, any>",
+      "required": true,
+      "description": "Apollo useQuery 返回的查询对象"
+    }
+  ],
+  "returnType": "UseQueryReturn<any, any>",
+  "examples": [
+    {
+      "id": "apollo_poll",
+      "title": "轮询查询结果",
+      "description": "对 useQuery 返回值启用轮询式刷新",
+      "code": "<script setup lang=\"ts\">\nimport { useQuery } from '@vue/apollo-composable';\nimport { usePoll } from '@ksyun-internal/versatile';\n\nconst queryResult = useQuery(GET_INSTANCE_LIST);\nconst pollResult = usePoll(queryResult);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "non_query_result",
+      "description": "传入普通 Promise 或自定义对象而不是 Apollo 查询返回值",
+      "wrongCode": "const result = usePoll(fetchList());",
+      "correctCode": "const result = usePoll(useQuery(GET_LIST));",
+      "explanation": "usePoll 依赖 Apollo 的 UseQueryReturn 结构。"
+    }
+  ],
+  "searchKeywords": [
+    "usePoll",
+    "轮询",
+    "apollo",
+    "useQuery",
+    "自动刷新",
+    "列表轮询"
+  ]
+}

package/hooks/useRoutePlus.json

@@ -0,0 +1,36 @@
+{
+  "id": "useRoutePlus",
+  "name": "useRoutePlus",
+  "displayName": "增强路由读取",
+  "category": "router",
+  "description": "对 vue-router 的 route 做包装，直接返回 params、query 及其 refs，便于在组合式函数中按字段响应式使用。",
+  "importStatement": "import { useRoutePlus } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ $route: RouteLocationNormalizedLoadedGeneric; params: Record<string, string>; paramRefs: ToRefs<Record<string, string>>; query: LocationQuery; queryRefs: ToRefs<LocationQuery>; }",
+  "examples": [
+    {
+      "id": "route_params",
+      "title": "读取详情页路由参数",
+      "description": "把详情页 id 和 query 参数拆成可直接使用的 refs",
+      "code": "<script setup lang=\"ts\">\nimport { useRoutePlus } from '@ksyun-internal/versatile';\n\nconst { params, paramRefs, queryRefs } = useRoutePlus();\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_writeback",
+      "description": "直接修改 paramRefs/queryRefs，期望同步改写路由地址",
+      "wrongCode": "paramRefs.id.value = '2';",
+      "correctCode": "如需跳转，请配合 useRouterPlus 或 router.push。",
+      "explanation": "这个 hook 主要用于读取路由状态，不负责写回 URL。"
+    }
+  ],
+  "searchKeywords": [
+    "useRoutePlus",
+    "route params",
+    "query refs",
+    "vue-router",
+    "详情页参数",
+    "路由读取"
+  ]
+}

package/hooks/useRouterPlus.json

@@ -0,0 +1,36 @@
+{
+  "id": "useRouterPlus",
+  "name": "useRouterPlus",
+  "displayName": "增强路由跳转",
+  "category": "router",
+  "description": "对 vue-router 的导航能力做统一封装，提供新开页签跳转和可回退的导航能力。",
+  "importStatement": "import { useRouterPlus } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ $router: Router; goNewPage: (to: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric, currentLocation?: RouteLocationNormalizedLoadedGeneric) => void; goBack: (back?: string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric) => void; }",
+  "examples": [
+    {
+      "id": "go_detail_page",
+      "title": "跳转详情页或新页签打开",
+      "description": "在列表页操作列中统一处理跳转行为",
+      "code": "<script setup lang=\"ts\">\nimport { useRouterPlus } from '@ksyun-internal/versatile';\n\nconst { goNewPage, goBack } = useRouterPlus();\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_back_fallback",
+      "description": "调用 goBack 但没有提供兜底地址，历史栈不足时体验不稳定",
+      "wrongCode": "goBack();",
+      "correctCode": "goBack({ name: 'instance-list' });",
+      "explanation": "在业务列表/详情页之间跳转时，建议提供明确回退目标。"
+    }
+  ],
+  "searchKeywords": [
+    "useRouterPlus",
+    "goNewPage",
+    "goBack",
+    "路由跳转",
+    "新开页签",
+    "vue-router"
+  ]
+}

package/hooks/useSearch.json

@@ -0,0 +1,56 @@
+{
+  "id": "useSearch",
+  "name": "useSearch",
+  "displayName": "搜索状态管理",
+  "category": "search",
+  "description": "管理 Search 和 SearchItems 常用的搜索状态，统一维护 searchKey、searchValue、searchItems 及其变更方法。配合列表页分页时可在筛选变化后重置页码。",
+  "importStatement": "import { useSearch } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ defaultSearchKey?: string; page?: Ref<number> }",
+      "required": false,
+      "description": "初始化配置，可指定默认搜索字段，并传入分页页码以便搜索变化时联动重置"
+    }
+  ],
+  "returnType": "{ searchKey: Ref<string>; searchKeyRela: Ref<string>; searchValue: Ref<string>; searchItems: Ref<T | undefined>; searchItemsRef: Ref<any>; handleChangeSearchValue: Function; handleChangeSingleValue: Function; handleChangeSearchSingleValue: Function; }",
+  "examples": [
+    {
+      "id": "list_search",
+      "title": "列表页搜索状态",
+      "description": "在列表页中统一维护搜索 key、搜索值和搜索项",
+      "code": "<script setup lang=\"ts\">\nimport { Search, SearchItems, usePagination, useSearch } from '@ksyun-internal/versatile';\n\nconst { page } = usePagination();\nconst { searchKey, searchValue, searchItems } = useSearch({\n  defaultSearchKey: 'name',\n  page,\n});\n</script>\n\n<template>\n  <Search v-model:search-key=\"searchKey\" v-model:search-value=\"searchValue\" :searches=\"[]\" />\n  <SearchItems v-model=\"searchItems\" />\n</template>"
+    },
+    {
+      "id": "search_callback",
+      "title": "手动处理搜索值变更",
+      "description": "通过返回的方法接管批量搜索或单值搜索的更新逻辑",
+      "code": "<script setup lang=\"ts\">\nimport { useSearch } from '@ksyun-internal/versatile';\n\nconst { handleChangeSearchValue } = useSearch();\n\nconst onSearch = (value?: string) => {\n  handleChangeSearchValue(value, value);\n};\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_page_link",
+      "description": "列表页搜索变化时没有传入 page，导致筛选后仍停留在旧页码",
+      "wrongCode": "const search = useSearch();",
+      "correctCode": "const search = useSearch({ page });",
+      "explanation": "在分页列表中建议把 page 传给 useSearch，让搜索条件变化时同步回到第一页。"
+    },
+    {
+      "id": "manual_duplicate_state",
+      "description": "重复自己维护 searchKey/searchValue，和 hook 返回值并存",
+      "wrongCode": "const searchKey = ref('name'); const searchValue = ref(''); const { searchItems } = useSearch();",
+      "correctCode": "const { searchKey, searchValue, searchItems } = useSearch({ defaultSearchKey: 'name' });",
+      "explanation": "优先使用 useSearch 返回的整套状态，避免来源分裂。"
+    }
+  ],
+  "searchKeywords": [
+    "useSearch",
+    "Search",
+    "SearchItems",
+    "列表筛选",
+    "搜索状态",
+    "检索条件"
+  ]
+}

package/hooks/useShell.json

@@ -0,0 +1,49 @@
+{
+  "id": "useShell",
+  "name": "useShell",
+  "displayName": "Shell 内容挂载",
+  "category": "dialog",
+  "description": "在弹窗显示时把 shell 或命令内容挂载到指定容器引用，适合命令预览、终端输出展示等场景。",
+  "importStatement": "import { useShell } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "content",
+      "type": "WatchSource<string | undefined | null>",
+      "required": true,
+      "description": "需要展示的 shell 内容"
+    },
+    {
+      "name": "isShowDialog",
+      "type": "Ref<boolean>",
+      "required": true,
+      "description": "弹窗显隐状态"
+    }
+  ],
+  "returnType": "{ shellRef: Ref<any> }",
+  "examples": [
+    {
+      "id": "shell_dialog",
+      "title": "命令预览弹窗",
+      "description": "在弹窗打开时渲染命令或脚本内容",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useShell } from '@ksyun-internal/versatile';\n\nconst content = ref('kubectl get pods');\nconst isShowDialog = ref(false);\nconst { shellRef } = useShell(content, isShowDialog);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "content_not_watch_source",
+      "description": "传入一次性字符串字面量，后续更新不会同步",
+      "wrongCode": "useShell('kubectl get pods', isShowDialog);",
+      "correctCode": "const content = ref('kubectl get pods'); useShell(content, isShowDialog);",
+      "explanation": "内容建议使用 Ref 或 getter，便于后续更新时同步渲染。"
+    }
+  ],
+  "searchKeywords": [
+    "useShell",
+    "shell",
+    "命令预览",
+    "dialog content",
+    "终端输出",
+    "shellRef"
+  ]
+}

package/hooks/useSkip.json

@@ -0,0 +1,43 @@
+{
+  "id": "useSkip",
+  "name": "useSkip",
+  "displayName": "头部返回跳转",
+  "category": "router",
+  "description": "从 Header 的 back 配置中提取统一跳转逻辑，适合详情页和购买链路页的返回按钮行为。",
+  "importStatement": "import { useSkip } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "back",
+      "type": "Ref<LayoutHeaderProps['back']>",
+      "required": true,
+      "description": "Header 的 back 配置项"
+    }
+  ],
+  "returnType": "{ goLink: () => any }",
+  "examples": [
+    {
+      "id": "header_back",
+      "title": "Header 返回按钮",
+      "description": "复用 Header back 配置实现统一返回跳转",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useSkip } from '@ksyun-internal/versatile';\n\nconst back = ref({ to: { name: 'instance-list' } });\nconst { goLink } = useSkip(back);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "plain_object_back",
+      "description": "直接传普通对象而不是 Ref，导致 back 配置变化无法联动",
+      "wrongCode": "useSkip({ to: { name: 'list' } });",
+      "correctCode": "const back = ref({ to: { name: 'list' } }); useSkip(back);",
+      "explanation": "hook 设计为消费 Header back 的响应式配置。"
+    }
+  ],
+  "searchKeywords": [
+    "useSkip",
+    "Header back",
+    "返回跳转",
+    "详情页返回",
+    "goLink",
+    "layout header"
+  ]
+}

package/hooks/useStorageIdEntity.json

@@ -0,0 +1,67 @@
+{
+  "id": "useStorageIdEntity",
+  "name": "useStorageIdEntity",
+  "displayName": "带存储的 ID 实体映射",
+  "category": "state",
+  "description": "在 useIdEntity 的基础上增加存储键能力，适合把当前选中的实体 ID 与本地缓存联动，支持刷新后恢复选择。",
+  "importStatement": "import { useStorageIdEntity } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "id",
+      "type": "Ref<string | number | undefined | null>",
+      "required": true,
+      "description": "当前选中的实体 ID"
+    },
+    {
+      "name": "list",
+      "type": "Ref<Entity[] | undefined | null>",
+      "required": true,
+      "description": "实体源列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof Entity",
+      "required": true,
+      "description": "实体主键字段"
+    },
+    {
+      "name": "storageName",
+      "type": "string",
+      "required": false,
+      "description": "本地存储使用的键名"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: Entity | undefined) => void",
+      "required": false,
+      "description": "实体变化时的回调"
+    }
+  ],
+  "returnType": "Ref<Entity | undefined>",
+  "examples": [
+    {
+      "id": "remember_selected_workspace",
+      "title": "记住上次选择的实体",
+      "description": "页面刷新后仍恢复用户上次选择的对象",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useStorageIdEntity } from '@ksyun-internal/versatile';\n\nconst selectedId = ref('ws-001');\nconst workspaceList = ref([{ WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' }]);\nconst currentWorkspace = useStorageIdEntity(selectedId, workspaceList, 'WorkspaceId', 'workspace-id');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "shared_storage_name",
+      "description": "多个页面复用同一个 storageName，导致选择串数据",
+      "wrongCode": "useStorageIdEntity(id, list, 'id', 'selected-id');",
+      "correctCode": "useStorageIdEntity(id, list, 'id', 'instance-workspace-id');",
+      "explanation": "storageName 建议按业务域区分，避免不同页面互相覆盖。"
+    }
+  ],
+  "searchKeywords": [
+    "useStorageIdEntity",
+    "本地记忆选择",
+    "storage",
+    "实体映射",
+    "刷新恢复",
+    "workspace"
+  ]
+}

package/hooks/useStore.json

@@ -0,0 +1,36 @@
+{
+  "id": "useStore",
+  "name": "useStore",
+  "displayName": "轻量全局状态",
+  "category": "state",
+  "description": "读取和写入 versatile 内部维护的轻量全局状态，当前暴露地域 key 和地域列表的读写能力。",
+  "importStatement": "import { useStore } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "{ setRegionKey: (regionKey: string) => void; setRegionList: (regionList: any[]) => void; regionKey: ComputedRef<string>; regionList: ComputedRef<any[]>; }",
+  "examples": [
+    {
+      "id": "shared_region_state",
+      "title": "共享地域状态",
+      "description": "在 Region、AZ 或购买页中共享当前地域选择",
+      "code": "<script setup lang=\"ts\">\nimport { useStore } from '@ksyun-internal/versatile';\n\nconst { regionKey, regionList, setRegionKey, setRegionList } = useStore();\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "mutate_computed_directly",
+      "description": "直接修改 regionList/regionKey，而不是走 setter",
+      "wrongCode": "regionKey.value = 'cn-beijing-6';",
+      "correctCode": "setRegionKey('cn-beijing-6');",
+      "explanation": "返回的状态是 computed，只读修改应通过 setter 完成。"
+    }
+  ],
+  "searchKeywords": [
+    "useStore",
+    "regionKey",
+    "regionList",
+    "全局状态",
+    "地域缓存",
+    "共享状态"
+  ]
+}

package/hooks/useTable.json

@@ -0,0 +1,49 @@
+{
+  "id": "useTable",
+  "name": "useTable",
+  "displayName": "表格状态管理",
+  "category": "table",
+  "description": "集中管理表格勾选、展开、列显隐和导出相关状态，适合原子 Table 和业务表格容器共享同一套表格控制逻辑。",
+  "importStatement": "import { useTable } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ rowKey?: string; notCheckTip?: string; tableFields?: TableFields }",
+      "required": false,
+      "description": "表格配置，可指定 rowKey、未勾选提示文案和列配置定义"
+    }
+  ],
+  "returnType": "{ checkedKeys: Ref<string[]>; expandedKeys: Ref<(string | number)[]>; isChecked: ComputedRef<number>; canCheck: ComputedRef<{ disabled: boolean; msg: string }>; tableRef: Ref<Table | undefined>; componentRef: Ref<any>; noCheckedColFields: Ref<string[]>; setRowKey: Function; exportTableData: Function; hideCol: Function; getTableColTitle: ((key: string) => string) | null; initTableColumnProps: Function; }",
+  "examples": [
+    {
+      "id": "table_selection",
+      "title": "管理表格勾选和列显隐",
+      "description": "在列表页中集中维护勾选状态和动态列配置",
+      "code": "<script setup lang=\"ts\">\nimport { useTable } from '@ksyun-internal/versatile';\n\nconst tableFields = [\n  { key: 'name', label: '实例名称', checked: true },\n  { key: 'status', label: '状态', checked: true },\n];\nconst { checkedKeys, tableRef, canCheck, initTableColumnProps } = useTable({\n  rowKey: 'id',\n  tableFields,\n});\n</script>"
+    },
+    {
+      "id": "table_export",
+      "title": "导出当前表格数据",
+      "description": "通过 hook 暴露的导出方法触发表格导出",
+      "code": "<script setup lang=\"ts\">\nimport { useTable } from '@ksyun-internal/versatile';\n\nconst { exportTableData } = useTable({ rowKey: 'id' });\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_row_key",
+      "description": "多选或导出场景没有稳定 rowKey，导致勾选数据不稳定",
+      "wrongCode": "const table = useTable();",
+      "correctCode": "const table = useTable({ rowKey: 'id' });",
+      "explanation": "在业务表格中建议显式指定 rowKey，避免勾选项和导出数据映射错乱。"
+    }
+  ],
+  "searchKeywords": [
+    "useTable",
+    "Table",
+    "勾选状态",
+    "列显隐",
+    "导出表格",
+    "rowKey"
+  ]
+}

package/hooks/useTableGroup.json

@@ -0,0 +1,43 @@
+{
+  "id": "useTableGroup",
+  "name": "useTableGroup",
+  "displayName": "表格分组筛选状态",
+  "category": "table",
+  "description": "管理 Table 或 ProTable 的 group 筛选状态，并可与 SearchItems 联动生成可展示的筛选项。",
+  "importStatement": "import { useTableGroup } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "options",
+      "type": "{ page?: Ref<number>; key?: string; defalutValue?: any; searchItemsRef?: Ref<any>; labelMaps?: Record<string, string> | Ref<Record<string, string>>; groupLabel?: string | Record<string, string | { label: string }>; isShowSearchItem?: boolean }",
+      "required": false,
+      "description": "分组筛选配置，可联动分页、SearchItems 和字段标签映射"
+    }
+  ],
+  "returnType": "{ status: ComputedRef<any>; group: Ref<Record<string, any>>; resetGroup: Function; changeGroup: Function; }",
+  "examples": [
+    {
+      "id": "protable_group",
+      "title": "配合 ProTable 的 group 筛选",
+      "description": "将 group 状态和 SearchItems 联动，统一驱动表格筛选",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { usePagination, useTableGroup } from '@ksyun-internal/versatile';\n\nconst { page } = usePagination();\nconst searchItemsRef = ref();\nconst { group, changeGroup, resetGroup } = useTableGroup({\n  page,\n  key: 'status',\n  searchItemsRef,\n  labelMaps: { using: '运行中', shutdown: '已关机' },\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_label_maps",
+      "description": "SearchItems 展示 group 条件时没有提供 labelMaps 或 groupLabel",
+      "wrongCode": "useTableGroup({ searchItemsRef });",
+      "correctCode": "useTableGroup({ searchItemsRef, labelMaps, groupLabel: '状态' });",
+      "explanation": "如果要把 group 同步到 SearchItems，建议补齐展示文案映射。"
+    }
+  ],
+  "searchKeywords": [
+    "useTableGroup",
+    "group",
+    "ProTable",
+    "表格筛选",
+    "SearchItems",
+    "状态分组"
+  ]
+}