king-design-analyzer 2.1.7 → 2.2.0

package/docs_for_llm/protable.doc.md

@@ -2,9 +2,9 @@
 
 集成了搜索、筛选、排序、分页、工具栏等功能的高级表格组件。
 
-**关键词**: table, search, filter, list, 表格, pro
+**关键词**: table, search, filter, list, 表格, pro, 高级表格, 资源列表
 
-**使用场景**: 资源列表页、复杂数据展示
+**使用场景**: 资源列表页、复杂数据展示、带搜索导出和列设置的高级列表、资源管理后台表格页
 
 ## 导入语句
 ```typescript
@@ -12,10 +12,46 @@ import { ProTable } from '@ksyun-internal/versatile';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| data | `Array` | `undefined` | 是 | 表格数据 | - |
-| loading | `boolean` | `undefined` | 否 | 加载状态 | - |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| data | `Array` | `undefined` | 是 | 表格数据 | - | - |
+| fixHeader | `boolean | number | string` | `false` | 否 | 表头固定，给定需要固定高度的具体数值，当超出该值时，展示滚动条 | `inherited:Table` | `<Table :data="data" :fixHeader="300"></Table>` |
+| stickHeader | `boolean | number | string` | `false` | 否 | 表头吸顶，给定需要吸顶的高度，当表头在页面滚动滚动时，距离视窗顶部的距离等于该高度时，将表头固定在此高度处 | `inherited:Table` | - |
+| stickScrollbar | `boolean | number | string` | `false` | 否 | 当出现横向滚动条时，设置是否当表格底部没有滚动到视窗中时，将横向滚动条固定在页面底部；取值为number类型时，用来指定距离视窗底部的距离 | `inherited:Table` | - |
+| checkType | `"checkbox" | "radio" | "none"` | `"checkbox"` | 否 | 当行可选择时，定义选择的类型: 单选 "radio" , 复选 "checkbox", 不可选 "none" | `inherited:Table` | - |
+| checkedKeys | `TableRowKey[]` | `[]` | 否 | 通过key数组来指定哪些行被选中，可用v-model:checkedKeys双向绑定 | `inherited:Table` | - |
+| rowKey | `(value: T, index: number) => TableRowKey` | `(value, index) => index` | 否 | 设置每行的key | `inherited:Table` | `<Table :data="tableData" :rowKey="(value, index) => index"></Table>` |
+| rowCheckable | `boolean` | `true` | 否 | 当行可选时，是否点击该行任意区域都可选中 | `inherited:Table` | - |
+| disableRow | `(value: T, index: number, key: TableRowKey) => boolean` | `undefined` | 否 | 定义行禁用可选的逻辑，返回true，则该行被禁用选择 | `inherited:Table` | - |
+| type | `"default" | "border" | "grid"` | `"default"` | 否 | 表格类型，默认左右无边框，"border"类型会添加边框, "grid"类型会展示栅格边框 | `inherited:Table` | - |
+| stripe | `boolean` | `false` | 否 | 相邻行是否展示不同的背景色 | `inherited:Table` | - |
+| rowClassName | `(value: T, index: number, key: TableRowKey) => string | undefined` | `undefined` | 否 | 通过一个函数定义行的className，该函数会传入该行数据，索引和key当做参数，返回的字符串将被设为该行的className | `inherited:Table` | - |
+| group | `TableGroupValue` | `undefined` | 否 | 分组配置 | `inherited:Table` | - |
+| sort | `TableSortValue` | `undefined` | 否 | 排序配置，可用v-model:sort双向绑定 | `inherited:Table` | - |
+| loading | `boolean` | `undefined` | 否 | 加载状态 | - | - |
+| merge | `TableMerge` | `undefined` | 否 | 指定表格单元格合并逻辑 | `inherited:Table` | - |
+| expandedKeys | `TableRowKey[]` | `undefined` | 否 | 通过key来指定哪些行展开，可用v-model:expandedKeys绑定 | `inherited:Table` | - |
+| rowExpandable | `boolean` | `true` | 否 | 是否点击该行任意区域即展开 | `inherited:Table` | - |
+| selectedKeys | `TableRowKey[]` | `undefined` | 否 | 当rowSelectable取值为非false时，指定哪些行高亮 | `inherited:Table` | - |
+| rowSelectable | `boolean | "single" | "multiple"` | `false` | 否 | 是否点击行时高亮该行，取值为multiple时，可以同时高亮多行 | `inherited:Table` | - |
+| childrenKey | `string` | `"children"` | 否 | 树形表格指定子元素键名 | `inherited:Table` | - |
+| indent | `number` | `32` | 否 | 树形表格指定子元素缩进宽度 | `inherited:Table` | - |
+| spreadKeys | `TableRowKey[]` | `undefined` | 否 | 树形表格指定展开的行，可用v-model:spreadKeys绑定 | `inherited:Table` | - |
+| tooltipPosition | `"left" | "bottom" | "right" | "top" | Position` | `"top"` | 否 | 行提示的位置 | `inherited:Table` | - |
+| tooltipContainer | `Container` | `undefined` | 否 | 指定行提示弹层追加的位置，支持函数或 CSS 选择器 | `inherited:Table` | - |
+| keepStatus | `boolean` | `false` | 否 | 是否在行销毁的时候，保持该行在checkedKeys | selectedKeys | spreadKeys | expandedKeys中的key值 | `inherited:Table` | - |
+| showIndeterminate | `boolean` | `true` | 否 | 表头的Checkbox是否支持展示半选中状态 | `inherited:Table` | - |
+| resizable | `boolean` | `false` | 否 | 是否可以表头拖动调整列宽 | `inherited:Table` | - |
+| minColWidth | `number` | `40` | 否 | 指定所有列拖动时的最小宽度 | `inherited:Table` | - |
+| widthStoreKey | `string` | `undefined` | 否 | 如果要保存表格拖动后的列宽信息，可以通过该属性设置保存到localStorage中的key | `inherited:Table` | - |
+| draggable | `boolean` | `false` | 否 | 表格行是否可拖动排序 | `inherited:Table` | - |
+| animation | `boolean | [boolean, boolean]` | `true` | 否 | 是否开启动效，可以通过数组单独设置行和列的动效 | `inherited:Table` | - |
+| hideHeader | `boolean` | `false` | 否 | 是否隐藏表头 | `inherited:Table` | - |
+| pagination | `boolean | PaginationProps` | `false` | 否 | 是否支持分页，可传入对象配置分页参数 | `inherited:Table` | - |
+| fixFooter | `boolean` | `false` | 否 | table给定需要固定高度时，自定义footer固定 | `inherited:Table` | - |
+| load | `(node: any) => Promise<any[]> | void` | `undefined` | 否 | 指定异步加载节点数据的函数，该函数通过Promise返回数组来添加子节点数据 | `inherited:Table` | - |
+| spreadArrowIndex | `number` | `0` | 否 | 指定树形表格展开Icon的所在列，默认在第一列 | `inherited:Table` | - |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟滚动，适用于大数据量场景 | `inherited:Table` | - |
 | tableHeaderProps | `TableHeaderProps` | `{ show: true }` | 否 | 头部工具栏配置对象。包含以下子属性：
 - show: Boolean (默认 true) - 是否显示
 - toolbar: TableToolbar - 表格功能区配置
@@ -29,7 +65,7 @@ import { ProTable } from '@ksyun-internal/versatile';
   - searches: string (默认 '') - 继承 Search 组件的 searches 属性
   - searchGroups: TableFilter - 继承 Search 组件的 searchGroups 属性
 - filter: TableFilter - 表格检索区配置
-  - show: Boolean (默认 true) - 是否显示 | `:tableHeaderProps="{
+  - show: Boolean (默认 true) - 是否显示 | - | `:tableHeaderProps="{
   show: true,
   toolbar: {
     show: true,
@@ -44,19 +80,54 @@ import { ProTable } from '@ksyun-internal/versatile';
   },
   filter: { show: true }
 }"` |
