king-design-analyzer 2.1.9 → 2.2.1

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,94 +12,251 @@ 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">` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| value | 自定义单选模式下的已选值展示内容 | `#value="[value, label]"` | `<Select v-model="selected">
+  <template #value="[value, label]">
+    <span>{{ label }} ({{ value }})</span>
+  </template>
+</Select>` |
+| values | 自定义多选模式下的已选值展示内容 | `#values="[values, labels]"` | `<Select v-model="selectedList" multiple>
+  <template #values="[values, labels]">
+    <span>已选 {{ labels.length }} 项</span>
+  </template>
+</Select>` |
+| prefix | 扩展选择框前缀内容 | `#prefix` | `<Select>
+  <template #prefix>
+    <span class="k-icon-search"></span>
+  </template>
+</Select>` |
+| suffix | 扩展选择框后缀内容 | `#suffix` | `<Select>
+  <template #suffix>
+    <span>自定义</span>
+  </template>
+</Select>` |
+| menu | 自定义整个下拉菜单区域 | `#menu` | `<Select>
+  <template #menu>
+    <div>自定义菜单内容</div>
+  </template>
+</Select>` |
+
+### 插槽参数说明
+**value**
+
+- 参数结构: #value="[value, label]"
+- 参数列表: `value: T`、`label: string`
+
+**values**
+
+- 参数结构: #values="[values, labels]"
+- 参数列表: `values: T[]`、`labels: string[]`
+
+**prefix**
+
+- 参数结构: 无参数
+
+**suffix**
+
+- 参数结构: 无参数
+
+**menu**
+
+- 参数结构: 无参数
+
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| show | 主动展开选择器下拉面板。 | `-` | `void` |
+| hide | 主动关闭选择器下拉面板。 | `-` | `void` |
+| position | 重新计算当前选择器下拉面板的位置。 | `-` | `void` |
+
+### 方法调用示例
+**show**
 
-### 事件处理函数示例
-**show**:
 ```typescript
-const handleShow = () => {
-  console.log('下拉菜单已展开');
-};
+selectRef.value?.show();
 ```
 
-**hide**:
+**hide**
+
 ```typescript
-const handleHide = () => {
-  console.log('下拉菜单已关闭');
-};
+selectRef.value?.hide();
 ```
 
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
-| --- | --- | --- | --- |
-| value | 自定义选择结果的展示 | `undefined` | - |
-| values | 自定义多选的选择结果的展示 | `undefined` | - |
-| prefix | 自定义输入框前面展示的内容 | `undefined` | - |
-| suffix | 自定义输入框后面展示的内容 | `undefined` | - |
-| menu | 自定义整个菜单的内容 | `undefined` | - |
+**position**
+
+```typescript
+selectRef.value?.position();
+```
 
 ## 子组件 (Sub-Components)
 ### Option
 选项组件，用于定义下拉选项
 
+#### 属性 (Props)
 | 属性名 | 类型 | 说明 | 示例 |
 | --- | --- | --- | --- |
 | value | `any` | 选中的值 | `<Option value="apple" label="苹果" />` |
 | label | `string` | 展示文案，同时也作为筛选的内容。不存在时使用 children 的文本 | `<Option value="apple" label="苹果" />` |
 | disabled | `boolean` | 是否禁用该项选择 | `<Option value="apple" label="苹果" disabled />` |
 
+#### 组合示例
+##### 禁用选项
+**场景**: 禁用下拉框中的某些选项
+
+禁用特定的选项
+
+**命中的子组件 API**: 属性: value, label, disabled
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select, Option } from '@king-design/vue';
+
+const selected = ref('');
+</script>
+<template>
+  <Select v-model="selected">
+    <Option value="apple" label="苹果" />
+    <Option value="orange" label="橙子" disabled />
+    <Option value="banana" label="香蕉" />
+  </Select>
+</template>
+```
+
+##### 多选
+**场景**: 创建一个支持多选的下拉框
+
+支持选择多个选项
+
+**命中的子组件 API**: 属性: value, label
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select, Option } from '@king-design/vue';
+
+const selected = ref<string[]>([]);
+</script>
+<template>
+  <Select v-model="selected" multiple placeholder="请选择多项">
+    <Option value="apple" label="苹果" />
+    <Option value="orange" label="橙子" />
+    <Option value="banana" label="香蕉" />
+    <Option value="grape" label="葡萄" />
+  </Select>
+</template>
+```
+
+##### 可搜索
+**场景**: 创建一个可以通过关键字搜索的下拉框
+
+可以通过输入关键字筛选选项
+
+**命中的子组件 API**: 属性: value, label
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select, Option } from '@king-design/vue';
+
+const selected = ref('');
+</script>
+<template>
+  <Select v-model="selected" filterable placeholder="输入关键字搜索">
+    <Option value="beijing" label="北京" />
+    <Option value="shanghai" label="上海" />
+    <Option value="guangzhou" label="广州" />
+    <Option value="shenzhen" label="深圳" />
+  </Select>
+</template>
+```
+
 ### OptionGroup
 选项分组组件，用于对选项进行分组展示
 
+#### 属性 (Props)
 | 属性名 | 类型 | 说明 | 示例 |
 | --- | --- | --- | --- |
 | label | `string | number | VNode` | 分组标签名 | `<OptionGroup label="水果">
   <Option value="apple" label="苹果" />
 </OptionGroup>` |
 
-**插槽**:
-- `undefined`: 定义复杂的分组标签名
+#### 组合示例
+##### 分组选项
+**场景**: 创建带有分组的下拉选择框
+
+使用 OptionGroup 对选项进行分组
+
+**命中的子组件 API**: 属性: label
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select, Option, OptionGroup } from '@king-design/vue';
+
+const selected = ref('');
+</script>
+<template>
+  <Select v-model="selected" placeholder="请选择">
+    <OptionGroup label="水果">
+      <Option value="apple" label="苹果" />
+      <Option value="orange" label="橙子" />
+    </OptionGroup>
+    <OptionGroup label="蔬菜">
+      <Option value="tomato" label="番茄" />
+      <Option value="potato" label="土豆" />
+    </OptionGroup>
+  </Select>
+</template>
+```
 
 ## 常见错误与正确用法 (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 +265,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
+