king-design-analyzer 2.1.7 → 2.2.0

package/docs_for_llm/formitemswitch.doc.md

@@ -0,0 +1,113 @@
+# 开关表单项 (FormItemSwitch)
+
+用于业务表单中录入布尔配置的开关表单项组件，补齐了 label、辅助说明和状态切换提示。
+
+**关键词**: form item switch, switch item, 开关表单项, 状态开关, 布尔配置
+
+**使用场景**: 启停开关、布尔配置项录入、紧凑型开关表单
+
+## 导入语句
+```typescript
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| trueValue | `any` | `true` | 否 | 开启时的值 | `inherited:Switch` | `<Switch trueValue="on" falseValue="off" />` |
+| falseValue | `any` | `false` | 否 | 关闭时的值 | `inherited:Switch` | `<Switch trueValue="1" falseValue="0" />` |
+| on | `string` | `undefined` | 否 | 开启时显示的文案 | `inherited:Switch` | `<Switch on="开" off="关" />` |
+| off | `string` | `undefined` | 否 | 关闭时显示的文案 | `inherited:Switch` | `<Switch on="ON" off="OFF" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Switch` | `<Switch disabled />` |
+| loading | `boolean` | `false` | 否 | 是否显示加载状态 | `inherited:Switch` | `<Switch :loading="isLoading" />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Switch` | `<Switch size="small" />` |
+| width | `number | string` | `undefined` | 否 | 开关的宽度 | `inherited:Switch` | `<Switch :width="60" />` |
+| height | `number | string` | `undefined` | 否 | 开关的高度 | `inherited:Switch` | `<Switch :height="24" />` |
+| name | `string` | `undefined` | 否 | 开关的名称，用于表单提交 | `inherited:Switch` | `<Switch name="enable" />` |
+| beforeChange | `(from: any, to: any) => boolean | Promise<boolean>` | `undefined` | 否 | 切换前的拦截函数，返回 false 阻止切换，支持异步 | `inherited:Switch` | `<Switch :beforeChange="handleBeforeChange" />` |
+| modelValue | `boolean | string` | `undefined` | 否 | 当前开关值 | - | - |
+| hideLabel | `boolean` | `undefined` | 否 | 是否隐藏 label 区域 | - | - |
+| label | `string` | `""` | 否 | 表单项标题 | - | - |
+| tip | `string` | `undefined` | 否 | 辅助提示文案 | - | - |
+| helper | `string` | `undefined` | 否 | 说明文案 | - | - |
+| appendTip | `string` | `undefined` | 否 | 右侧追加提示文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 开关值变化时触发，适合直接同步布尔型配置。 | `value?: boolean | string` | - |
+| change:value | `@change:value` | 用户完成一次有效切换后触发，可用于触发联动逻辑。 | `value?: boolean | string` | - |
+| change:op | `@change:op` | 组件内部操作态变化时触发，适合跟踪启停类动作的执行过程。 | `value?: string` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `boolean | string` | 否 | - | 当前开关值，可为布尔值或业务自定义值。 |
+
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `boolean | string` | 否 | - | 本次切换后的最终值。 |
+
+**change:op**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 当前操作态标识，例如启用、关闭或处理中等业务态。 |
+
+## 使用示例
+### 公网访问开关
+**场景**: 在网络配置表单中控制是否开启公网能力。
+
+在表单中配置一个带说明文案的布尔开关项。
+
+**使用的 API**: 属性: modelValue, label, helper | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+
+const enablePublicIp = ref(true);
+</script>
+
+<template>
+  <FormItemSwitch
+    v-model="enablePublicIp"
+    label="开启公网访问"
+    helper="关闭后实例将无法从公网直接访问"
+  />
+</template>
+```
+
+### 隐藏标题的开关项
+**场景**: 在配置卡片中以更紧凑的方式呈现布尔选项。
+
+在紧凑型表单里隐藏 label，仅保留辅助说明。
+
+**使用的 API**: 属性: modelValue, hideLabel, helper, appendTip
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+
+const autoBackup = ref(false);
+</script>
+
+<template>
+  <FormItemSwitch
+    v-model="autoBackup"
+    :hide-label="true"
+    helper="开启后每天凌晨自动执行备份"
+    append-tip="将占用少量存储空间"
+  />
+</template>
+```
+
+## 相关组件
+Switch, FormItemInput
+

package/docs_for_llm/formitemtableconfigs.doc.md

@@ -0,0 +1,95 @@
+# 表格配置表单项 (FormItemTableConfigs)
+
+通过表格方式维护一组配置项的表单组件，适合批量录入实例规格、节点列表、挂载配置等多行数据。
+
+**关键词**: form item table configs, config table form, 配置表格, 实例配置, 批量表单行, 节点配置, 多行表单, 表格型表单项
+
+**使用场景**: 多实例配置表单、批量节点配置、确认步骤只读展示配置列表、通过表格维护一组配置项
+
+## 导入语句
+```typescript
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `any[]` | `[]` | 否 | 当前配置项数组 | - | - |
+| label | `string` | `undefined` | 否 | 表单项标题 | - | - |
+| maxInstanceNum | `number` | `undefined` | 否 | 允许添加的最大实例数 | - | - |
+| minInstanceNum | `number` | `1` | 否 | 允许保留的最小实例数 | - | - |
+| initInstanceModels | `() => Record<string, any>` | `undefined` | 是 | 初始化一条实例配置的工厂函数 | - | - |
+| addBtnText | `string` | `undefined` | 否 | 新增按钮文案 | - | - |
+| showAddBtnLabel | `boolean` | `false` | 否 | 是否显示新增按钮标签 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+| fixHeader | `number` | `undefined` | 否 | 固定表头高度阈值 | - | - |
+| infinite | `boolean` | `undefined` | 否 | 是否启用无限模式 | - | - |
+| readonly | `boolean` | `undefined` | 否 | 是否为只读模式 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 配置项数组变化时触发，新增、删除或编辑行后都会返回最新列表。 | `value?: any[]` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `any[]` | 否 | - | 当前配置项列表数组。 |
+
+## 使用示例
+### 节点配置列表维护
+**场景**: 在集群创建页面中维护多条节点或实例配置。
+
+在表单中维护多条节点或实例配置。
+
+**使用的 API**: 属性: modelValue, label, addBtnText, maxInstanceNum | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+
+const nodes = ref([
+  { name: 'worker-01', spec: '2C4G' },
+]);
+</script>
+
+<template>
+  <FormItemTableConfigs
+    v-model="nodes"
+    label="节点配置"
+    add-btn-text="新增节点"
+    :max-instance-num="5"
+  />
+</template>
+```
+
+### 只读模式展示配置列表
+**场景**: 在提交前确认页只读展示用户已填写的表格配置。
+
+在审核或确认步骤中仅展示配置列表，不允许再编辑。
+
+**使用的 API**: 属性: modelValue, label, readonly
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+
+const instances = ref([
+  { name: 'node-01', spec: '4C8G' },
+  { name: 'node-02', spec: '4C8G' },
+]);
+</script>
+
+<template>
+  <FormItemTableConfigs v-model="instances" label="实例配置" :readonly="true" />
+</template>
+```
+
+## 相关组件
+InstanceList, InstanceNum, FormItemInput, FormItemSpinner
+