-| searchKey | `string` | `undefined` | 否 | 搜索关键词绑定 | `v-model:searchKey="key"` |
-| searchValue | `string` | `undefined` | 否 | 搜索值绑定 | `v-model:searchValue="val"` |
-| searchItems | `object` | `{}` | 否 | 同 SearchItems 组件的 modelValue，可用 v-model 双向绑定 | `v-model:searchItems="searchParams"` |
+| searchKey | `string` | `undefined` | 否 | 搜索关键词绑定 | - | `v-model:searchKey="key"` |
+| searchValue | `string` | `undefined` | 否 | 搜索值绑定 | - | `v-model:searchValue="val"` |
+| searchItems | `object` | `{}` | 否 | 同 SearchItems 组件的 modelValue，可用 v-model 双向绑定 | - | `v-model:searchItems="searchParams"` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | refresh | `@refresh` | 点击刷新按钮时触发 | `-` | `<ProTable @refresh="loadData" />` |
-| change:searchValue | `@change:searchValue` | 搜索框内容变更时触发 | `-` | - |
-| change:searchKey | `@change:searchKey` | 搜索 Key 变更时触发 | `-` | - |
-| change:columns | `@change:columns` | 列设置变更时触发 | `-` | - |
-| change:filters | `@change:filters` | 筛选条件变更时触发 | `-` | - |
-| change:export | `@change:export` | 导出配置变更时触发，payload 包含 selectedKeys 和 exportRange | `-` | - |
+| change:searchValue | `@change:searchValue` | 搜索框内容变更时触发 | `value: string, label?: string, current?: SearchType, obj?: Record<string, any> | null` | - |
+| change:searchKey | `@change:searchKey` | 搜索 Key 变更时触发 | `value: string, current?: SearchType` | - |
+| change:columns | `@change:columns` | 列设置变更时触发 | `data: string[]` | - |
+| change:filters | `@change:filters` | 筛选条件变更时触发 | `data: TableGroupValue` | - |
+| change:export | `@change:export` | 导出配置变更时触发，payload 包含 selectedKeys 和 exportRange | `data: ExportConfig` | - |
+
+### 事件参数说明
+**change:searchValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前搜索框中的检索值。 |
+| label | `string` | 否 | - | 当前搜索值对应的展示文案，选择型搜索时可直接用于回显。 |
+| current | `SearchType` | 否 | - | 当前正在使用的搜索项配置。 |
+| obj | `Record<string, any> | null` | 否 | - | 选择型搜索命中的原始选项对象；纯输入搜索通常为 `null`。 |
+
+**change:searchKey**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前选中的搜索字段 key。 |
+| current | `SearchType` | 否 | - | 当前激活的搜索项配置对象。 |
+
+**change:columns**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| data | `string[]` | 是 | - | 当前保留展示的列 key 列表，可直接用于持久化用户列设置。 |
+
+**change:filters**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| data | `TableGroupValue` | 是 | - | 当前表格分组或筛选条件对象，通常用于组装请求参数。 |
+
+**change:export**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| data | `ExportConfig` | 是 | - | 当前导出配置，包含待导出列 key 和导出范围标识。 |
 
 ## 插槽 (Slots)
 | 插槽名 | 说明 | 模板写法 | 示例 |
