king-design-analyzer 2.1.7 → 2.2.0

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
+

package/docs_for_llm/searchselect.doc.md

@@ -0,0 +1,126 @@
+# 搜索下拉框 (SearchSelect)
+
+面向搜索维度或搜索值选择的业务下拉组件，适合在搜索框左侧选择字段，也适合承载小规模筛选选项。
+
+**关键词**: search select, search field select, filter select, 下拉搜索, 搜索下拉框, 检索字段选择, 筛选字段, 条件下拉
+
+**使用场景**: 搜索类型选择、业务下拉筛选、组合搜索左侧字段切换、小规模筛选项选择
+
+## 导入语句
+```typescript
+import { SearchSelect } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | `inherited:Select` | `<Select v-model="selectedList" multiple>` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选，输入时可过滤选项 | `inherited:Select` | `<Select v-model="selected" filterable>` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | `inherited:Select` | `<Select v-model="selected" :loading="isLoading">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Select` | `<Select disabled>` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | `inherited:Select` | `<Select name="city">` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Select` | `<Select size="small">` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的下拉图标 | `inherited:Select` | `<Select hideIcon>` |
+| clearable | `boolean` | `false` | 否 | 是否可清空已选内容 | `inherited:Select` | `<Select v-model="selected" clearable>` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Select` | `<Select fluid>` |
+| inline | `boolean` | `false` | 否 | 展示内联模式，该模式下组件没有边框，宽度和高度由内容撑开 | `inherited:Select` | `<Select inline>` |
+| placeholder | `string` | `"请选择"` | 否 | 占位文案 | `inherited:Select` | `<Select placeholder="请选择城市">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | `inherited:Select` | `<Select :container="() => document.body">` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，组件自动添加单位 px | `inherited:Select` | `<Select :width="200">` |
+| filter | `(keywords: string, props: any) => boolean` | `(keywords, props) => props.label.toLowerCase().includes(keywords) || props.value.toLowerCase().includes(keywords)` | 否 | 当支持筛选时，可以自定义筛选规则 | `inherited:Select` | `<Select filterable :filter="(kw, props) => props.label.includes(kw)">` |
+| searchable | `boolean` | `false` | 否 | 是否在弹出菜单中展示搜索框 | `inherited:Select` | `<Select searchable>` |
+| creatable | `boolean` | `false` | 否 | 是否支持创建新的选项，可以配合 filterable 使用 | `inherited:Select` | `<Select filterable creatable>` |
+| labelMap | `Map<any, string>` | `new Map()` | 否 | 建立 value 到 label 的映射，可以在 value 不在 Option 集合中时正确展示 label | `inherited:Select` | `<Select :labelMap="new Map([['custom', '自定义选项']])">` |
+| card | `boolean` | `false` | 否 | 是否展示 card 模式 | `inherited:Select` | `<Select card>` |
+| autoDisableArrow | `boolean` | `false` | 否 | 是否在没有更多可选项时，给箭头一个 disabled 状态来提示用户 | `inherited:Select` | `<Select autoDisableArrow>` |
+| keepKeywords | `boolean` | `true` | 否 | 是否在选中选项后保留搜索关键字，配合 filterable 使用 | `inherited:Select` | `<Select filterable :keepKeywords="false">` |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | `inherited:Select` | `<Select :show="isMenuVisible">` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | `inherited:Select` | `<Select position="top">` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Select` | `<Select flat>` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | `inherited:Select` | `<Select nowrap>` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | `inherited:Select` | `<Select multiple draggable>` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | `inherited:Select` | `<Select virtual>` |
+| label | `string` | `undefined` | 否 | 下拉框前置标题或说明文案 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助提示文案 | - | - |
+| modelValue | `string` | `""` | 否 | 当前选中的值 | - | - |
+| searches | `SearchType[] | Record<string, SearchType>` | `[]` | 否 | 搜索选项列表 | - | - |
+| searchKeyName | `string` | `"key"` | 否 | 搜索项中 value 字段名 | - | - |
+| searchLabelName | `string` | `"label"` | 否 | 搜索项中 label 字段名 | - | - |
+| searchGroups | `SearchGroupItem[]` | `undefined` | 否 | 搜索项分组配置 | - | - |
+| showValue | `boolean` | `false` | 否 | 选项展示时是否同时显示 value | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| change:value | `@change:value` | 下拉选中值变化时触发，通常用于联动输入框占位或直接发起查询。 | `value?: string` | - |
+
+### 事件参数说明
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 当前选中的搜索项 key。 |
+
+## 使用示例
+### 选择搜索维度
+**场景**: 在列表搜索区切换当前按哪个字段检索。
+
+在组合搜索中用下拉框切换当前搜索字段。
+
+**使用的 API**: 属性: modelValue, label, searches | 事件: change:value
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchSelect } from '@ksyun-internal/versatile';
+
+const searchKey = ref('name');
+const searches = [
+  { key: 'name', label: '实例名称' },
+  { key: 'id', label: '实例 ID' },
+  { key: 'ip', label: '内网 IP' },
+];
+</script>
+
+<template>
+  <SearchSelect
+    v-model="searchKey"
+    label="搜索字段"
+    :searches="searches"
+  />
+</template>
+```
+
+### 同时展示标签和值
+**场景**: 在字段名称可能重复或歧义较大时同时展示 key 和 label。
+
+在选项较多时同时展示 value，方便用户准确识别字段。
+
+**使用的 API**: 属性: modelValue, searches, helper, showValue | 事件: change:value
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchSelect } from '@ksyun-internal/versatile';
+
+const searchKey = ref('instanceId');
+const searches = [
+  { key: 'instanceId', label: '实例 ID' },
+  { key: 'privateIp', label: '内网 IP' },
+  { key: 'projectId', label: '项目 ID' },
+];
+</script>
+
+<template>
+  <SearchSelect
+    v-model="searchKey"
+    :searches="searches"
+    helper="请选择检索字段"
+    :show-value="true"
+  />
+</template>
+```
+
+## 相关组件
+Search, Select
+

package/docs_for_llm/select.doc.md

@@ -12,64 +12,48 @@ import { Select, Option, OptionGroup } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `any` | `""` | 否 | 当前选择的元素，可用 v-model 双向绑定 | `<Select v-model="selected"></Select>` |
-| multiple | `boolean` | `false` | 否 | 是否支持多选 | `<Select v-model="selectedList" multiple></Select>` |
-| filterable | `boolean` | `false` | 否 | 是否支持筛选，输入时可过滤选项 | `<Select v-model="selected" filterable></Select>` |
-| loading | `boolean` | `false` | 否 | 数据加载状态 | `<Select v-model="selected" :loading="isLoading"></Select>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 | `<Select disabled></Select>` |
-| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | `<Select name="city"></Select>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `<Select size="small"></Select>` |
-| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的下拉图标 | `<Select hideIcon></Select>` |
-| clearable | `boolean` | `false` | 否 | 是否可清空已选内容 | `<Select v-model="selected" clearable></Select>` |
-| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `<Select fluid></Select>` |
-| inline | `boolean` | `false` | 否 | 展示内联模式，该模式下组件没有边框，宽度和高度由内容撑开 | `<Select inline></Select>` |
-| placeholder | `string` | `"请选择"` | 否 | 占位文案 | `<Select placeholder="请选择城市"></Select>` |
-| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | `<Select :container="() => document.body"></Select>` |
-| width | `number | string` | `undefined` | 否 | 指定宽度，组件自动添加单位 px | `<Select :width="200"></Select>` |
-| filter | `(keywords: string, props: any) => boolean` | `(keywords, props) => props.label.toLowerCase().includes(keywords) || props.value.toLowerCase().includes(keywords)` | 否 | 当支持筛选时，可以自定义筛选规则 | `<Select filterable :filter="(kw, props) => props.label.includes(kw)"></Select>` |
-| searchable | `boolean` | `false` | 否 | 是否在弹出菜单中展示搜索框 | `<Select searchable></Select>` |
-| creatable | `boolean` | `false` | 否 | 是否支持创建新的选项，可以配合 filterable 使用 | `<Select filterable creatable></Select>` |
-| labelMap | `Map<any, string>` | `new Map()` | 否 | 建立 value 到 label 的映射，可以在 value 不在 Option 集合中时正确展示 label | `<Select :labelMap="new Map([['custom', '自定义选项']])"></Select>` |
-| card | `boolean` | `false` | 否 | 是否展示 card 模式 | `<Select card></Select>` |
-| autoDisableArrow | `boolean` | `false` | 否 | 是否在没有更多可选项时，给箭头一个 disabled 状态来提示用户 | `<Select autoDisableArrow></Select>` |
-| keepKeywords | `boolean` | `true` | 否 | 是否在选中选项后保留搜索关键字，配合 filterable 使用 | `<Select filterable :keepKeywords="false"></Select>` |
-| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | `<Select :show="isMenuVisible"></Select>` |
-| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | `<Select position="top"></Select>` |
-| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `<Select flat></Select>` |
-| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | `<Select multiple draggable></Select>` |
-| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | `<Select virtual></Select>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `any` | `""` | 否 | 当前选择的元素，可用 v-model 双向绑定 | - | `<Select v-model="selected">` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | - | `<Select v-model="selectedList" multiple>` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选，输入时可过滤选项 | - | `<Select v-model="selected" filterable>` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | - | `<Select v-model="selected" :loading="isLoading">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | - | `<Select disabled>` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | - | `<Select name="city">` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | - | `<Select size="small">` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的下拉图标 | - | `<Select hideIcon>` |
+| clearable | `boolean` | `false` | 否 | 是否可清空已选内容 | - | `<Select v-model="selected" clearable>` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | - | `<Select fluid>` |
+| inline | `boolean` | `false` | 否 | 展示内联模式，该模式下组件没有边框，宽度和高度由内容撑开 | - | `<Select inline>` |
+| placeholder | `string` | `"请选择"` | 否 | 占位文案 | - | `<Select placeholder="请选择城市">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | - | `<Select :container="() => document.body">` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，组件自动添加单位 px | - | `<Select :width="200">` |
+| filter | `(keywords: string, props: any) => boolean` | `(keywords, props) => props.label.toLowerCase().includes(keywords) || props.value.toLowerCase().includes(keywords)` | 否 | 当支持筛选时，可以自定义筛选规则 | - | `<Select filterable :filter="(kw, props) => props.label.includes(kw)">` |
+| searchable | `boolean` | `false` | 否 | 是否在弹出菜单中展示搜索框 | - | `<Select searchable>` |
+| creatable | `boolean` | `false` | 否 | 是否支持创建新的选项，可以配合 filterable 使用 | - | `<Select filterable creatable>` |
+| labelMap | `Map<any, string>` | `new Map()` | 否 | 建立 value 到 label 的映射，可以在 value 不在 Option 集合中时正确展示 label | - | `<Select :labelMap="new Map([['custom', '自定义选项']])">` |
+| card | `boolean` | `false` | 否 | 是否展示 card 模式 | - | `<Select card>` |
+| autoDisableArrow | `boolean` | `false` | 否 | 是否在没有更多可选项时，给箭头一个 disabled 状态来提示用户 | - | `<Select autoDisableArrow>` |
+| keepKeywords | `boolean` | `true` | 否 | 是否在选中选项后保留搜索关键字，配合 filterable 使用 | - | `<Select filterable :keepKeywords="false">` |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | - | `<Select :show="isMenuVisible">` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | - | `<Select position="top">` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | - | `<Select flat>` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | - | `<Select nowrap>` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | - | `<Select multiple draggable>` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | - | `<Select virtual>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| show | `@show` | 菜单弹出时触发 | `-` | `<Select @show="handleShow"></Select>` |
-| hide | `@hide` | 菜单隐藏时触发 | `-` | `<Select @hide="handleHide"></Select>` |
+| show | `@show` | 菜单弹出时触发 | `-` | `<Select @show="handleShow">` |
+| hide | `@hide` | 菜单隐藏时触发 | `-` | `<Select @hide="handleHide">` |
 
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('下拉菜单已展开');
-};
-```
-
-**hide**:
-```typescript
-const handleHide = () => {
-  console.log('下拉菜单已关闭');
-};
-```
-
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| value | 自定义选择结果的展示 | `undefined` | - |
-| values | 自定义多选的选择结果的展示 | `undefined` | - |
-| prefix | 自定义输入框前面展示的内容 | `undefined` | - |
-| suffix | 自定义输入框后面展示的内容 | `undefined` | - |
-| menu | 自定义整个菜单的内容 | `undefined` | - |
+| show | 主动展开选择器下拉面板。 | `-` | `void` |
+| hide | 主动关闭选择器下拉面板。 | `-` | `void` |
+| position | 重新计算当前选择器下拉面板的位置。 | `-` | `void` |
 
 ## 子组件 (Sub-Components)
 ### Option