package/docs_for_llm/grid.doc.md

@@ -12,11 +12,11 @@ import { Row, Col } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| gutter | `string | number | object` | `undefined` | 否 | 栅格间距，单位 px。也可以传入对象设置响应式间距。 | `<Row :gutter="16"></Row>` |
-| justify | `"start" | "end" | "center" | "between" | "around" | "evenly"` | `undefined` | 否 | flex 布局下的水平排列方式 | `<Row justify="center"></Row>` |
-| align | `"top" | "bottom" | "middle" | "stretch" | "baseline"` | `undefined` | 否 | flex 布局下的垂直对齐方式 | `<Row align="middle"></Row>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| gutter | `string | number | object` | `undefined` | 否 | 栅格间距，单位 px。也可以传入对象设置响应式间距。 | - | `<Row :gutter="16"></Row>` |
+| justify | `"start" | "end" | "center" | "between" | "around" | "evenly"` | `undefined` | 否 | flex 布局下的水平排列方式 | - | `<Row justify="center"></Row>` |
+| align | `"top" | "bottom" | "middle" | "stretch" | "baseline"` | `undefined` | 否 | flex 布局下的垂直对齐方式 | - | `<Row align="middle"></Row>` |
 
 ## 子组件 (Sub-Components)
 ### Col
@@ -37,6 +37,7 @@ import { Row, Col } from '@king-design/vue';
 | xxl | `number | string | object` | ≥1600px 响应式栅格 | - |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### span 总和超过 24
 > **错误用法**: `<Row>
   <Col :span="12">col-12</Col>
   <Col :span="13">col-13</Col>