@@ -64,3 +135,6 @@ import { ProTable } from '@ksyun-internal/versatile';
 | actions | 表格的左上角操作区 | `<template #actions>...</template>` | `<ProTable><template #actions><Button type="primary">新建</Button></template></ProTable>` |
 | toolbar | 表格的右上角功能区 | `<template #toolbar>...</template>` | `<ProTable><template #toolbar><Button>自定义操作</Button></template></ProTable>` |
 
+## 相关组件
+Table, Search, SearchItems, PaginationPlus
+

package/docs_for_llm/queuevisualrange.doc.md

@@ -0,0 +1,78 @@
+# 队列可见范围 (QueueVisualRange)
+
+用于配置队列、任务或资源可见范围的业务组件，适合在私有、项目共享、全员可见等可见性策略之间切换。
+
+**关键词**: queue visual range, visibility scope, 队列可见范围, 可见性, 共享范围
+
+**使用场景**: 队列权限范围配置、资源共享范围设置、共享范围说明和切换
+
+## 导入语句
+```typescript
+import { QueueVisualRange } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `string` | `""` | 否 | 当前可见范围值 | - | - |
+| tip | `string` | `undefined` | 否 | 说明提示文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 可见范围变化时触发，可据此同步权限或共享策略配置。 | `value?: string` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 当前选中的可见范围标识。 |
+
+## 使用示例
+### 设置队列可见范围
+**场景**: 在任务或资源配置页选择共享和可见性范围。
+
+在新建队列时选择私有或共享范围。
+
+**使用的 API**: 属性: modelValue, tip | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { QueueVisualRange } from '@ksyun-internal/versatile';
+
+const visualRange = ref('project');
+</script>
+
+<template>
+  <QueueVisualRange v-model="visualRange" tip="共享范围越大，越需要关注访问控制" />
+</template>
+```
+
+### 共享范围选择联动说明
+**场景**: 在队列和任务创建时明确不同共享范围的含义。
+
+在切换可见范围时同步展示额外说明文案。
+
+**使用的 API**: 属性: modelValue, tip | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { QueueVisualRange } from '@ksyun-internal/versatile';
+
+const visualRange = ref('private');
+</script>
+
+<template>
+  <QueueVisualRange
+    v-model="visualRange"
+    tip="选择项目共享后，同项目成员均可查看该队列"
+  />
+</template>
+```
+
+## 相关组件
+Visibility
+

package/docs_for_llm/radio.doc.md

@@ -12,21 +12,33 @@ import { Radio } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `any` | `false` | 否 | 单选框取值，用于 v-model 进行双向绑定 | `<Radio v-model="selected" trueValue="a">选项 A</Radio>` |
-| trueValue | `any` | `true` | 否 | 单选框选中后的值，用于区分不同选项 | `<Radio v-model="selected" trueValue="apple">苹果</Radio>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 | `<Radio disabled>禁用选项</Radio>` |
-| name | `string` | `undefined` | 否 | 单选框的名称。指定相同的 name 可以使多个单选框组成一个单选框组，行为与浏览器原生单选框一致。 | `<Radio name="gender" trueValue="male">男</Radio>
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `any` | `false` | 否 | 单选框取值，用于 v-model 进行双向绑定 | - | `<Radio v-model="selected" trueValue="a">选项 A</Radio>` |
+| trueValue | `any` | `true` | 否 | 单选框选中后的值，用于区分不同选项 | - | `<Radio v-model="selected" trueValue="apple">苹果</Radio>` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | - | `<Radio disabled>禁用选项</Radio>` |
+| name | `string` | `undefined` | 否 | 单选框的名称。指定相同的 name 可以使多个单选框组成一个单选框组，行为与浏览器原生单选框一致。 | `native` | `<Radio name="gender" trueValue="male">男</Radio>
 <Radio name="gender" trueValue="female">女</Radio>` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定浏览器自动补全行为 | `native` | `<Radio autocomplete="off">选项</Radio>` |
+| autofocus | `boolean` | `undefined` | 否 | 原生 autofocus 属性，页面加载后自动聚焦单选框 | `native` | `<Radio autofocus trueValue="a">选项 A</Radio>` |
+| form | `string` | `undefined` | 否 | 原生 form 属性，指定单选框关联的表单 id | `native` | `<Radio form="myForm" trueValue="a">选项 A</Radio>` |
+| maxlength | `number | string` | `undefined` | 否 | 原生 maxlength 属性，组件透传到内部 input 元素 | `native` | `<Radio :maxlength="1" trueValue="a">选项 A</Radio>` |
+| required | `boolean` | `undefined` | 否 | 原生 required 属性，标记为必选输入项 | `native` | `<Radio required trueValue="a">选项 A</Radio>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | change | `@change` | 当点击组件导致值变化时触发 | `value: any, e: MouseEvent` | `<Radio @change="handleChange" trueValue="a">选项</Radio>` |
 
