king-design-analyzer 2.1.7 → 2.2.0

package/docs_for_llm/timepicker.doc.md

@@ -12,26 +12,36 @@ import { Timepicker } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `Value | Value[] | [Value, Value] | [Value, Value][]` | `""` | 否 | 当前选中的时间，可用 v-model 双向绑定。范围选择时为 [Value, Value] | `<Timepicker v-model="time" />` |
-| range | `boolean` | `false` | 否 | 是否选择时间范围 | `<Timepicker range />` |
-| multiple | `boolean` | `false` | 否 | 是否支持多选 | `<Timepicker multiple />` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 | `<Timepicker disabled />` |
-| clearable | `boolean` | `false` | 否 | 是否可清空 | `<Timepicker clearable />` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `<Timepicker size="small" />` |
-| placeholder | `string` | `"请选择时间"` | 否 | 占位文案 | `<Timepicker placeholder="选择开始时间" />` |
-| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 时间格式化字符串 | `<Timepicker format="HH:mm" />` |
-| valueFormat | `string` | `undefined` | 否 | value 值的格式化字符串 | `<Timepicker valueFormat="HH:mm:ss" />` |
-| showFormat | `string` | `undefined` | 否 | 展示的格式化字符串 | `<Timepicker showFormat="HH时mm分" />` |
-| step | `string` | `undefined` | 否 | 固定时间点的步长，如 "00:30" 表示每 30 分钟一个选项 | `<Timepicker step="00:30" />` |
-| min | `Value` | `undefined` | 否 | 最小可选时间 | `<Timepicker min="09:00:00" />` |
-| max | `Value` | `undefined` | 否 | 最大可选时间 | `<Timepicker max="18:00:00" />` |
-| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | `<Timepicker hideIcon />` |
-| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `<Timepicker fluid />` |
-| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `<Timepicker inline />` |
-| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `<Timepicker flat />` |
-| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | `<Timepicker :width="150" />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `Value | Value[] | [Value, Value] | [Value, Value][]` | `""` | 否 | 当前选中的时间，可用 v-model 双向绑定。范围选择时为 [Value, Value] | - | `<Timepicker v-model="time" />` |
+| range | `boolean` | `false` | 否 | 是否选择时间范围 | - | `<Timepicker range />` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | - | `<Timepicker multiple />` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选输入 | - | `<Timepicker filterable />` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | - | `<Timepicker :loading="loading" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | - | `<Timepicker disabled />` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | - | `<Timepicker name="startTime" />` |
+| clearable | `boolean` | `false` | 否 | 是否可清空 | - | `<Timepicker clearable />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | - | `<Timepicker size="small" />` |
+| placeholder | `string` | `"请选择时间"` | 否 | 占位文案 | - | `<Timepicker placeholder="选择开始时间" />` |
+| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 时间格式化字符串 | - | `<Timepicker format="HH:mm" />` |
+| valueFormat | `string` | `undefined` | 否 | value 值的格式化字符串 | - | `<Timepicker valueFormat="HH:mm:ss" />` |
+| showFormat | `string` | `undefined` | 否 | 展示的格式化字符串 | - | `<Timepicker showFormat="HH时mm分" />` |
+| step | `string` | `undefined` | 否 | 固定时间点的步长，如 "00:30" 表示每 30 分钟一个选项 | - | `<Timepicker step="00:30" />` |
+| min | `Value` | `undefined` | 否 | 最小可选时间 | - | `<Timepicker min="09:00:00" />` |
+| max | `Value` | `undefined` | 否 | 最大可选时间 | - | `<Timepicker max="18:00:00" />` |
+| disabledDate | `(v: Dayjs) => boolean` | `undefined` | 否 | 禁用日期的函数，返回 true 表示禁用该日期 | - | `<Timepicker :disabledDate="(d) => d.day() === 0" />` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | - | `<Timepicker hideIcon />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | - | `<Timepicker fluid />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | - | `<Timepicker inline />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | - | `<Timepicker flat />` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | - | `<Timepicker :width="150" />` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | - | `<Timepicker :container="() => document.body" />` |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | - | `<Timepicker :show="visible" />` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | - | `<Timepicker position="top" />` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | - | `<Timepicker nowrap />` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | - | `<Timepicker multiple draggable />` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | - | `<Timepicker virtual />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
@@ -39,48 +49,57 @@ import { Timepicker } from '@king-design/vue';
 | show | `@show` | 菜单弹出时触发 | `-` | `<Timepicker @show="handleShow" />` |
 | hide | `@hide` | 菜单隐藏时触发 | `-` | `<Timepicker @hide="handleHide" />` |
 | change | `@change` | 用户操作完成且值变化时触发 | `value: string` | `<Timepicker @change="handleChange" />` |
-| selecting | `@selecting` | 范围选择时，用户正在操作选择时触发 | `value: [Dayjs, Dayjs?]` | `<Timepicker range @selecting="handleSelecting" />` |
+| selecting | `@selecting` | 范围选择时，用户正在操作选择时触发 | `value: [Dayjs, Dayjs?], confirmed: boolean` | `<Timepicker range @selecting="handleSelecting" />` |
 
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('时间选择器已打开');
-};
-```
+### 事件参数说明
+**change**
 
