king-design-analyzer 2.1.9 → 2.2.1

package/docs_for_llm/rate.doc.md

@@ -0,0 +1,127 @@
+# 评分 (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>` |
+
+### 插槽参数说明
+**icon**
+
+- 参数结构: 无参数
+
+## 常见错误与正确用法 (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/scrollselect.doc.md

@@ -0,0 +1,90 @@
+# 滚动选择器 (ScrollSelect)
+
+滚动选择器组件，通过滚轮、拖拽或点击来选择值。适合时间、年份、数值区间等连续选项场景，也可以通过函数动态生成可选数据。
+
+**关键词**: scrollselect, 滚动选择器, 时间滚轮, year picker
+
+**使用场景**: 年份或月份选择、时间滚轮、连续数值选择
+
+## 导入语句
+```typescript
+import { ScrollSelect } from '@king-design/vue';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `T` | `undefined` | 否 | 当前选中值，可用 v-model 双向绑定 | - | `<ScrollSelect v-model="year" :data="years" />` |
+| count | `number` | `5` | 否 | 可视区域中渲染的数据个数 | - | `<ScrollSelect :count="10" />` |
+| data | `Data<T> = DataItem<T>[] | ((v: T) => DataItem<T>[])` | `[]` | 否 | 可选数据列表，或根据当前值动态生成数据的方法 | - | `<ScrollSelect :data="[{ value: 1, label: '一月' }]" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用整个选择器 | - | `<ScrollSelect disabled :data="years" />` |
+| disable | `(v: T) => boolean` | `undefined` | 否 | 按值控制单项是否禁用 | - | `<ScrollSelect :disable="(v) => v < 2020" />` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| append | 在滚动选择器后追加额外内容，例如单位说明 | `#append` | `<ScrollSelect v-model="hour" :data="hours"><template #append>时</template></ScrollSelect>` |
+
+### 插槽参数说明
+**append**
+
+- 参数结构: 无参数
+
+## 使用示例
+### 基础用法
+**场景**: 在时间和数值选择场景中提供滚动选择交互。
+
+使用静态数据创建一个年份选择器。
+
+**使用的 API**: 属性: value, data
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ScrollSelect } from '@king-design/vue';
+
+const year = ref(2024);
+const years = Array.from({ length: 7 }, (_, index) => ({
+  value: 2021 + index,
+  label: `${2021 + index} 年`,
+}));
+</script>
+<template>
+  <ScrollSelect v-model="year" :data="years" />
+</template>
+```
+
+### 动态生成数据
+**场景**: 在时间滚轮或区间选择中按需生成可见窗口数据。
+
+根据当前选中值动态生成附近的年份选项。
+
+**使用的 API**: 属性: value, count, data | 插槽: append
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ScrollSelect } from '@king-design/vue';
+
+const currentYear = ref(2025);
+const generateYears = (value: number) => {
+  const start = value - 3;
+  return Array.from({ length: 7 }, (_, index) => {
+    const year = start + index;
+    return {
+      value: year,
+      label: `${year} 年`,
+    };
+  });
+};
+</script>
+<template>
+  <ScrollSelect v-model="currentYear" :count="7" :data="generateYears">
+    <template #append>年份</template>
+  </ScrollSelect>
+</template>
+```
+
+## 相关组件
+Datepicker, Timepicker
+

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
+

package/docs_for_llm/searchinput.doc.md

