king-design-analyzer 2.1.9 → 2.2.1

package/docs_for_llm/drawer.doc.md

@@ -12,108 +12,153 @@ import { Drawer } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `boolean` | `false` | 否 | 抽屉是否展示，可用 v-model 双向绑定 | `<Drawer v-model="visible"></Drawer>` |
-| title | `string` | `"提示"` | 否 | 抽屉标题 | `<Drawer title="抽屉标题"></Drawer>` |
-| placement | `"top" | "bottom" | "left" | "right"` | `"right"` | 否 | 抽屉弹出的位置 | `<Drawer placement="left"></Drawer>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 抽屉尺寸 | `<Drawer size="large"></Drawer>` |
-| width | `number | string` | `undefined` | 否 | 指定抽屉宽度，number 类型时单位为 px，string 类型需指定单位 | `<Drawer :width="500"></Drawer>` |
-| loading | `boolean` | `false` | 否 | "确定"按钮是否为加载状态 | `<Drawer :loading="isSubmitting"></Drawer>` |
-| disabledOk | `boolean` | `false` | 否 | "确定"按钮是否为禁用状态 | `<Drawer :disabledOk="!isFormValid"></Drawer>` |
-| okText | `string` | `"确定"` | 否 | "确定"按钮文案 | `<Drawer okText="保存"></Drawer>` |
-| cancelText | `string` | `"取消"` | 否 | "取消"按钮文案 | `<Drawer cancelText="关闭"></Drawer>` |
-| ok | `() => void` | `undefined` | 否 | "确定"按钮点击后自定义回调函数 | `<Drawer :ok="handleOk"></Drawer>` |
-| cancel | `() => void` | `undefined` | 否 | "取消"按钮点击后自定义回调函数 | `<Drawer :cancel="handleCancel"></Drawer>` |
-| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | `<Drawer hideClose></Drawer>` |
-| overlay | `boolean` | `true` | 否 | 是否展示遮罩层 | `<Drawer :overlay="false"></Drawer>` |
-| closable | `boolean` | `true` | 否 | 点击遮罩层是否可以关闭抽屉 | `<Drawer :closable="false"></Drawer>` |
-| escClosable | `boolean` | `true` | 否 | 是否按 ESC 键时关闭抽屉 | `<Drawer :escClosable="false"></Drawer>` |
-| terminate | `() => void` | `undefined` | 否 | 用户点击关闭按钮、遮罩层或按 ESC 键时的回调函数 | `<Drawer :terminate="handleTerminate"></Drawer>` |
-| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定抽屉插入的位置，默认追加到 body | `<Drawer :container="() => document.body"></Drawer>` |
-| mode | `"destroy" | "hide"` | `"hide"` | 否 | 指定关闭状态下的渲染方式 | `<Drawer mode="destroy"></Drawer>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `boolean` | `false` | 否 | 抽屉是否展示，可用 v-model 双向绑定 | - | `<Drawer v-model="visible">` |
+| title | `string` | `"提示"` | 否 | 抽屉标题 | - | `<Drawer title="抽屉标题">` |
+| placement | `"top" | "bottom" | "left" | "right"` | `"right"` | 否 | 抽屉弹出的位置 | - | `<Drawer placement="left">` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 抽屉尺寸 | - | `<Drawer size="large">` |
+| width | `number | string` | `undefined` | 否 | 指定抽屉宽度，number 类型时单位为 px，string 类型需指定单位 | - | `<Drawer :width="500">` |
+| loading | `boolean` | `false` | 否 | "确定"按钮是否为加载状态 | - | `<Drawer :loading="isSubmitting">` |
+| disabledOk | `boolean` | `false` | 否 | "确定"按钮是否为禁用状态 | - | `<Drawer :disabledOk="!isFormValid">` |
+| okText | `string` | `"确定"` | 否 | "确定"按钮文案 | - | `<Drawer okText="保存">` |
+| cancelText | `string` | `"取消"` | 否 | "取消"按钮文案 | - | `<Drawer cancelText="关闭">` |
+| ok | `() => void` | `undefined` | 否 | "确定"按钮点击后自定义回调函数 | - | `<Drawer :ok="handleOk">` |
+| cancel | `() => void` | `undefined` | 否 | "取消"按钮点击后自定义回调函数 | - | `<Drawer :cancel="handleCancel">` |
+| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | - | `<Drawer hideClose>` |
+| overlay | `boolean` | `true` | 否 | 是否展示遮罩层 | - | `<Drawer :overlay="false">` |
+| closable | `boolean` | `true` | 否 | 点击遮罩层是否可以关闭抽屉 | - | `<Drawer :closable="false">` |
+| escClosable | `boolean` | `true` | 否 | 是否按 ESC 键时关闭抽屉 | - | `<Drawer :escClosable="false">` |
+| draggable | `boolean` | `true` | 否 | 抽屉是否可拖拽 | - | `<Drawer :draggable="false">` |
+| terminate | `() => void` | `undefined` | 否 | 用户点击关闭按钮、遮罩层或按 ESC 键时的回调函数 | - | `<Drawer :terminate="handleTerminate">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定抽屉插入的位置，默认追加到 body | - | `<Drawer :container="() => document.body">` |
+| mode | `"destroy" | "hide"` | `"hide"` | 否 | 指定关闭状态下的渲染方式 | - | `<Drawer mode="destroy">` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| open | `@open` | 抽屉打开后触发 | `-` | `<Drawer @open="handleOpen"></Drawer>` |
-| close | `@close` | 抽屉关闭后触发，不管是什么原因导致的关闭 | `-` | `<Drawer @close="handleClose"></Drawer>` |
-| ok | `@ok` | 点击确定按钮时触发 | `-` | `<Drawer @ok="handleOk"></Drawer>` |
-| cancel | `@cancel` | 点击取消按钮时触发 | `-` | `<Drawer @cancel="handleCancel"></Drawer>` |
-| terminate | `@terminate` | 用户强行关闭抽屉时触发（点击关闭按钮、遮罩层或按 ESC） | `-` | `<Drawer @terminate="handleTerminate"></Drawer>` |
-| afterClose | `@afterClose` | 抽屉退出动画执行完成后触发 | `-` | `<Drawer @afterClose="handleAfterClose"></Drawer>` |
-
-### 事件处理函数示例
-**open**:
+| 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)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| content | 定义整个弹窗体，包括header，body，footer | `#content` | `<Drawer>
+  <template #content>自定义内容</template>
+</Drawer>` |
+| header | 扩展弹窗头部 | `#header` | `<Drawer>
+  <template #header>头部内容</template>
+</Drawer>` |
+| body | 扩展弹窗主体部分 | `#body` | `<Drawer>
+  <template #body>
+    自定义body内容
+  </template>
+</Drawer>` |
+| footer | 扩展弹窗底部 | `#footer` | `<Drawer>
+  <template #footer>底部内容</template>
+</Drawer>` |
+| footer-wrapper | 扩展弹窗整个底部，上述footer是它下面一个子扩展点 | `#footer-wrapper` | `<Drawer>
+  <template #footer-wrapper>
+    自定义footer-wrapper内容
+  </template>
+</Drawer>` |
+
+### 插槽参数说明
+**content**
+
+- 参数结构: 无参数
+
+**header**
+
+- 参数结构: 无参数
+
+**body**
+
+- 参数结构: 无参数
+
+**footer**
+
+- 参数结构: 无参数
+
+**footer-wrapper**
+
+- 参数结构: 无参数
+
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| show | 弹出抽屉 | `props?: DrawerProps` | `Promise` |
+| close | 关闭抽屉 | `-` | `void` |
+| showLoading | "确定"按钮变为加载状态 | `-` | `void` |
+| hideLoading | "确定"按钮变为正常状态 | `-` | `void` |
+| disableOk | "确定"按钮变为禁用状态 | `-` | `void` |
+| enableOk | "确定"按钮变为正常状态 | `-` | `void` |
+
+### 方法参数说明
+**show**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| props | `DrawerProps` | 否 | - | 可选的临时抽屉配置，会在本次显示时覆盖标题、方向、宽度或按钮状态。 |
+
+调用示例:
 ```typescript