-### 事件处理函数示例
-**change**:
+### 事件参数说明
+**change**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `any` | 是 | - | 当前选中的值 |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件对象 |
+
+事件处理示例:
 ```typescript
 const handleChange = (value: any, e: MouseEvent) => {
   console.log('选中值:', value);
@@ -34,18 +46,21 @@ const handleChange = (value: any, e: MouseEvent) => {
 ```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 多个 Radio 未设置 trueValue
 > **错误用法**: `<Radio v-model="selected">选项 A</Radio>
 <Radio v-model="selected">选项 B</Radio>`
 > **正确写法**: `<Radio v-model="selected" trueValue="a">选项 A</Radio>
 <Radio v-model="selected" trueValue="b">选项 B</Radio>`
 > **说明**: 多个 Radio 组成单选组时，必须为每个 Radio 设置不同的 trueValue 来区分选项
 
+### 未设置 name 且同组 Radio 绑定了不同的 v-model
 > **错误用法**: `<Radio v-model="value1" trueValue="a">A</Radio>
 <Radio v-model="value2" trueValue="b">B</Radio>`
 > **正确写法**: `<Radio v-model="selected" trueValue="a">A</Radio>
 <Radio v-model="selected" trueValue="b">B</Radio>`
 > **说明**: 如果不使用 name 属性进行原生分组，同一组单选框必须绑定同一个 v-model 变量，否则无法实现互斥选择
 