@@ -47,6 +48,7 @@ import { Row, Col } from '@king-design/vue';
 </Row>`
 > **说明**: Grid 系统基于 24 栅格，一行中的 span 总和（加上 offset）不应超过 24，否则会换行。
 
+### gutter 导致的内容溢出
 > **错误用法**: `<div style="width: 100%; overflow: hidden;">
   <Row :gutter="20">...</Row>
 </div>`

package/docs_for_llm/header.doc.md

@@ -0,0 +1,85 @@
+# 顶部栏 (Header)
+
+页面级顶部栏组件，整合标题、返回、面包屑和文档入口，常用于列表页、详情页以及购买链路页的统一页头。
+
+**关键词**: header, page header, 顶部栏, 面包屑, 文档入口
+
+**使用场景**: 详情页顶部栏、列表页顶部栏、购买链路页面头部
+
+## 导入语句
+```typescript
+import { Header } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 左侧标题文案 | - | - |
+| back | `() => any | RouteLocationRaw` | `undefined` | 否 | 返回配置，支持函数或路由跳转参数 | - | - |
+| doc | `DocParams` | `undefined` | 否 | 相关文档配置，通常包含中英文文档地址 | - | - |
+| docText | `string` | `"相关文档"` | 否 | 文档入口文案 | - | - |
+| newable | `boolean` | `false` | 否 | 是否启用购买链路顶部栏样式 | - | - |
+| breadcrumb | `Array<{ to: string, label: string }>` | `undefined` | 否 | 面包屑导航配置，元素格式为 { to, label } | - | - |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| title | 扩展顶部栏左侧标题处内容 | `<template #title>...</template>` | - |
+| titleAppend | 扩展顶部栏左侧标题后的追加内容 | `<template #titleAppend>...</template>` | - |
+| docPrepend | 扩展右侧文档入口前的内容 | `<template #docPrepend>...</template>` | - |
+| doc | 自定义右侧文档区域 | `<template #doc>...</template>` | - |
+
+## 使用示例
+### 详情页头部信息
+**场景**: 在详情页统一展示返回路径和文档入口。
+
+同时展示标题、面包屑和文档入口，形成统一的页面头部。
+
+**使用的 API**: 属性: title, breadcrumb, doc
+
+```vue
+<script setup lang="ts">
+import { Header } from '@ksyun-internal/versatile';
+
+const breadcrumb = [
+  { to: '/instance', label: '云服务器' },
+  { to: '/instance/list', label: '实例列表' },
+  { to: '/instance/detail', label: '实例详情' },
+];
+const doc = {
+  zh: 'https://docs.ksyun.com/documents/instance',
+};
+</script>
+
+<template>
+  <Header title="实例详情" :breadcrumb="breadcrumb" :doc="doc" />
+</template>
+```
+
+### 通过插槽扩展头部操作
+**场景**: 在页面头部追加状态标识和右侧快捷入口。
+
+使用 titleAppend 和 docPrepend 插槽扩展状态展示和快捷入口。
+
+**使用的 API**: 属性: title, docText
+
+```vue
+<script setup lang="ts">
+import { Header } from '@ksyun-internal/versatile';
+</script>
+
+<template>
+  <Header title="实例详情" doc-text="帮助文档">
+    <template #titleAppend>
+      <span style="margin-left: 8px; color: #18a058;">运行中</span>
+    </template>
+    <template #docPrepend>
+      <a href="/monitor">监控图表</a>
+    </template>
+  </Header>
+</template>
+```
+
+## 相关组件
+LayoutContent, LayoutListContent
+