-const handleOpen = () => {
-  console.log('抽屉已打开');
-};
+drawerRef.value?.show();
 ```
 
-**close**:
+### 方法调用示例
+**show**
+
 ```typescript
-const handleClose = () => {
-  console.log('抽屉已关闭');
-};
+drawerRef.value?.show();
 ```
 
-**ok**:
+**close**
+
 ```typescript
-const handleOk = () => {
-  console.log('点击了确定');
-};
+drawerRef.value?.close();
 ```
 
-**cancel**:
+**showLoading**
+
 ```typescript
-const handleCancel = () => {
-  console.log('点击了取消');
-};
+drawerRef.value?.showLoading();
 ```
 
-**terminate**:
+**hideLoading**
+
 ```typescript
-const handleTerminate = () => {
-  console.log('用户强行关闭');
-};
+drawerRef.value?.hideLoading();
 ```
 
-**afterClose**:
+**disableOk**
+
 ```typescript
-const handleAfterClose = () => {
-  console.log('动画完成');
-};
+drawerRef.value?.disableOk();
 ```
 
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
-| --- | --- | --- | --- |
-| content | 定义整个弹窗体，包括header，body，footer | `undefined` | - |
-| header | 扩展弹窗头部 | `undefined` | - |
-| body | 扩展弹窗主体部分 | `undefined` | - |
-| footer | 扩展弹窗底部 | `undefined` | - |
-| footer-wrapper | 扩展弹窗整个底部，上述footer是它下面一个子扩展点 | `undefined` | - |
+**enableOk**
 
-## 方法 (Methods)
-| 方法名 | 说明 | 参数 | 返回值 |
-| --- | --- | --- | --- |
-| show | 弹出抽屉 | `` | `Promise` |
-| close | 关闭抽屉 | `` | `void` |
-| showLoading | "确定"按钮变为加载状态 | `` | `void` |
-| hideLoading | "确定"按钮变为正常状态 | `` | `void` |
-| disableOk | "确定"按钮变为禁用状态 | `` | `void` |
-| enableOk | "确定"按钮变为正常状态 | `` | `void` |
+```typescript
+drawerRef.value?.enableOk();
+```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### placement 值拼写错误
 > **错误用法**: `<Drawer placement="center">`
 > **正确写法**: `<Drawer placement="right">`
 > **说明**: placement 只支持 top, bottom, left, right，不存在 center 值
 
+### 使用错误的 v-model 属性名
 > **错误用法**: `<Drawer v-model:visible="visible">`
 > **正确写法**: `<Drawer v-model="visible">`
 > **说明**: Drawer 使用 v-model 控制显示状态，不是 v-model:visible
 
+### 混淆 closable 和 hideClose
 > **错误用法**: `<Drawer :closable="true"> <!-- 想隐藏关闭按钮 -->`
 > **正确写法**: `<Drawer hideClose> <!-- 隐藏关闭按钮 -->
 <Drawer :closable="false"> <!-- 禁止点击遮罩关闭 -->`

package/docs_for_llm/dropdown.doc.md

@@ -12,54 +12,320 @@ import { Dropdown, DropdownMenu, DropdownItem } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| trigger | `"hover" | "click" | "contextmenu" | "focus"` | `"hover"` | 否 | 触发方式 | `<Dropdown trigger="click"></Dropdown>` |
-| value | `boolean` | `false` | 否 | 是否展示菜单，可用 v-model 双向绑定 | `<Dropdown v-model="visible"></Dropdown>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用整个菜单 | `<Dropdown disabled></Dropdown>` |
-| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | `<Dropdown position="right"></Dropdown>` |
-| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是触发元素所在的菜单元素 | `<Dropdown of="parent"></Dropdown>` |
-| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认追加到 body | `<Dropdown :container="() => document.body"></Dropdown>` |
-| alwaysShowOnClick | `boolean` | `false` | 否 | 不管什么触发方式，重复点击触发器都不隐藏弹层 | `<Dropdown alwaysShowOnClick></Dropdown>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| trigger | `"hover" | "click" | "contextmenu" | "focus"` | `"hover"` | 否 | 触发方式 | - | `<Dropdown trigger="click">` |
+| value | `boolean` | `false` | 否 | 是否展示菜单，可用 v-model 双向绑定 | - | `<Dropdown v-model="visible">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用整个菜单 | - | `<Dropdown disabled>` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | - | `<Dropdown position="right">` |
+| collison | `Collision | [Collision, Collision]` | `undefined` | 否 | 碰撞检测策略，控制弹层超出边界时的处理方式。注意源码字段名拼写为 collison。 | - | `<Dropdown :collison="'flipfit'">` |
+| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是触发元素所在的菜单元素 | - | `<Dropdown of="parent">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认追加到 body | - | `<Dropdown :container="() => document.body">` |
+| alwaysShowOnClick | `boolean` | `false` | 否 | 不管什么触发方式，重复点击触发器都不隐藏弹层 | - | `<Dropdown alwaysShowOnClick>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| show | `@show` | 菜单展示时触发 | `-` | `<Dropdown @show="handleShow"></Dropdown>` |
-| hide | `@hide` | 菜单隐藏时触发 | `-` | `<Dropdown @hide="handleHide"></Dropdown>` |
+| show | `@show` | 菜单展示时触发 | `-` | `<Dropdown @show="handleShow">` |
+| hide | `@hide` | 菜单隐藏时触发 | `-` | `<Dropdown @hide="handleHide">` |
+| positioned | `@positioned` | 下拉菜单完成定位计算后触发，可用于读取最终落位方向和坐标。 | `feedback: Feedback` | `<Dropdown @positioned="handlePositioned">` |
 