+### 多个 Radio 设置了相同的 trueValue
 > **错误用法**: `<Radio v-model="selected" trueValue="a">A</Radio>
 <Radio v-model="selected" trueValue="a">B</Radio>`
 > **正确写法**: `<Radio v-model="selected" trueValue="a">A</Radio>

package/docs_for_llm/rate.doc.md

@@ -0,0 +1,122 @@
+# 评分 (Rate)
+
+评分组件，用于展示和选择星级评分。支持半星、禁用态、自定义总数以及再次点击清空评分。
+
+**关键词**: rate, 评分, 星级, 打分, 半星, clearable
+
+**使用场景**: 商品评价、服务满意度评分、内容点赞等级、后台数据展示只读评分
+
+## 导入语句
+```typescript
+import { Rate } from '@king-design/vue';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `number` | `0` | 否 | 当前评分值，可用 v-model 双向绑定。 | - | `<Rate v-model="score" />` |
+| count | `number` | `5` | 否 | 总星数。 | - | `<Rate v-model="score" :count="10" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用。禁用后只展示当前值，不响应 hover 和点击。 | - | `<Rate :value="4" disabled />` |
+| half | `boolean` | `false` | 否 | 是否允许半星评分。 | - | `<Rate v-model="score" half />` |
+| clearable | `boolean` | `false` | 否 | 是否允许点击当前值后清空评分。 | - | `<Rate v-model="score" clearable />` |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| mouseleave | `@mouseleave` | 鼠标离开评分区域时触发，通常用于结束悬停预览。 | `e: MouseEvent` | `<Rate @mouseleave="handleMouseLeave" />` |
+
+### 事件参数说明
+**mouseleave**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件 |
+
+事件处理示例:
+```typescript
+const handleMouseLeave = (e: MouseEvent) => {
+  console.log('离开评分区域');
+};
+```
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| icon | 自定义每一项评分图标，默认使用星形图标。 | `<template #icon>...</template>` | `<Rate v-model="score"><template #icon><Icon class="k-icon-favorite" /></template></Rate>` |
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 传入小数评分但未开启 half
+> **错误用法**: `<Rate :value="3.5" />`
+> **正确写法**: `<Rate :value="3.5" half />`
+> **说明**: 如果需要展示或选择半星评分，应显式开启 half，否则组件按整星交互处理。
+
+### 期望再次点击清空评分但未开启 clearable
+> **错误用法**: `<Rate v-model="score" />`
+> **正确写法**: `<Rate v-model="score" clearable />`
+> **说明**: 默认再次点击当前星级不会清空值，如需允许取消评分，应开启 clearable。
+
+## 使用示例
+### 基础用法
+**场景**: 收集用户星级评分
+
+用户评分输入。
+
+**使用的 API**: 属性: value
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Rate } from '@king-design/vue';
+
+const score = ref(3);
+</script>
+<template>
+  <Rate v-model="score" />
+</template>
+```
+
+### 半星和可清空
+**场景**: 允许半星和取消评分
+
+适合更细粒度的打分场景。
+
+**使用的 API**: 属性: value, half, clearable
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Rate } from '@king-design/vue';
+
+const score = ref(3.5);
+</script>
+<template>
+  <Rate v-model="score" half clearable />
+</template>
+```
+
+### 自定义图标
+**场景**: 在点赞或喜爱度场景中使用心形评分
+
+使用心形图标替代默认星形。
+
+**使用的 API**: 属性: value | 插槽: icon
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Icon, Rate } from '@king-design/vue';
+
+const score = ref(4);
+</script>
+<template>
+  <Rate v-model="score">
+    <template #icon>
+      <Icon class="k-icon-heart" />
+    </template>
+  </Rate>
+</template>
+```
+
+## 相关组件
+Icon, Tag, Tooltip
+

package/docs_for_llm/region.doc.md

@@ -2,9 +2,9 @@
 
 地域（Region）选择组件，支持多区域和多地域的展示与切换。
 
-**关键词**: region, area, location, 地域, 区域
+**关键词**: region, area, location, 地域, 区域, 大区, region select, 地域选择
 
-**使用场景**: 购买页选择地域、列表页筛选地域
+**使用场景**: 购买页选择地域、列表页筛选地域、资源创建时切换可售卖地域、和 AZ 联动选择地域与可用区
 
 ## 导入语句
 ```typescript
