king-design-analyzer 2.1.9 → 2.2.0

package/docs_for_llm/useTable.doc.md

@@ -0,0 +1,57 @@
+# 表格状态管理 (useTable)
+
+集中管理表格勾选、展开、列显隐和导出相关状态，适合原子 Table 和业务表格容器共享同一套表格控制逻辑。
+
+**关键词**: useTable, Table, 勾选状态, 列显隐, 导出表格, rowKey
+
+## 导入语句
+```typescript
+import { useTable } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ rowKey?: string; notCheckTip?: string; tableFields?: TableFields }` | 否 | 表格配置，可指定 rowKey、未勾选提示文案和列配置定义 |
+
+## 返回值
+```typescript
+{ checkedKeys: Ref<string[]>; expandedKeys: Ref<(string | number)[]>; isChecked: ComputedRef<number>; canCheck: ComputedRef<{ disabled: boolean; msg: string }>; tableRef: Ref<Table | undefined>; componentRef: Ref<any>; noCheckedColFields: Ref<string[]>; setRowKey: Function; exportTableData: Function; hideCol: Function; getTableColTitle: ((key: string) => string) | null; initTableColumnProps: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 多选或导出场景没有稳定 rowKey，导致勾选数据不稳定
+> **错误用法**: `const table = useTable();`
+> **正确写法**: `const table = useTable({ rowKey: 'id' });`
+> **说明**: 在业务表格中建议显式指定 rowKey，避免勾选项和导出数据映射错乱。
+
+## 使用示例
+### 管理表格勾选和列显隐
+在列表页中集中维护勾选状态和动态列配置
+
+```vue
+<script setup lang="ts">
+import { useTable } from '@ksyun-internal/versatile';
+
+const tableFields = [
+  { key: 'name', label: '实例名称', checked: true },
+  { key: 'status', label: '状态', checked: true },
+];
+const { checkedKeys, tableRef, canCheck, initTableColumnProps } = useTable({
+  rowKey: 'id',
+  tableFields,
+});
+</script>
+```
+
+### 导出当前表格数据
+通过 hook 暴露的导出方法触发表格导出
+
+```vue
+<script setup lang="ts">
+import { useTable } from '@ksyun-internal/versatile';
+
+const { exportTableData } = useTable({ rowKey: 'id' });
+</script>
+```
+

package/docs_for_llm/useTableGroup.doc.md

@@ -0,0 +1,47 @@
+# 表格分组筛选状态 (useTableGroup)
+
+管理 Table 或 ProTable 的 group 筛选状态，并可与 SearchItems 联动生成可展示的筛选项。
+
+**关键词**: useTableGroup, group, ProTable, 表格筛选, SearchItems, 状态分组
+
+## 导入语句
+```typescript
+import { useTableGroup } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ page?: Ref<number>; key?: string; defalutValue?: any; searchItemsRef?: Ref<any>; labelMaps?: Record<string, string> | Ref<Record<string, string>>; groupLabel?: string | Record<string, string | { label: string }>; isShowSearchItem?: boolean }` | 否 | 分组筛选配置，可联动分页、SearchItems 和字段标签映射 |
+
+## 返回值
+```typescript
+{ status: ComputedRef<any>; group: Ref<Record<string, any>>; resetGroup: Function; changeGroup: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### SearchItems 展示 group 条件时没有提供 labelMaps 或 groupLabel
+> **错误用法**: `useTableGroup({ searchItemsRef });`
+> **正确写法**: `useTableGroup({ searchItemsRef, labelMaps, groupLabel: '状态' });`
+> **说明**: 如果要把 group 同步到 SearchItems，建议补齐展示文案映射。
+
+## 使用示例
+### 配合 ProTable 的 group 筛选
+将 group 状态和 SearchItems 联动，统一驱动表格筛选
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { usePagination, useTableGroup } from '@ksyun-internal/versatile';
+
+const { page } = usePagination();
+const searchItemsRef = ref();
+const { group, changeGroup, resetGroup } = useTableGroup({
+  page,
+  key: 'status',
+  searchItemsRef,
+  labelMaps: { using: '运行中', shutdown: '已关机' },
+});
+</script>
+```
+

package/docs_for_llm/useTableSort.doc.md

@@ -0,0 +1,40 @@
+# 表格排序状态 (useTableSort)
+
+统一管理表格排序字段和方向，并提供多种派生排序状态，适合请求参数、UI 高亮和布尔/整数映射场景。
+
+**关键词**: useTableSort, 排序, TableSortValue, ProTable, 列表排序, sort
+
+## 导入语句
+```typescript
+import { useTableSort } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| page | `Ref<number | undefined>` | 否 | 分页页码，传入后在切换排序时可联动重置页码 |
+
+## 返回值
+```typescript
+{ sort: Ref<TableSortValue>; curSortKey: ComputedRef<string | undefined>; curSortType: ComputedRef<'desc' | 'asc' | undefined>; curSortTypeByInt: ComputedRef<0 | 1 | -1>; curSortTypeByBoolean: ComputedRef<boolean | ''>; changeSort: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 自己维护 asc/desc 和 0/1/-1 的映射，重复实现 hook 已有能力
+> **错误用法**: `const sortType = computed(() => sort.value.type === 'asc' ? 1 : -1);`
+> **正确写法**: `const { curSortTypeByInt } = useTableSort(page);`
+> **说明**: hook 已经提供多种派生排序表示，优先复用。
+
+## 使用示例
+### 列表排序状态
+将排序状态集中管理，并把变更方法绑定给表格
+
+```vue
+<script setup lang="ts">
+import { usePagination, useTableSort } from '@ksyun-internal/versatile';
+
+const { page } = usePagination();
+const { sort, curSortKey, curSortType, changeSort } = useTableSort(page);
+</script>
+```
+

package/docs_for_llm/useToState.doc.md

@@ -0,0 +1,112 @@
+# Props 转 State (useToState)
+
+将 props 中的属性转换为响应式 state，支持 v-model 双向绑定。当 props 变化时自动更新 state，当 state 变化时自动触发 emit 更新父组件。
+
+**关键词**: useToState, props, state, v-model, 双向绑定, 响应式
+
+## 导入语句
+```typescript
+import { useToState } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| props | `P extends object` | 是 | 组件的 props 对象（通过 defineProps 获取） |
+| key | `keyof P` | 是 | 要监听的 prop 名称（字符串） |
+| emit | `Emits<K & string, P[K]>` | 是 | 组件的 emit 函数（通过 defineEmits 获取），需要包含 update:key 事件 |
+| defaults | `NonNullable<P[K]>` | 否 | 默认值。如果提供，返回的 Ref 将保证不为 undefined |
+
+## 重载签名 (Overloads)
+### `useToState<P, K>(props: P, key: K, emit: Emits): Ref<P[K]>`
+基础用法，返回可能为 undefined 的响应式值
+
+### `useToState<P, K>(props: P, key: K, emit: Emits, defaults: NonNullable<P[K]>): Ref<NonNullable<P[K]>>`
+带默认值用法，返回保证非 undefined 的响应式值
+
+## 返回值
+```typescript
+Ref<P[K]>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 忘记传递 emit 参数
+> **错误用法**: `const value = useToState(props, 'modelValue');`
+> **正确写法**: `const value = useToState(props, 'modelValue', emit);`
+> **说明**: useToState 需要 emit 函数来实现双向绑定，缺少 emit 会导致编译错误
+
+### emit 没有定义对应的 update:key 事件
+> **错误用法**: `const emit = defineEmits(['change']);
+const value = useToState(props, 'modelValue', emit);`
+> **正确写法**: `const emit = defineEmits(['update:modelValue']);
+const value = useToState(props, 'modelValue', emit);`
+> **说明**: useToState 内部会调用 emit('update:key', newValue)，必须在 defineEmits 中声明对应事件
+
+### key 参数不是 props 中定义的属性
+> **错误用法**: `const props = defineProps<{ name: string }>();
+const value = useToState(props, 'age', emit);`
+> **正确写法**: `const props = defineProps<{ name: string; age?: number }>();
+const value = useToState(props, 'age', emit);`
+> **说明**: key 必须是 props 中已定义的属性名
+
+## 使用示例
+### 基础用法
+将 modelValue prop 转换为响应式 state
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+type Props = { modelValue?: string };
+type Emits = { (e: 'update:modelValue', v?: string): void };
+
+const props = defineProps<Props>();
+const emit = defineEmits<Emits>();
+
+const value = useToState(props, 'modelValue', emit);
+</script>
+<template>
+  <input v-model="value" />
+</template>
+```
+
+### 带默认值用法
+提供默认值，确保返回值不为 undefined
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+const props = defineProps<{ count?: number }>();
+const emit = defineEmits(['update:count']);
+
+// 默认值为 0，count 永远不为 undefined
+const count = useToState(props, 'count', emit, 0);
+</script>
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+### 对象类型值
+将对象类型的 prop 转换为响应式 state
+
+```vue
+<script setup lang="ts">
+import { useToState } from '@ksyun-internal/versatile';
+
+type FormData = { name: string; age: number };
+type Props = { modelValue?: FormData };
+type Emits = { (e: 'update:modelValue', v?: FormData): void };
+
+const props = defineProps<Props>();
+const emit = defineEmits<Emits>();
+
+const formData = useToState(props, 'modelValue', emit, { name: '', age: 0 });
+</script>
+<template>
+  <input v-model="formData.name" />
+  <input v-model.number="formData.age" />
+</template>
+```
+

package/docs_for_llm/useUser.doc.md

@@ -0,0 +1,38 @@
+# 当前用户信息 (useUser)
+
+获取当前登录用户信息，适合在业务组件中读取 root 权限、当前用户 ID 或账号属性。
+
+**关键词**: useUser, 当前用户, 权限, isRoot, curUserId, 账号信息
+
+## 导入语句
+```typescript
+import { useUser } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+Ref<UserInfo | undefined>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接访问 user.value 的属性，没有处理未加载完成的情况
+> **错误用法**: `const isRoot = user.value.isRoot;`
+> **正确写法**: `const isRoot = user.value?.isRoot;`
+> **说明**: 返回值是 Ref<UserInfo | undefined>，初始化阶段可能为空。
+
+## 使用示例
+### 读取当前用户信息
+在页面初始化时获取当前用户及权限信息
+
+```vue
+<script setup lang="ts">
+import { useUser } from '@ksyun-internal/versatile';
+
+const user = useUser();
+</script>
+
+<template>
+  <div v-if="user">{{ user.curUserId }}</div>
+</template>
+```
+

package/docs_for_llm/useValidForm.doc.md

@@ -0,0 +1,41 @@
+# 表单校验管理 (useValidForm)
+
+封装 Form 实例的校验、重置和滚动定位能力，适合页面表单和弹窗表单统一管理。
+
+**关键词**: useValidForm, 表单校验, Form, validateByScroll, reset, 滚动定位
+
+## 导入语句
+```typescript
+import { useValidForm } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| models | `Ref<T>` | 否 | 表单模型对象，可在 reset 时恢复默认值 |
+
+## 返回值
+```typescript
+{ formRef: Ref<Form | undefined>; validate: Function; validateByScroll: Function; reset: Function; scrollIntoFirstInvalidFormItem: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 希望 reset 恢复初始模型，但没有把 models 传给 hook
+> **错误用法**: `const { reset } = useValidForm();`
+> **正确写法**: `const { reset } = useValidForm(models);`
+> **说明**: 如果需要重置业务表单值，建议把模型 Ref 传入 useValidForm。
+
+## 使用示例
+### 页面表单校验
+在提交前统一校验并定位第一个错误项
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useValidForm } from '@ksyun-internal/versatile';
+
+const models = ref({ name: '', region: '' });
+const { formRef, validateByScroll } = useValidForm(models);
+</script>
+```
+

package/docs_for_llm/vdialog.doc.md

@@ -0,0 +1,129 @@
+# 业务弹窗 (VDialog)
+
+在基础 Dialog 之上补充默认触发器、受控显隐和异步确认逻辑的业务弹窗组件，适合表单弹窗和危险操作确认。
+
+**关键词**: vdialog, dialog, 业务弹窗, 确认弹窗, 表单弹窗, trigger dialog
+
+**使用场景**: 表单弹窗、异步确认弹窗、通过按钮触发的操作弹窗
+
+## 导入语句
+```typescript
+import { VDialog } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 弹窗标题 | - | - |
+| size | `string` | `undefined` | 否 | 弹窗尺寸 | - | - |
+| width | `string | number` | `undefined` | 否 | 弹窗宽度 | - | - |
+| loading | `boolean` | `false` | 否 | 确认按钮加载状态 | - | - |
+| disabledOk | `boolean` | `false` | 否 | 是否禁用确认按钮 | - | - |
+| okText | `string` | `"确定"` | 否 | 确认按钮文案 | - | - |
+| cancelText | `string` | `"取消"` | 否 | 取消按钮文案 | - | - |
+| ok | `() => Promise<boolean | void> | boolean | void` | `undefined` | 否 | 确认时的异步处理函数，可返回 false 阻止关闭 | - | - |
+| cancel | `() => void` | `undefined` | 否 | 取消时的回调逻辑 | - | - |
+| container | `string | Function` | `undefined` | 否 | 指定弹窗挂载容器 | - | - |
+| overlay | `boolean` | `true` | 否 | 是否显示遮罩层 | - | - |
+| closable | `boolean` | `true` | 否 | 点击遮罩层是否可关闭 | - | - |
+| terminate | `() => void` | `undefined` | 否 | 关闭动作统一回调 | - | - |
+| escClosable | `boolean` | `true` | 否 | 是否允许 ESC 关闭 | - | - |
+| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | - | - |
+| draggable | `boolean` | `false` | 否 | 是否允许拖拽弹窗 | - | - |
+| mode | `string` | `undefined` | 否 | 弹窗展示模式 | - | - |
+| hideTrigger | `boolean` | `false` | 否 | 隐藏默认 trigger，作为受控弹窗使用 | - | - |
+| modelValue | `boolean | undefined` | `undefined` | 否 | 弹窗显示状态 | - | - |
+| btnProps | `ButtonProps` | `undefined` | 否 | 默认 trigger 按钮属性 | - | - |
+| btnText | `string` | `"打开对话框"` | 否 | 默认 trigger 按钮文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| open | `@open` | 弹窗打开后触发 | `-` | `<Dialog v-model="visible" @open="handleOpen">` |
+| close | `@close` | 弹窗关闭后触发，不管是什么原因导致的关闭 | `-` | `<Dialog v-model="visible" @close="handleClose">` |
+| ok | `@ok` | 点击确定按钮时触发 | `-` | `<Dialog v-model="visible" @ok="handleOk">` |
+| cancel | `@cancel` | 点击取消按钮时触发 | `-` | `<Dialog v-model="visible" @cancel="handleCancel">` |
+| terminate | `@terminate` | 用户强行关闭弹窗时触发：点击关闭按钮、点击遮罩层、按ESC键 | `-` | `<Dialog v-model="visible" @terminate="handleTerminate">` |
+| afterClose | `@after-close` | 弹窗退出动画执行完成后触发 | `-` | `<Dialog v-model="visible" @after-close="handleAfterClose">` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | 弹窗主体内容（body区域） | `默认插槽` | `<Dialog v-model="visible">
+  <p>弹窗内容</p>
+</Dialog>` |
+| header | 扩展弹窗头部 | `#header` | `<Dialog v-model="visible">
+  <template #header>
+    <h2>自定义头部</h2>
+  </template>
+</Dialog>` |
+| footer | 扩展弹窗底部按钮区域 | `#footer` | `<Dialog v-model="visible">
+  <template #footer>
+    <Button @click="visible = false">关闭</Button>
+    <Button type="primary" @click="handleSubmit">提交</Button>
+  </template>
+</Dialog>` |
+| content | 定义整个弹窗体，包括header、body、footer | `#content` | `<Dialog v-model="visible">
+  <template #content>
+    <!-- 完全自定义弹窗结构 -->
+  </template>
+</Dialog>` |
+| trigger | 自定义触发按钮或触发区域 | `<template #trigger>...</template>` | - |
+
+## 使用示例
+### 受控表单弹窗
+**场景**: 在页面中以受控方式打开一个承载业务表单的弹窗。
+
+通过 v-model 控制弹窗显隐，并在确认时执行异步逻辑。
+
+**使用的 API**: 属性: modelValue, title, ok, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDialog, FormItemInput } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+const name = ref('');
+const handleOk = async () => {
+  console.log('submit', name.value);
+};
+</script>
+
+<template>
+  <button @click="visible = true">新建实例</button>
+  <VDialog v-model="visible" title="新建实例" :ok="handleOk" :hide-trigger="true">
+    <FormItemInput v-model="name" label="实例名称" placeholder="请输入实例名称" />
+  </VDialog>
+</template>
+```
+
+### 使用 trigger 插槽触发确认弹窗
+**场景**: 在操作列或详情页中用自定义按钮触发危险操作确认弹窗。
+
+通过 trigger 插槽自定义入口，用于危险操作前的二次确认。
+
+**使用的 API**: 属性: title, okText, ok
+
+```vue
+<script setup lang="ts">
+import { VDialog } from '@ksyun-internal/versatile';
+
+const handleOk = async () => {
+  console.log('release instance');
+};
+</script>
+
+<template>
+  <VDialog title="释放实例" ok-text="确认释放" :ok="handleOk">
+    <template #trigger>
+      <button>释放实例</button>
+    </template>
+    <div>释放后实例数据将被删除，且不可恢复。</div>
+  </VDialog>
+</template>
+```
+
+## 相关组件
+Dialog, VDrawer, useDialog
+

package/docs_for_llm/vdrawer.doc.md

@@ -0,0 +1,119 @@
+# 业务抽屉 (VDrawer)
+
+在基础 Drawer 之上补充默认触发器、受控显隐和异步确认逻辑的业务抽屉组件，适合编辑长表单和查看侧边详情。
+
+**关键词**: vdrawer, drawer, 业务抽屉, 侧边抽屉, 编辑抽屉, slot drawer
+
+**使用场景**: 侧边表单编辑、详情信息展示、通过按钮触发的抽屉
+
+## 导入语句
+```typescript
+import { VDrawer } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 抽屉标题 | - | - |
+| placement | `"left" | "right" | "top" | "bottom"` | `"right"` | 否 | 抽屉弹出方向 | - | - |
+| size | `string` | `undefined` | 否 | 抽屉尺寸 | - | - |
+| width | `string | number` | `undefined` | 否 | 抽屉宽度 | - | - |
+| loading | `boolean` | `false` | 否 | 确认按钮加载状态 | - | - |
+| disabledOk | `boolean` | `false` | 否 | 是否禁用确认按钮 | - | - |
+| okText | `string` | `"确定"` | 否 | 确认按钮文案 | - | - |
+| cancelText | `string` | `"取消"` | 否 | 取消按钮文案 | - | - |
+| ok | `() => Promise<boolean | void> | boolean | void` | `undefined` | 否 | 确认时的异步处理函数，可返回 false 阻止关闭 | - | - |
+| cancel | `() => void` | `undefined` | 否 | 取消时的回调逻辑 | - | - |
+| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | - | - |
+| overlay | `boolean` | `true` | 否 | 是否显示遮罩层 | - | - |
+| closable | `boolean` | `true` | 否 | 点击遮罩层是否可关闭 | - | - |
+| escClosable | `boolean` | `true` | 否 | 是否允许 ESC 关闭 | - | - |
+| draggable | `boolean` | `false` | 否 | 是否允许拖拽抽屉 | - | - |
+| terminate | `() => void` | `undefined` | 否 | 关闭动作统一回调 | - | - |
+| container | `string | Function` | `undefined` | 否 | 指定抽屉挂载容器 | - | - |
+| mode | `string` | `undefined` | 否 | 抽屉展示模式 | - | - |
+| hideTrigger | `boolean` | `false` | 否 | 隐藏默认 trigger，作为受控抽屉使用 | - | - |
+| modelValue | `boolean | undefined` | `undefined` | 否 | 抽屉显示状态 | - | - |
+| btnProps | `ButtonProps` | `undefined` | 否 | 默认 trigger 按钮属性 | - | - |
+| btnText | `string` | `"打开抽屉"` | 否 | 默认 trigger 按钮文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| open | `@open` | 抽屉打开后触发 | `-` | `<Drawer @open="handleOpen">` |
+| close | `@close` | 抽屉关闭后触发，不管是什么原因导致的关闭 | `-` | `<Drawer @close="handleClose">` |
+| ok | `@ok` | 点击确定按钮时触发 | `-` | `<Drawer @ok="handleOk">` |
+| cancel | `@cancel` | 点击取消按钮时触发 | `-` | `<Drawer @cancel="handleCancel">` |
+| terminate | `@terminate` | 用户强行关闭抽屉时触发（点击关闭按钮、遮罩层或按 ESC） | `-` | `<Drawer @terminate="handleTerminate">` |
+| afterClose | `@afterClose` | 抽屉退出动画执行完成后触发 | `-` | `<Drawer @afterClose="handleAfterClose">` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | 抽屉主体内容区域 | `<VDrawer>...</VDrawer>` | - |
+| header | 自定义抽屉头部 | `<template #header>...</template>` | - |
+| footer | 自定义抽屉底部操作区 | `<template #footer>...</template>` | - |
+| trigger | 自定义触发按钮或触发区域 | `<template #trigger>...</template>` | - |
+
+## 使用示例
+### 侧边编辑抽屉
+**场景**: 在列表页右侧滑出编辑面板，保留用户当前上下文。
+
+用抽屉承载较长的编辑表单，避免打断列表上下文。
+
+**使用的 API**: 属性: modelValue, title, ok, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDrawer, FormItemInput, Description } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+const name = ref('web-prod-01');
+const remark = ref('支付链路核心实例');
+const handleOk = async () => {
+  console.log('save', name.value, remark.value);
+};
+</script>
+
+<template>
+  <button @click="visible = true">编辑实例</button>
+  <VDrawer v-model="visible" title="编辑实例" :ok="handleOk" :hide-trigger="true">
+    <FormItemInput v-model="name" label="实例名称" />
+    <Description v-model="remark" />
+  </VDrawer>
+</template>
+```
+
+### 使用 trigger 和 footer 插槽自定义抽屉
+**场景**: 在详情预览场景下通过自定义触发器和底部按钮扩展抽屉交互。
+
+通过 trigger 和 footer 插槽自定义抽屉打开方式和底部操作区。
+
+**使用的 API**: 属性: modelValue, title, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDrawer } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+</script>
+
+<template>
+  <VDrawer v-model="visible" title="实例详情" :hide-trigger="false">
+    <template #trigger>
+      <button>查看详情</button>
+    </template>
+    <div>这里可以放详情摘要、监控图表或操作记录。</div>
+    <template #footer>
+      <button @click="visible = false">关闭</button>
+      <button>导出详情</button>
+    </template>
+  </VDrawer>
+</template>
+```
+
+## 相关组件
+Drawer, VDialog
+