@@ -90,16 +74,15 @@ const handleHide = () => {
   <Option value="apple" label="苹果" />
 </OptionGroup>` |
 
-**插槽**:
-- `undefined`: 定义复杂的分组标签名
-
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 多选模式下 value 类型错误
 > **错误用法**: `const selected = ref('');
 <Select v-model="selected" multiple>`
 > **正确写法**: `const selected = ref<string[]>([]);
 <Select v-model="selected" multiple>`
 > **说明**: 使用 multiple 多选模式时，value 必须是数组类型，而非字符串
 
+### Option 未设置 value 属性
 > **错误用法**: `<Select v-model="selected">
   <Option label="苹果" />
 </Select>`
@@ -108,10 +91,12 @@ const handleHide = () => {
 </Select>`
 > **说明**: Option 必须设置 value 属性，否则无法正确绑定选中值
 
+### 使用不存在的 size 值 (Select)
 > **错误用法**: `<Select size="medium">`
 > **正确写法**: `<Select size="default">`
 > **说明**: Select 的 size 只支持 large, default, small, mini。常见错误是使用 medium 值。
 
+### 使用 creatable 但未启用 filterable
 > **错误用法**: `<Select creatable>`
 > **正确写法**: `<Select filterable creatable>`
 > **说明**: creatable 属性需要配合 filterable 使用，因为创建新选项需要用户输入

package/docs_for_llm/sidebar.doc.md

@@ -0,0 +1,133 @@
+# 侧边导航 (Sidebar)
+
+用于控制台左侧导航的多层级菜单组件，支持路由联动、展开状态管理和默认选中逻辑。
+
+**关键词**: sidebar, navigation, menu tree, 侧边栏, 菜单导航, 多级菜单, 控制台导航, 左侧导航
+
+**使用场景**: 控制台左侧导航、多级菜单导航、资源中心侧边菜单、路由驱动的后台导航
+
+## 导入语句
+```typescript
+import { Sidebar } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `undefined` | 否 | 侧边栏标题 | - | - |
+| selectedKey | `Key` | `undefined` | 否 | 当前选中的菜单 key | - | - |
+| expandedKeys | `Key[]` | `undefined` | 否 | 当前展开的菜单 key 列表 | - | - |
+| menus | `Menus` | `undefined` | 是 | 菜单配置树 | - | - |
+| router | `boolean` | `false` | 否 | 是否启用路由模式 | - | - |
+| autoSelectDefault | `boolean` | `true` | 否 | 未匹配到路由时是否自动选中默认菜单项 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:selectedKey | `@update:selectedKey` | 当前选中菜单 key 变化时触发，可用于同步路由或高亮状态。 | `value?: string` | - |
+| update:expandedKeys | `@update:expandedKeys` | 展开的菜单节点变化时触发，适合持久化用户展开习惯。 | `value?: string[]` | - |
+| update:menuItem | `@update:menuItem` | 当前选中的完整菜单项变化时触发，便于读取标题、路由等附加字段。 | `value?: SidebarMenuItem` | - |
+| change:menus | `@change:menus` | 菜单结构变化时触发，适合动态菜单加载后重新同步状态。 | `value?: SidebarMenuItem[]` | - |
+
+### 事件参数说明
+**update:selectedKey**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 当前选中的菜单 key。 |
+
+**update:expandedKeys**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string[]` | 否 | - | 当前处于展开状态的菜单 key 列表。 |
+
+**update:menuItem**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `SidebarMenuItem` | 否 | - | 当前命中的菜单项对象，包含标题、路由参数和 children 等扩展字段。 |
+
+**change:menus**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `SidebarMenuItem[]` | 否 | - | 当前可渲染的菜单树数组，常用于动态菜单加载后做缓存或二次处理。 |
+
+## 使用示例
+### 控制台侧边导航
+**场景**: 在控制台左侧展示资源管理导航。
+
+渲染一个带二级菜单的控制台导航树。
+
+**使用的 API**: 属性: title, selectedKey, expandedKeys, menus | 事件: update:selectedKey, update:expandedKeys
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Sidebar } from '@ksyun-internal/versatile';
+
+const selectedKey = ref('instances');
+const expandedKeys = ref(['compute']);
+const menus = [
+  {
+    key: 'compute',
+    label: '计算',
+    children: [
+      { key: 'instances', label: '实例列表' },
+      { key: 'images', label: '镜像' },
+    ],
+  },
+];
+</script>
+
+<template>
+  <Sidebar
+    title="云服务器"
+    v-model:selected-key="selectedKey"
+    v-model:expanded-keys="expandedKeys"
+    :menus="menus"
+  />
+</template>
+```
+
+### 路由模式侧边导航
+**场景**: 在多级控制台中让菜单选中状态与 URL 同步。
+
+在路由驱动的控制台中让侧边栏自动和当前页面同步。
+
+**使用的 API**: 属性: selectedKey, expandedKeys, menus, router, autoSelectDefault | 事件: update:selectedKey, update:expandedKeys
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Sidebar } from '@ksyun-internal/versatile';
+
+const selectedKey = ref('dashboard');
+const expandedKeys = ref(['overview']);
+const menus = [
+  {
+    key: 'overview',
+    label: '概览',
+    children: [
+      { key: 'dashboard', label: '仪表盘' },
+      { key: 'alerts', label: '告警中心' },
+    ],
+  },
+];
+</script>
+
+<template>
+  <Sidebar
+    v-model:selected-key="selectedKey"
+    v-model:expanded-keys="expandedKeys"
+    :menus="menus"
+    :router="true"
+    :auto-select-default="false"
+  />
+</template>
+```
+
+## 相关组件
+Header, LayoutContent
+