@@ -12,14 +12,14 @@ import { Region } from '@ksyun-internal/versatile';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| modelValue | `string` | `undefined` | 否 | 选中的地域编码（RegionCode） | `<Region v-model="regionCode" />` |
-| areaCode | `string` | `undefined` | 否 | 当前选中的大区编码 | `<Region v-model:areaCode="areaCode" />` |
-| packages | `Region[]` | `undefined` | 否 | 地域配置列表 | `<Region :packages="packages" />` |
-| supportEmptyAz | `boolean` | `false` | 否 | 是否支持空可用区 | `<Region supportEmptyAz />` |
-| showLearnMore | `boolean` | `true` | 否 | 是否显示了解更多 | `<Region showLearnMore />` |
-| learnMoreUrl | `number` | `undefined` | 否 | 了解更多链接ID | `<Region :learnMoreUrl="123" />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `string` | `undefined` | 否 | 选中的地域编码（RegionCode） | - | `<Region v-model="regionCode" />` |
+| areaCode | `string` | `undefined` | 否 | 当前选中的大区编码 | - | `<Region v-model:areaCode="areaCode" />` |
+| packages | `Region[]` | `undefined` | 否 | 地域配置列表 | - | `<Region :packages="packages" />` |
+| supportEmptyAz | `boolean` | `false` | 否 | 是否支持空可用区 | - | `<Region supportEmptyAz />` |
+| showLearnMore | `boolean` | `true` | 否 | 是否显示了解更多 | - | `<Region showLearnMore />` |
+| learnMoreUrl | `number` | `undefined` | 否 | 了解更多链接ID | - | `<Region :learnMoreUrl="123" />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
@@ -27,13 +27,25 @@ import { Region } from '@ksyun-internal/versatile';
 | change | `update:modelValue` | 地域改变时触发 | `value: string` | `<Region @update:modelValue="v => console.log(v)" /></Region>` |
 | areaChange | `update:areaCode` | 大区改变时触发 | `value: string` | `<Region @update:areaCode="v => console.log(v)" /></Region>` |
 
-### 事件处理函数示例
-**change**:
+### 事件参数说明
+**change**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 新的RegionCode |
+
+事件处理示例:
 ```typescript
 (val) => { console.log(val); }
 ```
 
-**areaChange**:
+**areaChange**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 新的AreaCode |
+
+事件处理示例:
 ```typescript
 (val) => { console.log(val); }
 ```

package/docs_for_llm/search.doc.md