-### 事件处理函数示例
-**show**:
+### 事件参数说明
+**positioned**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| feedback | `Feedback` | 是 | - | 定位反馈对象，描述当前菜单的最终 placement 和坐标信息。 |
+
+事件处理示例:
 ```typescript
-const handleShow = () => {
-  console.log('菜单已展示');
+const handlePositioned = (feedback: Feedback) => {
+  console.log('最终位置', feedback.placement);
 };
 ```
 
-**hide**:
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| show | 主动展开下拉菜单。 | `shouldFocus?: boolean` | `void` |
+| hide | 主动隐藏下拉菜单。 | `immediately?: boolean` | `void` |
+| focusFirst | 把焦点移动到菜单中的第一个可聚焦项。 | `-` | `void` |
+| position | 重新计算当前下拉菜单的位置。 | `callback?: (feedback: Feedback) => void` | `void` |
+
+### 方法参数说明
+**show**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| shouldFocus | `boolean` | 否 | - | 展开后是否尝试把焦点移动到菜单内容，用于键盘可访问性场景。 |
+
+调用示例:
 ```typescript
-const handleHide = () => {
-  console.log('菜单已隐藏');
-};
+dropdownRef.value?.show(true);
+```
+
+**hide**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| immediately | `boolean` | 否 | - | 是否立即隐藏并跳过延迟关闭逻辑。 |
+
+调用示例:
+```typescript
+dropdownRef.value?.hide(true);
+```
+
+**position**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| callback | `(feedback: Feedback) => void` | 否 | - | 定位完成后的回调，可读取最终 placement 和坐标。 |
+
+调用示例:
+```typescript
+dropdownRef.value?.position((feedback) => console.log(feedback.placement));
+```
+
+### 方法调用示例
+**show**
+
+```typescript
+dropdownRef.value?.show(true);
+```
+
+**hide**
+
+```typescript
+dropdownRef.value?.hide(true);
+```
+
+**focusFirst**
+
+```typescript
+dropdownRef.value?.focusFirst();
+```
+
+**position**
+
+```typescript
+dropdownRef.value?.position((feedback) => console.log(feedback.placement));
 ```
 
 ## 子组件 (Sub-Components)
 ### DropdownMenu
 下拉菜单容器，用于包裹菜单项
 