-**hide**:
-```typescript
-const handleHide = () => {
-  console.log('时间选择器已关闭');
-};
-```
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前选择的时间值 |
 
-**change**:
+事件处理示例:
 ```typescript
 const handleChange = (value: string) => {
   console.log('选择的时间:', value);
 };
 ```
 
-**selecting**:
+**selecting**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `[Dayjs, Dayjs?]` | 是 | - | 当前选择的值 |
+| confirmed | `boolean` | 是 | - | 当前这次 selecting 是否已经进入确认完成态；常见交互过程中通常为 `false`。 |
+
+事件处理示例:
 ```typescript
-const handleSelecting = (value) => {
-  console.log('正在选择:', value);
+const handleSelecting = (value, confirmed) => {
+  console.log('正在选择:', value, confirmed);
 };
 ```
 
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| show | 主动展开时间选择面板。 | `-` | `void` |
+| hide | 主动关闭时间选择面板。 | `-` | `void` |
+| position | 重新计算时间选择面板的位置。 | `-` | `void` |
+
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 范围选择时 value 类型错误
 > **错误用法**: `const time = ref('');
 <Timepicker v-model="time" range />`
 > **正确写法**: `const timeRange = ref<[string, string]>(['', '']);
 <Timepicker v-model="timeRange" range />`
 > **说明**: 当 range 为 true 时，value 必须是 [string, string] 数组
 
+### step 格式错误
 > **错误用法**: `<Timepicker step="30" /> <!-- 期望 30 分钟 -->`
 > **正确写法**: `<Timepicker step="00:30" />`
 > **说明**: step 应使用时间格式字符串，如 "00:30" 表示 30 分钟
 
+### min/max 格式与 format 不匹配
 > **错误用法**: `<Timepicker min="9:00" max="18:00" /> <!-- 缺少秒 -->`
 > **正确写法**: `<Timepicker min="09:00:00" max="18:00:00" />`
 > **说明**: min/max 应使用完整的时间格式

package/docs_for_llm/timerange.doc.md