@@ -0,0 +1,120 @@
+# 组合搜索框 (Search)
+
+由搜索类型选择器和输入区域组合而成的业务搜索组件，适合列表页按名称、ID、状态等不同维度快速检索。
+
+**关键词**: search, filter, search bar, search by field, 组合搜索, 搜索框, 多条件搜索, 字段筛选
+
+**使用场景**: 列表页关键字搜索、按类型切换搜索条件、和 SearchItems 联动的高级检索、控制台资源列表顶部搜索区
+
+## 导入语句
+```typescript
+import { Search } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| searchKey | `string` | `""` | 否 | 当前选中的搜索类型 key | - | - |
+| searchValue | `string` | `""` | 否 | 当前输入或选择的搜索值 | - | - |
+| searches | `SearchType[] | Record<string, SearchType>` | `undefined` | 是 | 搜索配置集合，支持数组或 key-value 对象 | - | - |
+| searchGroups | `SearchGroupItem[]` | `undefined` | 否 | 搜索类型分组配置 | - | - |
+| clearable | `boolean` | `false` | 否 | 是否允许清空搜索值 | - | - |
+| leftWidth | `string | number` | `120` | 否 | 左侧搜索类型选择区域宽度 | - | - |
+| rightWidth | `string | number` | `240` | 否 | 右侧搜索输入区域宽度 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| clear | `@clear` | 用户点击清空按钮后触发，通常用于重置搜索值并刷新列表。 | `-` | - |
+| change:searchKey | `@change:searchKey` | 搜索维度切换时触发，可据此切换占位提示或请求参数。 | `value: string, current?: SearchType` | - |
+| change:searchValue | `@change:searchValue` | 搜索值变化时触发，适合实时记录当前检索条件。 | `value: string, label?: string, current?: SearchType, obj?: Record<string, any> | null` | - |
+
+### 事件参数说明
+**change:searchKey**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前选中的搜索字段 key，例如 `name`、`project`、`privateIp`。 |
+| current | `SearchType` | 否 | - | 当前激活的搜索项配置对象，包含 label、type、placeholder 等信息。 |
+
+**change:searchValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前输入框或选择器中的搜索值。 |
+| label | `string` | 否 | - | 当前搜索值对应的展示文案，选择型搜索时常用于回显标签。 |
+| current | `SearchType` | 否 | - | 当前正在使用的搜索项配置对象。 |
+| obj | `Record<string, any> | null` | 否 | - | 选择型搜索命中的原始选项对象；输入型搜索通常为 `null`。 |
+
+## 使用示例
+### 实例列表组合搜索
+**场景**: 在列表页顶部提供按不同字段切换的统一搜索入口。
+
+在一个搜索框内切换按名称、实例 ID 或 IP 搜索。
+
+**使用的 API**: 属性: searchKey, searchValue, searches, clearable | 事件: change:searchKey, change:searchValue, clear
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Search } from '@ksyun-internal/versatile';
+
+const searchKey = ref('name');
+const searchValue = ref('web-prod');
+const searches = [
+  { key: 'name', label: '实例名称', type: 'input', placeholder: '请输入实例名称' },
+  { key: 'id', label: '实例 ID', type: 'input', placeholder: '请输入实例 ID' },
+  { key: 'ip', label: '内网 IP', type: 'input', placeholder: '请输入内网 IP' },
+];
+</script>
+
+<template>
+  <Search
+    v-model:search-key="searchKey"
+    v-model:search-value="searchValue"
+    :searches="searches"
+    :clearable="true"
+  />
+</template>
+```
+
+### 按分组组织搜索条件
+**场景**: 在复杂列表页中把搜索条件按业务域分组，降低用户选择成本。
+
+通过 searchGroups 将资源类和网络类搜索条件分组展示。
+
+**使用的 API**: 属性: searchKey, searchValue, searches, searchGroups, leftWidth, rightWidth | 事件: change:searchKey, change:searchValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Search } from '@ksyun-internal/versatile';
+
+const searchKey = ref('project');
+const searchValue = ref('core');
+const searches = {
+  name: { key: 'name', label: '实例名称', type: 'input', placeholder: '请输入实例名称' },
+  project: { key: 'project', label: '项目名称', type: 'input', placeholder: '请输入项目名称' },
+  privateIp: { key: 'privateIp', label: '内网 IP', type: 'input', placeholder: '请输入内网 IP' },
+};
+const searchGroups = [
+  { label: '资源信息', keys: ['name', 'project'] },
+  { label: '网络信息', keys: ['privateIp'] },
+];
+</script>
+
+<template>
+  <Search
+    v-model:search-key="searchKey"
+    v-model:search-value="searchValue"
+    :searches="searches"
+    :search-groups="searchGroups"
+    :left-width="140"
+    :right-width="280"
+  />
+</template>
+```
+
+## 相关组件
+SearchInput, SearchSelect, SearchItems, ProTable
+