+#### 组合示例
+##### 嵌套菜单
+**场景**: 创建多级嵌套的下拉菜单
+
+多级嵌套的下拉菜单
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';
+</script>
+<template>
+  <Dropdown>
+    <Button>嵌套菜单</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem>菜单项1</DropdownItem>
+        <Dropdown position="right">
+          <DropdownItem>更多 ></DropdownItem>
+          <template #menu>
+            <DropdownMenu>
+              <DropdownItem>子菜单1</DropdownItem>
+              <DropdownItem>子菜单2</DropdownItem>
+            </DropdownMenu>
+          </template>
+        </Dropdown>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
+##### 基础用法
+**场景**: 创建一个悬停触发的下拉菜单
+
+基本的下拉菜单，悬停触发
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';
+</script>
+<template>
+  <Dropdown>
+    <Button>下拉菜单</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem>菜单项1</DropdownItem>
+        <DropdownItem>菜单项2</DropdownItem>
+        <DropdownItem>菜单项3</DropdownItem>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
+##### 点击触发
+**场景**: 创建点击触发的下拉菜单
+
+点击触发的下拉菜单
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';
+</script>
+<template>
+  <Dropdown trigger="click">
+    <Button>点击展开</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem>菜单项1</DropdownItem>
+        <DropdownItem>菜单项2</DropdownItem>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
 ### DropdownItem
 下拉菜单项组件
 