package/docs_for_llm/virtuallist.doc.md

@@ -12,9 +12,9 @@ import { VirtualList } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| disabled | `boolean` | `false` | 否 | 是否禁用虚拟化，禁用后会渲染所有元素 | `<VirtualList disabled></VirtualList>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| disabled | `boolean` | `false` | 否 | 是否禁用虚拟化，禁用后会渲染所有元素 | - | `<VirtualList disabled></VirtualList>` |
 
 ## 子组件 (Sub-Components)
 ### VirtualListContainer
@@ -34,6 +34,7 @@ import { VirtualList } from '@king-design/vue';
 行渲染组件，包裹实际渲染的列表项
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 容器未设置高度
 > **错误用法**: `<VirtualList> <!-- 没有高度，无法滚动 -->
   <div v-for="item in data" :key="item.value">...</div>
 </VirtualList>`
@@ -42,10 +43,12 @@ import { VirtualList } from '@king-design/vue';
 </VirtualList>`
 > **说明**: VirtualList 容器必须设置固定高度才能正常工作
 
+### 列表项缺少 key
 > **错误用法**: `<div v-for="item in data">{{ item.label }}</div>`
 > **正确写法**: `<div v-for="item in data" :key="item.value">{{ item.label }}</div>`
 > **说明**: 每个列表项必须设置唯一的 key 以确保正确渲染
 
+### 数据量较小时启用虚拟化
 > **错误用法**: `const data = [1, 2, 3]; // 只有 3 条数据
 <VirtualList>...</VirtualList>`
 > **正确写法**: `const data = [1, 2, 3];