@@ -0,0 +1,111 @@
+# 搜索输入框 (SearchInput)
+
+轻量搜索输入框组件，适合工具栏关键词过滤、输入即搜或与列表查询按钮配套使用。
+
+**关键词**: search input, keyword search, 输入搜索, 搜索输入框, 关键字过滤, 单字段搜索
+
+**使用场景**: 列表页关键字输入、工具栏快捷搜索、确认输入后发起查询
+
+## 导入语句
+```typescript
+import { SearchInput } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `string` | `"text"` | 否 | 在原生 input 标签的 type 取值的基础上扩展了 textarea 值，当取该值时渲染成 <textarea> | `inherited:Input` | `<Input type="textarea" :rows="4" placeholder="请输入内容" />` |
+| name | `string` | `undefined` | 否 | 原生 input 标签的 name 属性 | `native`, `inherited:Input` | `<Input name="username" />` |
+| placeholder | `string` | `undefined` | 否 | 占位文案 | `native`, `inherited:Input` | `<Input placeholder="请输入内容" />` |
+| readonly | `boolean` | `false` | 否 | 是否只读 | `native`, `inherited:Input` | `<Input v-model="value" readonly />` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定浏览器自动补全行为 | `native`, `inherited:Input` | `<Input autocomplete="username" />` |
+| autofocus | `boolean` | `undefined` | 否 | 原生 autofocus 属性，页面加载后自动聚焦输入框 | `native`, `inherited:Input` | `<Input autofocus />` |
+| form | `string` | `undefined` | 否 | 原生 form 属性，指定输入框关联的表单 id | `native`, `inherited:Input` | `<Input form="searchForm" />` |
+| maxlength | `number | string` | `undefined` | 否 | 原生 maxlength 属性，限制最大输入长度 | `native`, `inherited:Input` | `<Input :maxlength="50" showCount />` |
+| pattern | `string` | `undefined` | 否 | 原生 pattern 属性，指定输入值需要匹配的正则模式 | `native`, `inherited:Input` | `<Input pattern="[0-9]{6}" placeholder="请输入6位数字" />` |
+| required | `boolean` | `undefined` | 否 | 原生 required 属性，标记为必填输入项 | `native`, `inherited:Input` | `<Input required placeholder="必填项" />` |
+| clearable | `boolean` | `false` | 否 | 是否显示清空按钮 | - | - |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Input` | `<Input disabled placeholder="禁用状态" />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `inherited:Input` | `<Input size="large" placeholder="大尺寸输入框" />` |
+| rows | `number | string` | `2` | 否 | 当 type="textarea" 时，默认展示文本行数 | `native`, `inherited:Input` | `<Input type="textarea" :rows="6" />` |
+| cols | `number` | `undefined` | 否 | 原生 cols 属性，当 type="textarea" 时指定可见宽度 | `native`, `inherited:Input` | `<Input type="textarea" :cols="40" />` |
+| datalist | `string` | `undefined` | 否 | 原生 datalist 属性，关联 datalist 元素 id | `native`, `inherited:Input` | `<Input datalist="city-list" />` |
+| dirname | `string` | `undefined` | 否 | 原生 dirname 属性，提交时附带输入方向信息 | `native`, `inherited:Input` | `<Input dirname="comment.dir" />` |
+| wrap | `"hard" | "soft"` | `undefined` | 否 | 原生 wrap 属性，当 type="textarea" 时指定换行提交方式 | `native`, `inherited:Input` | `<Input type="textarea" wrap="hard" />` |
+| autoWidth | `boolean` | `false` | 否 | 是否宽度随输入的文本的长度变化而变化 | `inherited:Input` | `<Input autoWidth placeholder="宽度自适应" />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Input` | `<Input fluid placeholder="宽度100%" />` |
+| width | `string | number` | `undefined` | 否 | 指定宽度，组件会加上单位 px | `inherited:Input` | `<Input :width="300" placeholder="宽度300px" />` |
+| stackClearIcon | `boolean` | `false` | 否 | 是否将清空按钮覆盖在 suffix 按钮上展示来节省空间 | `inherited:Input` | `<Input clearable stackClearIcon />` |
+| frozenOnInput | `boolean` | `false` | 否 | 是否在输入的过程中冻结 value 更新到视图 | `inherited:Input` | `<Input frozenOnInput />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `inherited:Input` | `<Input inline />` |
+| waveDisabled | `boolean` | `false` | 否 | 是否禁用点击波纹效果 | `inherited:Input` | `<Input waveDisabled />` |
+| resize | `"none" | "vertical" | "horizontal" | "both"` | `"vertical"` | 否 | 指定 textarea 输入框拖动调整大小的方向，默认只能垂直方向调整 | `inherited:Input` | `<Input type="textarea" resize="both" />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Input` | `<Input flat placeholder="扁平样式" />` |
+| showCount | `boolean` | `false` | 否 | 是否展示字符长度提示数字 | `inherited:Input` | `<Input showCount maxlength="50" />` |
+| showPassword | `boolean` | `false` | 否 | 当 type="password" 时，是否展示显隐密码按钮 | `inherited:Input` | `<Input type="password" showPassword />` |
+| modelValue | `string` | `""` | 否 | 输入框当前值 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| clear | `@clear` | 用户清空关键词时触发，通常用于恢复默认列表数据。 | `-` | - |
+| change:value | `@change:value` | 搜索关键词完成一次确认输入时触发，适合发起查询请求。 | `value?: string` | - |
+
+### 事件参数说明
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 本次确认提交的关键词。 |
+
+## 使用示例
+### 工具栏关键字过滤
+**场景**: 在工具栏中提供单关键字快速搜索。
+
+在列表工具栏放置一个轻量搜索框，按名称快速过滤资源。
+
+**使用的 API**: 属性: modelValue, clearable, placeholder | 事件: change:value, clear
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchInput } from '@ksyun-internal/versatile';
+
+const keyword = ref('');
+</script>
+
+<template>
+  <SearchInput v-model="keyword" :clearable="true" placeholder="搜索实例名称" />
+</template>
+```
+
+### 监听确认输入发起搜索
+**场景**: 在用户回车或确认输入时再发起一次正式查询。
+
+通过 change:value 在用户确认输入后发起查询。
+
+**使用的 API**: 属性: modelValue, placeholder | 事件: change:value
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchInput } from '@ksyun-internal/versatile';
+
+const keyword = ref('');
+const handleChange = (value: string) => {
+  console.log('query keyword:', value);
+};
+</script>
+
+<template>
+  <SearchInput
+    v-model="keyword"
+    placeholder="请输入镜像名称"
+    @change:value="handleChange"
+  />
+</template>
+```
+
+## 相关组件
+Search, Input
+