+#### 属性 (Props)
 | 属性名 | 类型 | 说明 | 示例 |
 | --- | --- | --- | --- |
 | disabled | `boolean` | 是否禁用该菜单项 | `<DropdownItem disabled>禁用项</DropdownItem>` |
 | hideOnSelect | `boolean` | 选中该菜单后是否隐藏整个菜单 | `<DropdownItem :hideOnSelect="false">选中不关闭</DropdownItem>` |
 
-**事件**:
-- `@select`: 菜单项被选中时触发（点击或键盘操作）
-- `@click`: 菜单项被点击时触发
+#### 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| select | `@select` | 菜单项被选中时触发（点击或键盘操作） | `item: DropdownItem` | `<DropdownItem @select="handleActionSelect">查看详情</DropdownItem>` |
+| click | `@click` | 菜单项被点击时触发 | `e: MouseEvent` | `<DropdownItem @click="recordMenuClick">下载日志</DropdownItem>` |
+
+##### DropdownItem 事件参数说明
+**select**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| item | `DropdownItem` | 是 | - | 被选中的菜单项实例 |
+
+事件处理示例:
+```typescript
+const selectedAction = ref('');
+const selectedItem = ref(null);
+
+const handleActionSelect = (item) => {
+  selectedAction.value = 'detail';
+  selectedItem.value = item;
+};
+```
+
+**click**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件 |
+
+事件处理示例:
+```typescript
+const lastPointer = ref({ x: 0, y: 0 });
+
+const recordMenuClick = (e: MouseEvent) => {
+  lastPointer.value = { x: e.clientX, y: e.clientY };
+};
+```
+
+#### 组合示例
+##### 禁用菜单项
+**场景**: 禁用特定的菜单项
+
+禁用特定的菜单项
+
+**命中的子组件 API**: 属性: disabled
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button } from '@king-design/vue';
+</script>
+<template>
+  <Dropdown>
+    <Button>下拉菜单</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem>可用项</DropdownItem>
+        <DropdownItem disabled>禁用项</DropdownItem>
+        <DropdownItem>可用项</DropdownItem>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
+##### 监听选择事件
+**场景**: 监听菜单项点击并执行操作
+
+监听菜单项的选择
+
+**命中的子组件 API**: 事件: click
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button, Message } from '@king-design/vue';
+
+const handleClick = (action: string) => {
+  Message.info(`选择了: ${action}`);
+};
+</script>
+<template>
+  <Dropdown>
+    <Button>操作</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem @click="handleClick('编辑')">编辑</DropdownItem>
+        <DropdownItem @click="handleClick('复制')">复制</DropdownItem>
+        <DropdownItem @click="handleClick('删除')">删除</DropdownItem>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
+
+##### 表格操作列
+**场景**: 在表格操作列中使用下拉菜单
+
+在表格中使用下拉菜单作为操作列
+
+**命中的子组件 API**: 事件: click
+
+```vue
+<script setup lang="ts">
+import { Dropdown, DropdownMenu, DropdownItem, Button, Message } from '@king-design/vue';
+
+const handleAction = (action: string, id: number) => {
+  Message.info(`对 ID=${id} 执行 ${action}`);
+};
+</script>
+<template>
+  <!-- 假设在表格的操作列中 -->
+  <Dropdown trigger="click">
+    <Button type="link" size="small">操作</Button>
+    <template #menu>
+      <DropdownMenu>
+        <DropdownItem @click="handleAction('查看', 1)">查看</DropdownItem>
+        <DropdownItem @click="handleAction('编辑', 1)">编辑</DropdownItem>
+        <DropdownItem @click="handleAction('删除', 1)">删除</DropdownItem>
+      </DropdownMenu>
+    </template>
+  </Dropdown>
+</template>
+```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 未使用 #menu 插槽
 > **错误用法**: `<Dropdown>
   <Button>菜单</Button>
   <DropdownMenu>
@@ -76,10 +342,12 @@ const handleHide = () => {
 </Dropdown>`
 > **说明**: DropdownMenu 必须放在 #menu 插槽中
 