package/docs_for_llm/icon.doc.md

@@ -12,28 +12,32 @@ import { Icon } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| class | `string` | `undefined` | 是 | 必填。通过 class 指定图标名称，需以 k-icon- 为前缀。例如: k-icon-user | `<Icon class="k-icon-user" />` |
-| size | `"default" | "large" | "small" | "mini" | string | number` | `"default"` | 否 | 定义图标尺寸，可使用预设值或自定义数值 | `<Icon class="k-icon-home" size="large" />` |
-| color | `"default" | "primary" | "danger" | "warning" | "success" | string` | `undefined` | 否 | 图标颜色，可使用预设主题色或自定义颜色值 | `<Icon class="k-icon-heart" color="danger" />` |
-| rotate | `boolean` | `false` | 否 | 是否一直旋转图标，适用于加载状态 | `<Icon class="k-icon-refresh" rotate />` |
-| hoverable | `boolean` | `false` | 否 | 图标是否具有 hover 效果，适用于可点击图标 | `<Icon class="k-icon-delete" hoverable @click="handleDelete" />` |
-| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | `<Icon class="k-icon-edit" disabled />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| class | `string` | `undefined` | 是 | 必填。通过 class 指定图标名称，需以 k-icon- 为前缀。例如: k-icon-user | - | `<Icon class="k-icon-user" />` |
+| size | `"default" | "large" | "small" | "mini" | string | number` | `"default"` | 否 | 定义图标尺寸，可使用预设值或自定义数值 | - | `<Icon class="k-icon-home" size="large" />` |
+| color | `"default" | "primary" | "danger" | "warning" | "success" | string` | `undefined` | 否 | 图标颜色，可使用预设主题色或自定义颜色值 | - | `<Icon class="k-icon-heart" color="danger" />` |
+| rotate | `boolean` | `false` | 否 | 是否一直旋转图标，适用于加载状态 | - | `<Icon class="k-icon-refresh" rotate />` |
+| hoverable | `boolean` | `false` | 否 | 图标是否具有 hover 效果，适用于可点击图标 | - | `<Icon class="k-icon-delete" hoverable @click="handleDelete" />` |
+| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | - | `<Icon class="k-icon-edit" disabled />` |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 未通过 class 指定图标名称
 > **错误用法**: `<Icon name="k-icon-search" />`
 > **正确写法**: `<Icon class="k-icon-search" />`
 > **说明**: 图标名称必须通过 class 属性指定，而非 name 属性
 
+### 图标名称前缀错误
 > **错误用法**: `<Icon class="icon-search" />`
 > **正确写法**: `<Icon class="k-icon-search" />`
 > **说明**: KPC 图标名称必须以 k-icon- 为前缀
 
+### 自定义尺寸使用字符串而非数字
 > **错误用法**: `<Icon class="k-icon-home" size="24px" />`
 > **正确写法**: `<Icon class="k-icon-home" :size="24" />`
 > **说明**: 自定义数值尺寸应使用数字类型，不需要带单位
 
+### 预设颜色值拼写错误
 > **错误用法**: `<Icon class="k-icon-heart" color="red" />`
 > **正确写法**: `<Icon class="k-icon-heart" color="danger" />`
 > **说明**: 预设颜色值为 default, primary, danger, warning, success。如需使用其他颜色，请使用十六进制或 RGB 格式

package/docs_for_llm/icontooltip.doc.md

@@ -0,0 +1,121 @@
+# 图标提示 (IconTooltip)
+
+带有 Tooltip 提示的图标组件，支持普通图标和按钮图标两种类型。常用于工具栏中的刷新、下载、设置等操作。
+
+**关键词**: IconTooltip, 图标提示, 工具栏, 刷新, 下载, 设置
+
+**使用场景**: 工具栏操作按钮、表格刷新按钮、信息提示图标、设置入口
+
+## 导入语句
+```typescript
+import { IconTooltip } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| icon | `string` | `""` | 是 | 指定 KPC 图标的 class 名称 | - | `<IconTooltip icon="k-icon-refresh" />` |
+| type | `"default" | "button"` | `"default"` | 否 | 图标类型 | - | `<IconTooltip type="button" icon="k-icon-refresh" />` |
+| hoverable | `boolean` | `true` | 否 | 图标是否具有 hover 效果 | - | `<IconTooltip icon="k-icon-information" :hoverable="false" />` |
+| loading | `boolean` | `false` | 否 | 对于 type="button" 类型，是否为正在加载中的图标 | - | `<IconTooltip type="button" icon="k-icon-refresh" :loading="true" />` |
+| theme | `"dark" | "light"` | `"dark"` | 否 | 指定 Tooltip 的主题 | - | `<IconTooltip icon="k-icon-refresh" theme="light" />` |
+| tooltipText | `string` | `""` | 否 | 指定 Tooltip 的提示内容 | - | `<IconTooltip icon="k-icon-refresh" tooltipText="刷新" />` |
+| color | `string` | `undefined` | 否 | 自定义图标颜色，适用于普通图标和按钮图标 | - | `<IconTooltip icon="k-icon-information" color="#1890ff" tooltipText="信息" />` |
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 未指定 icon 属性
+> **错误用法**: `<IconTooltip tooltipText="刷新" />`
+> **正确写法**: `<IconTooltip icon="k-icon-refresh" tooltipText="刷新" />`
+> **说明**: icon 是必填属性，需要指定图标的 class 名称
+
+### 在 default 类型上使用 loading
+> **错误用法**: `<IconTooltip icon="k-icon-refresh" :loading="true" />`
+> **正确写法**: `<IconTooltip type="button" icon="k-icon-refresh" :loading="true" />`
+> **说明**: loading 属性仅对 type="button" 类型有效
+
+## 使用示例
+### 基础用法
+**场景**: 展示基础的图标提示
+
+基本的图标提示
+
+**使用的 API**: 属性: icon, tooltipText, theme
+
+```vue
+<script setup lang="ts">
+import { IconTooltip } from '@ksyun-internal/versatile';
+</script>
+<template>
+  <IconTooltip icon="k-icon-refresh" tooltipText="刷新" theme="light" />
+  <IconTooltip icon="k-icon-download" tooltipText="下载" theme="light" />
+  <IconTooltip icon="k-icon-settings" tooltipText="自定义列表字段" theme="light" />
+</template>
+```
+
+### 图标按钮
+**场景**: 展示按钮样式的图标
+
+按钮样式的图标提示
+
+**使用的 API**: 属性: type, icon, tooltipText
+
+```vue
+<script setup lang="ts">
+import { IconTooltip } from '@ksyun-internal/versatile';
+</script>
+<template>
+  <IconTooltip type="button" icon="k-icon-refresh" tooltipText="刷新" />
+  <IconTooltip type="button" icon="k-icon-download" tooltipText="下载" />
+  <IconTooltip type="button" icon="k-icon-settings" tooltipText="自定义列表字段" />
+</template>
+```
+
+### 加载状态
+**场景**: 展示加载中的图标按钮
+
+按钮图标的加载状态
+
+**使用的 API**: 属性: icon, type, loading, tooltipText
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { IconTooltip } from '@ksyun-internal/versatile';
+
+const loading = ref(false);
+const handleClick = () => {
+  loading.value = true;
+  setTimeout(() => loading.value = false, 2000);
+};
+</script>
+<template>
+  <IconTooltip
+    icon="k-icon-refresh"
+    type="button"
+    :loading="loading"
+    tooltipText="刷新"
+    @click="handleClick"
+  />
+</template>
+```
+
+### 去掉 hover 状态
+**场景**: 禁用 hover 效果
+
+禁用 hover 效果的图标
+
+**使用的 API**: 属性: type, icon, tooltipText, hoverable
+
+```vue
+<script setup lang="ts">
+import { IconTooltip } from '@ksyun-internal/versatile';
+</script>
+<template>
+  <IconTooltip type="button" icon="k-icon-refresh" tooltipText="刷新" :hoverable="false" />
+  <IconTooltip icon="k-icon-information" tooltipText="信息提示" :hoverable="false" />
+</template>
+```
+
+## 相关组件
+Icon, Tooltip, ButtonLink
+