@@ -0,0 +1,157 @@
+# 时间范围 (TimeRange)
+
+面向报表、监控和日志场景的时间范围选择组件，支持快捷区间、自定义起止时间以及时间戳格式输出。
+
+**关键词**: time range, date range, time filter, 时间范围, 时间筛选, 快捷时间, 监控时间段, 日志时间查询
+
+**使用场景**: 监控页时间筛选、报表页时间范围选择、日志页最近时间窗口查询、按快捷区间切换统计周期
+
+## 导入语句
+```typescript
+import { TimeRange } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `"date" | "datetime" | "year" | "month"` | `"date"` | 否 | 组件类型 | `inherited:Datepicker` | `<Datepicker type="datetime" />` |
+| range | `boolean` | `false` | 否 | 是否选择日期范围 | `inherited:Datepicker` | `<Datepicker range />` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | `inherited:Datepicker` | `<Datepicker multiple />` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选输入 | `inherited:Datepicker` | `<Datepicker filterable />` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | `inherited:Datepicker` | `<Datepicker :loading="loading" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Datepicker` | `<Datepicker disabled />` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | `inherited:Datepicker` | `<Datepicker name="startDate" />` |
+| clearable | `boolean` | `false` | 否 | 是否可清空 | `inherited:Datepicker` | `<Datepicker clearable />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Datepicker` | `<Datepicker size="small" />` |
+| placeholder | `string` | `"请选择日期"` | 否 | 占位文案 | `inherited:Datepicker` | `<Datepicker placeholder="选择开始日期" />` |
+| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 日期格式化字符串 | - | - |
+| valueFormat | `string` | `undefined` | 否 | value 值的日期格式化字符串 | `inherited:Datepicker` | `<Datepicker valueFormat="YYYY-MM-DD" />` |
+| showFormat | `string` | `undefined` | 否 | 展示的日期格式化字符串 | `inherited:Datepicker` | `<Datepicker showFormat="YYYY年MM月DD日" />` |
+| min | `Value` | `undefined` | 否 | 最小可选日期 | `inherited:Datepicker` | `<Datepicker min="2024-01-01" />` |
+| max | `Value` | `undefined` | 否 | 最大可选日期 | `inherited:Datepicker` | `<Datepicker max="2024-12-31" />` |
+| disabledDate | `(v: Dayjs) => boolean` | `undefined` | 否 | 禁用日期的函数，返回 true 表示禁用该日期 | `inherited:Datepicker` | `<Datepicker :disabledDate="(d) => d.day() === 0" />` |
+| shortcuts | `Shortcut[]` | `undefined` | 否 | 快捷方式配置 | `inherited:Datepicker` | `<Datepicker :shortcuts="shortcuts" />` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | `inherited:Datepicker` | `<Datepicker hideIcon />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Datepicker` | `<Datepicker fluid />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `inherited:Datepicker` | `<Datepicker inline />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Datepicker` | `<Datepicker flat />` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | `inherited:Datepicker` | `<Datepicker :width="200" />` |
+| container | `Container` | `undefined` | 否 | 弹出层挂载容器 | - | - |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | `inherited:Datepicker` | `<Datepicker :show="visible" />` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | `inherited:Datepicker` | `<Datepicker position="top" />` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | `inherited:Datepicker` | `<Datepicker nowrap />` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | `inherited:Datepicker` | `<Datepicker multiple draggable />` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | `inherited:Datepicker` | `<Datepicker virtual />` |
+| modelValue | `[number, number] | [string, string]` | `undefined` | 否 | 当前选中的时间范围 | - | - |
+| startTime | `string | number` | `undefined` | 否 | 当前时间范围的开始时间 | - | - |
+| endTime | `string | number` | `undefined` | 否 | 当前时间范围的结束时间 | - | - |
+| label | `string` | `""` | 否 | 组件标题文案 | - | - |
+| times | `(Time | number | 'today' | 'yesterday')[]` | `undefined` | 否 | 快捷时间范围配置，支持分钟数或 today / yesterday 等枚举 | - | - |
+| defaultValue | `number | 'today' | 'yesterday'` | `undefined` | 否 | 首次渲染时使用的默认快捷值 | - | - |
+| timestamp | `boolean` | `false` | 否 | 是否以时间戳格式返回值 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 整个时间范围值变化时触发，适合直接驱动查询参数。 | `value?: TimeModelType` | - |
+| update:startTime | `@update:startTime` | 开始时间变化时触发，可用于单独记录查询区间起点。 | `value?: string | number` | - |
+| update:endTime | `@update:endTime` | 结束时间变化时触发，可用于单独记录查询区间终点。 | `value?: string | number` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `TimeModelType` | 否 | - | 当前完整时间范围，可能是时间戳元组或格式化后的字符串元组。 |
+
+**update:startTime**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | number` | 否 | - | 当前开始时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。 |
+
+**update:endTime**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | number` | 否 | - | 当前结束时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。 |
+
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| setTimeValue | 按快捷值主动切换时间范围 | `value: number | 'today' | 'yesterday'` | `void` |
+| refetch | 刷新当前时间范围到最新时间 | `value?: number | 'today' | 'yesterday'` | `void` |
+
+### 方法参数说明
+**setTimeValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | 'today' | 'yesterday'` | 是 | - | 目标快捷值，可传分钟数或 `today`、`yesterday` 这类内置快捷标识。 |
+
+**refetch**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | 'today' | 'yesterday'` | 否 | - | 可选的快捷值；传入后会先切换到该快捷区间，再把结束时间刷新到当前最新时刻。 |
+
+## 使用示例
+### 监控页时间筛选
+**场景**: 在监控和报表页面中切换查询时间范围。
+
+提供最近 1 小时、最近 24 小时等快捷时间范围。
+
+**使用的 API**: 属性: modelValue, label, times, timestamp | 事件: update:modelValue, update:startTime, update:endTime
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimeRange } from '@ksyun-internal/versatile';
+
+const timeRange = ref<[number, number] | undefined>();
+</script>
+
+<template>
+  <TimeRange
+    v-model="timeRange"
+    label="统计周期"
+    :times="[60, 360, 'today']"
+    :timestamp="true"
+  />
+</template>
+```
+
+### 刷新到最新时间窗口
+**场景**: 在日志和监控页面中一键把查询区间重置到最新时间窗口。
+
+通过组件方法把当前时间范围刷新到最新时刻，适合日志和监控实时查看场景。
+
+**使用的 API**: 属性: modelValue, times, defaultValue, timestamp | 事件: update:modelValue | 方法: refetch
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimeRange } from '@ksyun-internal/versatile';
+
+const rangeRef = ref<InstanceType<typeof TimeRange>>();
+const timeRange = ref<[number, number] | undefined>();
+const refreshLatest = () => {
+  rangeRef.value?.refetch(60);
+};
+</script>
+
+<template>
+  <button @click="refreshLatest">刷新最近 1 小时</button>
+  <TimeRange
+    ref="rangeRef"
+    v-model="timeRange"
+    :times="[60, 360, 1440]"
+    :default-value="60"
+    :timestamp="true"
+  />
+</template>
+```
+
+## 相关组件
+Datepicker, Duration
+