+### trigger 值拼写错误
 > **错误用法**: `<Dropdown trigger="rightclick">`
 > **正确写法**: `<Dropdown trigger="contextmenu">`
 > **说明**: 右键触发应使用 contextmenu，不是 rightclick
 
+### DropdownItem 未放在 DropdownMenu 中
 > **错误用法**: `<Dropdown>
   <Button>菜单</Button>
   <template #menu>

package/docs_for_llm/duration.doc.md

@@ -0,0 +1,76 @@
+# 时长选择 (Duration)
+
+用于购买、续费和策略配置场景的时长选择器，支持按月或按小时切换，并可配合内置刻度快速选择常用周期。
+
+**关键词**: duration, period, 时长选择, 购买时长, 按小时时长, 续费周期
+
+**使用场景**: 购买链路时长选择、资源续费时长选择、按小时设置临时资源周期
+
+## 导入语句
+```typescript
+import { Duration } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `number` | `undefined` | 否 | 当前选中的时长值 | - | - |
+| marksType | `string` | `"month"` | 否 | 刻度类型，控制内置 marks 的生成方式 | - | - |
+| type | `string` | `"month"` | 否 | 时长类型，通常为 month 或 hour | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 用户选择新的时长后触发，通常用于联动价格或到期时间计算。 | `value?: number` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number` | 否 | - | 当前选中的时长值。 |
+
+## 使用示例
+### 续费时长选择
+**场景**: 在购买或续费流程中选择资源有效时长。
+
+按月展示常用刻度，并把结果同步到续费表单。
+
+**使用的 API**: 属性: modelValue, type, marksType | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Duration } from '@ksyun-internal/versatile';
+
+const duration = ref(3);
+</script>
+
+<template>
+  <Duration v-model="duration" type="month" marks-type="month" />
+</template>
+```
+
+### 按小时选择时长
+**场景**: 在临时测试机或弹性资源场景中按小时设置有效时长。
+
+在临时资源场景中切换到按小时的时长选择。
+
+**使用的 API**: 属性: modelValue, type, marksType | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Duration } from '@ksyun-internal/versatile';
+
+const duration = ref(12);
+</script>
+
+<template>
+  <Duration v-model="duration" type="hour" marks-type="hour" />
+</template>
+```
+
+## 相关组件
+Slider, TimeRange
+