package/docs_for_llm/searchitems.doc.md

@@ -0,0 +1,116 @@
+# 检索项 (SearchItems)
+
+用于展示和管理当前检索条件标签的组件，适合复杂筛选场景中回显用户已选条件，并支持快速删除和清空。
+
+**关键词**: search items, filters, filter tags, 检索项, 筛选条件, 条件回显, 搜索标签, 已选条件
+
+**使用场景**: 复杂检索条件回显、列表页多条件筛选、已选条件快速删除、列表页筛选状态持久化
+
+## 导入语句
+```typescript
+import { SearchItems } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `Record<string, string | number>` | `{}` | 否 | 检索项数据对象 | - | - |
+| searchKey | `string` | `""` | 否 | 持久化存储时使用的 key | - | - |
+| title | `string` | `"检索项"` | 否 | 检索项区域标题 | - | - |
+| separator | `string` | `"|"` | 否 | 多值拼接分隔符 | - | - |
+| placeholderSeparator | `string | RegExp` | `/,+|\|+/g` | 否 | 占位分隔符匹配规则 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| delete:item | `@delete:item` | 删除单个检索条件时触发，可用于同步列表查询参数。 | `key?: string, value?: SearchItem` | - |
+| delete:all | `@delete:all` | 清空全部检索条件时触发，通常配合重置分页和重新拉取数据。 | `-` | - |
+
+### 事件参数说明
+**delete:item**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| key | `string` | 否 | - | 被删除检索项所属的分组 key，通常对应当前列表或筛选区的唯一标识。 |
+| value | `SearchItem` | 否 | - | 被删除的检索项对象，包含 label、key、text、value 等字段。 |
+
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| get | 获取当前组件维护的全部检索项，用于外部读取当前筛选状态。 | `-` | `SearchItem[]` |
+| add | 追加一个新的检索条件，并立即同步到当前检索项列表中。 | `searchItem: SearchItem` | `void` |
+| del | 按照给定条件删除一个已存在的检索项。 | `item: Partial<SearchItem>, unique?: boolean, isTriggerEmit?: boolean` | `void` |
+| clear | 清空当前 searchKey 下保存的检索项，常用于重置单个列表视图的筛选状态。 | `-` | `void` |
+| clearAll | 清空组件维护的全部检索项，通常用于一键重置筛选条件。 | `-` | `void` |
+
+### 方法参数说明
+**add**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| searchItem | `SearchItem` | 是 | - | 待追加的检索项对象，通常包含 key、label 和 value。 |
+
+**del**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| item | `Partial<SearchItem>` | 是 | - | 用于匹配删除目标的条件对象，可传 key、label 或 value。 |
+| unique | `boolean` | 否 | `false` | 是否按唯一条件精确删除匹配项，适合区分同 key 下的多个候选值。 |
+| isTriggerEmit | `boolean` | 否 | `true` | 删除后是否继续触发组件事件，批量同步内部状态时可按需关闭。 |
+
+## 使用示例
+### 复杂筛选条件回显
+**场景**: 在复杂列表页中回显并管理用户已选择的过滤条件。
+
+把当前列表的多个过滤条件展示为可删除的检索项。
+
+**使用的 API**: 属性: modelValue, searchKey, title | 事件: delete:item, delete:all
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchItems } from '@ksyun-internal/versatile';
+
+const filters = ref({
+  name: 'web-prod',
+  status: 'running',
+  project: '核心项目',
+});
+</script>
+
+<template>
+  <SearchItems v-model="filters" search-key="instance-list" title="当前筛选" />
+</template>
+```
+
+### 通过组件方法清空检索项
+**场景**: 在切换页签或重置查询条件时，从外部统一清空当前检索项。
+
+使用 ref 调用 clearAll，在切换列表视图时统一重置筛选条件。
+
+**使用的 API**: 属性: modelValue, searchKey | 事件: delete:all | 方法: clearAll
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchItems } from '@ksyun-internal/versatile';
+
+const searchItemsRef = ref<InstanceType<typeof SearchItems>>();
+const filters = ref({
+  name: 'web-prod',
+  project: '核心项目',
+});
+const resetFilters = () => {
+  searchItemsRef.value?.clearAll();
+};
+</script>
+
+<template>
+  <button @click="resetFilters">重置全部筛选</button>
+  <SearchItems ref="searchItemsRef" v-model="filters" search-key="instance-list" />
+</template>
+```
+
+## 相关组件
+Search, ProTable
+