package/docs_for_llm/tip.doc.md

@@ -12,23 +12,29 @@ import { Tip } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 提示类型 | `<Tip type="warning">警告内容</Tip>` |
-| closable | `boolean` | `false` | 否 | 是否可关闭 | `<Tip closable>可关闭的提示</Tip>` |
-| closed | `boolean` | `false` | 否 | 是否已关闭，可用 v-model:closed 双向绑定 | `<Tip :closed="isClosed">提示</Tip>` |
-| showIcon | `boolean` | `false` | 否 | 是否展示图标 | `<Tip type="success" showIcon>成功</Tip>` |
-| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | `<Tip disabled>禁用状态</Tip>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `<Tip size="small">小尺寸提示</Tip>` |
-| border | `"solid" | "dashed" | "none"` | `"solid"` | 否 | 边框样式 | `<Tip border="dashed">虚线边框</Tip>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 提示类型 | - | `<Tip type="warning">警告内容</Tip>` |
+| closable | `boolean` | `false` | 否 | 是否可关闭 | - | `<Tip closable>可关闭的提示</Tip>` |
+| closed | `boolean` | `false` | 否 | 是否已关闭，可用 v-model:closed 双向绑定 | - | `<Tip :closed="isClosed">提示</Tip>` |
+| showIcon | `boolean` | `false` | 否 | 是否展示图标 | - | `<Tip type="success" showIcon>成功</Tip>` |
+| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | - | `<Tip disabled>禁用状态</Tip>` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | - | `<Tip size="small">小尺寸提示</Tip>` |
+| border | `"solid" | "dashed" | "none"` | `"solid"` | 否 | 边框样式 | - | `<Tip border="dashed">虚线边框</Tip>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | close | `@close` | 关闭时触发 | `e: MouseEvent` | `<Tip closable @close="handleClose"></Tip>` |
 
-### 事件处理函数示例
-**close**:
+### 事件参数说明
+**close**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件 |
+
+事件处理示例:
 ```typescript
 const handleClose = (e: MouseEvent) => {
   console.log('提示已关闭');
@@ -36,14 +42,17 @@ const handleClose = (e: MouseEvent) => {
 ```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 使用 closable 但未处理关闭逻辑
 > **错误用法**: `<Tip closable>提示</Tip> <!-- 点击关闭按钮不会隐藏 -->`
 > **正确写法**: `<Tip closable :closed="closed" @close="handleClose">提示</Tip>`
 > **说明**: closable 只显示关闭按钮，需要监听 close 事件并设置 closed 来隐藏
 
+### type 值拼写错误
 > **错误用法**: `<Tip type="error">错误</Tip>`
 > **正确写法**: `<Tip type="danger">错误</Tip>`
 > **说明**: 错误类型应使用 danger 而非 error
 
+### showIcon 大小写错误
 > **错误用法**: `<Tip showicon>提示</Tip>`
 > **正确写法**: `<Tip showIcon>提示</Tip>`
 > **说明**: 属性名是 showIcon（驼峰命名）

package/docs_for_llm/tooltip.doc.md

@@ -12,58 +12,84 @@ import { Tooltip } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| content | `string | VNode` | `undefined` | 否 | 提示的内容 | `<Tooltip content="提示内容"></Tooltip>` |
-| trigger | `"hover" | "click" | "focus"` | `"hover"` | 否 | 触发方式 | `<Tooltip trigger="click"></Tooltip>` |
-| value | `boolean` | `false` | 否 | 是否展示弹层，可用 v-model 双向绑定 | `<Tooltip v-model="visible"></Tooltip>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用提示 | `<Tooltip disabled></Tooltip>` |
-| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | 弹层弹出的位置，默认在触发器正上方 | `<Tooltip position="bottom"></Tooltip>` |
-| theme | `"dark" | "light"` | `"dark"` | 否 | 主题 | `<Tooltip theme="light"></Tooltip>` |
-| showArrow | `boolean` | `true` | 否 | 弹层是否展示箭头 | `<Tooltip :showArrow="false"></Tooltip>` |
-| hoverable | `boolean` | `false` | 否 | 对于悬浮触发方式，提示弹层是否在鼠标悬浮时仍然展示 | `<Tooltip hoverable></Tooltip>` |
-| always | `boolean` | `false` | 否 | 是否一直保持当前展示/隐藏状态 | `<Tooltip always></Tooltip>` |
-| size | `"default" | "small"` | `"default"` | 否 | 弹层尺寸 | `<Tooltip size="small"></Tooltip>` |
-| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是父元素 | `<Tooltip of="parent"></Tooltip>` |
-| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置 | `<Tooltip :container="() => document.body"></Tooltip>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| content | `string | VNode` | `undefined` | 否 | 提示的内容 | - | `<Tooltip content="提示内容">` |
+| trigger | `"hover" | "click" | "focus"` | `"hover"` | 否 | 触发方式 | - | `<Tooltip trigger="click">` |
+| value | `boolean` | `false` | 否 | 是否展示弹层，可用 v-model 双向绑定 | - | `<Tooltip v-model="visible">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用提示 | - | `<Tooltip disabled>` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | 弹层弹出的位置，默认在触发器正上方 | - | `<Tooltip position="bottom">` |
+| collison | `Collision | [Collision, Collision]` | `undefined` | 否 | 碰撞检测策略，控制弹层超出边界时的处理方式。注意源码字段名拼写为 collison。 | - | `<Tooltip :collison="'flipfit'">` |
+| theme | `"dark" | "light"` | `"dark"` | 否 | 主题 | - | `<Tooltip theme="light">` |
+| showArrow | `boolean` | `true` | 否 | 弹层是否展示箭头 | - | `<Tooltip :showArrow="false">` |
+| hoverable | `boolean` | `false` | 否 | 对于悬浮触发方式，提示弹层是否在鼠标悬浮时仍然展示 | - | `<Tooltip hoverable>` |
+| always | `boolean` | `false` | 否 | 是否一直保持当前展示/隐藏状态 | - | `<Tooltip always>` |
+| size | `"default" | "small"` | `"default"` | 否 | 弹层尺寸 | - | `<Tooltip size="small">` |
+| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是父元素 | - | `<Tooltip of="parent">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置 | - | `<Tooltip :container="() => document.body">` |
+| alwaysShowOnClick | `boolean` | `false` | 否 | 不管什么触发方式，重复点击触发器都不隐藏弹层 | - | `<Tooltip alwaysShowOnClick>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| show | `@show` | 弹层展示时触发 | `-` | `<Tooltip @show="handleShow"></Tooltip>` |
-| hide | `@hide` | 弹层隐藏时触发 | `-` | `<Tooltip @hide="handleHide"></Tooltip>` |
+| show | `@show` | 弹层展示时触发 | `-` | `<Tooltip @show="handleShow">` |
+| hide | `@hide` | 弹层隐藏时触发 | `-` | `<Tooltip @hide="handleHide">` |
+| positioned | `@positioned` | 提示弹层完成定位计算后触发，可用于读取最终落位结果。 | `feedback: Feedback` | `<Tooltip @positioned="handlePositioned">` |
 
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('Tooltip 已展示');
-};
-```
+### 事件参数说明
+**positioned**
 
-**hide**:
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| feedback | `Feedback` | 是 | - | 定位反馈对象，描述当前 Tooltip 的最终 placement 和坐标信息。 |
+
+事件处理示例:
 ```typescript
-const handleHide = () => {
-  console.log('Tooltip 已隐藏');
+const handlePositioned = (feedback: Feedback) => {
+  console.log('Tooltip 最终位置', feedback.placement);
 };
 ```
 
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| content | 自定义提示内容 | `undefined` | - |
+| show | 主动显示提示弹层。 | `shouldFocus?: boolean` | `void` |
+| hide | 主动隐藏提示弹层。 | `immediately: boolean` | `void` |
+| position | 重新计算提示弹层的位置。 | `callback?: (feedback: Feedback) => void` | `void` |
+
+### 方法参数说明
+**show**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| shouldFocus | `boolean` | 否 | - | 显示后是否尝试把焦点移动到弹层内容。 |
+
+**hide**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| immediately | `boolean` | 是 | - | 是否立即隐藏，用于手动控制点击确认型 Tooltip 的关闭时机。 |
+
+**position**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| callback | `(feedback: Feedback) => void` | 否 | - | 定位完成后的回调，可读取最终 placement 和坐标。 |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 未提供触发元素
 > **错误用法**: `<Tooltip content="提示" />`
 > **正确写法**: `<Tooltip content="提示">
   <Button>触发器</Button>
 </Tooltip>`
 > **说明**: Tooltip 需要包裹一个子元素作为触发器
 
+### position 值拼写错误
 > **错误用法**: `<Tooltip position="buttom">`
 > **正确写法**: `<Tooltip position="bottom">`
 > **说明**: position 只支持 top, bottom, left, right，注意拼写
 
+### 使用 hoverable 但 content 不可交互
 > **错误用法**: `<Tooltip hoverable content="纯文本" /> <!-- hoverable 无意义 -->`
 > **正确写法**: `<Tooltip hoverable>
   <Button>触发</Button>

package/docs_for_llm/tour.doc.md

@@ -12,43 +12,63 @@ import { Tour, TourStep } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `number` | `0` | 否 | 当前显示的步骤索引（从0开始），可用 v-model 双向绑定 | `<Tour v-model="currentStep"></Tour>` |
-| visible | `boolean` | `true` | 否 | 是否展示引导组件 | `<Tour :visible="showTour"></Tour>` |
-| data | `TourStepData[]` | `undefined` | 否 | 步骤数据数组，用于数据驱动方式 | `<Tour :data="tourData"></Tour>` |
-| beforeChange | `(current: number) => boolean | Promise<boolean>` | `undefined` | 否 | 步骤切换前的回调函数，返回 false 可阻止切换，支持异步 | `<Tour :beforeChange="handleBeforeChange"></Tour>` |
-| maskClosable | `boolean` | `false` | 否 | 点击遮罩层是否可关闭 | `<Tour maskClosable></Tour>` |
-| closable | `boolean` | `true` | 否 | 是否展示关闭图标 | `<Tour :closable="false"></Tour>` |
-| doneText | `string` | `"完成"` | 否 | 完成按钮文本 | `<Tour doneText="结束引导"></Tour>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `number` | `0` | 否 | 当前显示的步骤索引（从0开始），可用 v-model 双向绑定 | - | `<Tour v-model="currentStep">` |
+| theme | `"dark" | "light"` | `"light"` | 否 | 引导浮层主题 | - | `<Tour theme="dark" />` |
+| visible | `boolean` | `true` | 否 | 是否展示引导组件 | - | `<Tour :visible="showTour">` |
+| data | `TourStepData[]` | `undefined` | 否 | 步骤数据数组，用于数据驱动方式 | - | `<Tour :data="tourData">` |
+| beforeChange | `(current: number) => boolean | Promise<boolean>` | `undefined` | 否 | 步骤切换前的回调函数，返回 false 可阻止切换，支持异步 | - | `<Tour :beforeChange="handleBeforeChange">` |
+| maskClosable | `boolean` | `false` | 否 | 点击遮罩层是否可关闭 | - | `<Tour maskClosable>` |
+| closable | `boolean` | `true` | 否 | 是否展示关闭图标 | - | `<Tour :closable="false">` |
+| doneText | `string` | `"完成"` | 否 | 完成按钮文本 | - | `<Tour doneText="结束引导">` |
+| showArrow | `boolean` | `true` | 否 | 是否展示指向目标元素的箭头 | - | `<Tour :showArrow="false" />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| prev | `@prev` | 点击上一步按钮时触发 | `index: number` | `<Tour @prev="handlePrev"></Tour>` |
-| next | `@next` | 点击下一步按钮时触发 | `index: number` | `<Tour @next="handleNext"></Tour>` |
-| finish | `@finish` | 引导完成或关闭时触发 | `-` | `<Tour @finish="handleFinish"></Tour>` |
+| prev | `@prev` | 点击上一步按钮时触发 | `index: number` | `<Tour @prev="handlePrev">` |
+| next | `@next` | 点击下一步按钮时触发 | `index: number` | `<Tour @next="handleNext">` |
+| finish | `@finish` | 引导完成或关闭时触发 | `-` | `<Tour @finish="handleFinish">` |
+| positioned | `@positioned` | 当前步骤定位完成后触发，可用于读取最终计算位置或做埋点。 | `feedback: Feedback` | `<Tour @positioned="handlePositioned">` |
 
-### 事件处理函数示例
-**prev**:
+### 事件参数说明
+**prev**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| index | `number` | 是 | - | 当前步骤索引 |
+
+事件处理示例:
 ```typescript
 const handlePrev = (index: number) => {
   console.log(`从步骤 ${index} 返回`);
 };
 ```
 
-**next**:
+**next**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| index | `number` | 是 | - | 当前步骤索引 |
+
+事件处理示例:
 ```typescript
 const handleNext = (index: number) => {
   console.log(`从步骤 ${index} 前进`);
 };
 ```
 
-**finish**:
+**positioned**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| feedback | `Feedback` | 是 | - | 定位反馈对象，包含当前步骤最终落位信息。 |
+
+事件处理示例:
 ```typescript
-const handleFinish = () => {
-  showTour.value = false;
-  console.log('引导完成');
+const handlePositioned = (feedback: Feedback) => {
+  console.log('当前定位结果', feedback.placement);
 };
 ```
 
@@ -58,26 +78,25 @@ const handleFinish = () => {
 
 | 属性名 | 类型 | 说明 | 示例 |
 | --- | --- | --- | --- |
-| target | `string | HTMLElement` | 目标元素，可以是 CSS 选择器或 DOM 元素。不指定则居中显示 | `<TourStep target="#btn1"></TourStep>` |
-| title | `string | VNode` | 步骤标题 | `<TourStep title="第一步"></TourStep>` |
-| content | `string | VNode` | 步骤内容 | `<TourStep content="这是引导说明"></TourStep>` |
-| position | `"top" | "right" | "bottom" | "left"` | 弹出位置 | `<TourStep position="top"></TourStep>` |
-| nextText | `string` | 下一步按钮文本 | `<TourStep nextText="继续"></TourStep>` |
-| prevText | `string` | 上一步按钮文本 | `<TourStep prevText="返回"></TourStep>` |
-
-**插槽**:
-- `undefined`: 自定义标题内容
-- `undefined`: 自定义底部内容
+| target | `string | HTMLElement` | 目标元素，可以是 CSS 选择器或 DOM 元素。不指定则居中显示 | `<TourStep target="#btn1">` |
+| title | `string | VNode` | 步骤标题 | `<TourStep title="第一步">` |
+| content | `string | VNode` | 步骤内容 | `<TourStep content="这是引导说明">` |
+| position | `"top" | "right" | "bottom" | "left"` | 弹出位置 | `<TourStep position="top">` |
+| nextText | `string` | 下一步按钮文本 | `<TourStep nextText="继续">` |
+| prevText | `string` | 上一步按钮文本 | `<TourStep prevText="返回">` |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### target 选择器未匹配到元素
 > **错误用法**: `<TourStep target="btn1" /> <!-- 缺少 # -->`
 > **正确写法**: `<TourStep target="#btn1" />`
 > **说明**: target 使用 CSS 选择器，ID 选择器需要加 # 前缀
 
+### 未正确控制 visible 状态
 > **错误用法**: `<Tour :visible="true" /> <!-- 无法关闭 -->`
 > **正确写法**: `<Tour :visible="showTour" @finish="showTour = false" />`
 > **说明**: 需要通过响应式变量和 finish 事件控制显示隐藏
 
+### 步骤索引从 1 开始
 > **错误用法**: `const currentStep = ref(1); // 期望从第一步开始`
 > **正确写法**: `const currentStep = ref(0); // 第一步索引为 0`
 > **说明**: 步骤索引从 0 开始，0 表示第一步