king-design-analyzer 2.1.7 → 2.2.0

package/docs_for_llm/editable.doc.md

@@ -12,17 +12,23 @@ import { Editable } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `string` | `undefined` | 否 | 编辑的内容，可用 v-model 双向绑定 | `<Editable v-model="text" />` |
-| editing | `boolean` | `false` | 否 | 是否为编辑状态 | `<Editable :editing="isEditing" />` |
-| required | `boolean` | `true` | 否 | 是否规定不能为空 | `<Editable :required="false" />` |
-| validate | `((v: string) => boolean) | RegExp | string` | `undefined` | 否 | 验证规则，支持函数、正则表达式或正则字符串。函数返回 true 表示验证通过 | `<Editable :validate="(v) => v.length >= 3" /></Editable>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用编辑 | `<Editable disabled />` |
-| tip | `string` | `"编辑"` | 否 | 编辑按钮提示文案 | `<Editable tip="点击修改" />` |
-| trim | `boolean` | `true` | 否 | 是否去掉前后空白字符 | `<Editable :trim="false" />` |
-| invalid | `boolean` | `false` | 否 | 是否为验证失败状态 | `<Editable :invalid="hasError" />` |
-| rows | `string | number | 'auto' | AutoRows` | `1` | 否 | 是否自动折行及行数控制，可为数字、'auto' 或包含 min/max 的对象 | `<Editable :rows="3" />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `string` | `undefined` | 否 | 编辑的内容，可用 v-model 双向绑定 | - | `<Editable v-model="text" />` |
+| editing | `boolean` | `false` | 否 | 是否为编辑状态 | - | `<Editable :editing="isEditing" />` |
+| required | `boolean` | `true` | 否 | 是否规定不能为空 | - | `<Editable :required="false" />` |
+| validate | `((v: string) => boolean) | RegExp | string` | `undefined` | 否 | 验证规则，支持函数、正则表达式或正则字符串。函数返回 true 表示验证通过 | - | `<Editable :validate="(v) => v.length >= 3" /></Editable>` |
+| disabled | `boolean` | `false` | 否 | 是否禁用编辑 | - | `<Editable disabled />` |
+| placeholder | `string` | `undefined` | 否 | 编辑态输入框的占位提示文本 | - | `<Editable placeholder="请输入内容" />` |
+| title | `string` | `"编辑"` | 否 | 编辑按钮或输入区域的标题提示文本 | - | `<Editable title="修改名称" />` |
+| tip | `string` | `"编辑"` | 否 | 编辑按钮提示文案 | - | `<Editable tip="点击修改" />` |
+| trim | `boolean` | `true` | 否 | 是否去掉前后空白字符 | - | `<Editable :trim="false" />` |
+| invalid | `boolean` | `false` | 否 | 是否为验证失败状态 | - | `<Editable :invalid="hasError" />` |
+| errorTip | `string` | `"输入有误"` | 否 | 验证失败时显示的错误提示文案 | - | `<Editable error-tip="名称格式不正确" />` |
+| okText | `string` | `"确定"` | 否 | 确认按钮文案 | - | `<Editable ok-text="保存" />` |
+| cancelText | `string` | `"取消"` | 否 | 取消按钮文案 | - | `<Editable cancel-text="放弃" />` |
+| type | `string` | `undefined` | 否 | 编辑输入框类型，通常用于切换单行或其他输入模式 | - | `<Editable type="textarea" />` |
+| rows | `string | number | 'auto' | AutoRows` | `1` | 否 | 是否自动折行及行数控制，可为数字、'auto' 或包含 min/max 的对象 | - | `<Editable :rows="3" />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
@@ -30,15 +36,28 @@ import { Editable } from '@king-design/vue';
 | change | `@change` | 当值改变时触发 | `newValue: string, oldValue: string` | `<Editable @change="handleChange" />` |
 | error | `@error` | 验证失败时触发 | `value: string` | `<Editable @error="handleError" />` |
 
-### 事件处理函数示例
-**change**:
+### 事件参数说明
+**change**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| newValue | `string` | 是 | - | 新的值 |
+| oldValue | `string` | 是 | - | 旧的值 |
+
+事件处理示例:
 ```typescript
 const handleChange = (newValue: string, oldValue: string) => {
   console.log(`值从 ${oldValue} 变为 ${newValue}`);
 };
 ```
 
-**error**:
+**error**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 验证失败的值 |
+
+事件处理示例:
 ```typescript
 const handleError = (value: string) => {
   Message.error(`验证失败: ${value}`);
@@ -46,6 +65,7 @@ const handleError = (value: string) => {
 ```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 验证函数返回值错误
 > **错误用法**: `const validate = (v: string) => {
   if (v.length < 3) {
     return '长度不能小于3';
@@ -56,10 +76,12 @@ const handleError = (value: string) => {
 }`
 > **说明**: validate 函数应返回布尔值，true 表示验证通过，false 表示失败
 
+### rows 值类型错误
 > **错误用法**: `<Editable rows="3" />`
 > **正确写法**: `<Editable :rows="3" />`
 > **说明**: 当 rows 为数字时需要使用 v-bind (:rows)，字符串 '3' 会被当作字符串处理
 
+### 不了解 required 默认为 true
 > **错误用法**: `<Editable v-model="text" /> <!-- 用户无法保存空值 -->`
 > **正确写法**: `<Editable v-model="text" :required="false" /> <!-- 允许空值 -->`
 > **说明**: Editable 默认 required 为 true，如果允许空值需要显式设置 :required="false"

package/docs_for_llm/ellipsis.doc.md

@@ -12,23 +12,28 @@ import { Ellipsis } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| maxLines | `number` | `undefined` | 否 | 定义多行省略最大行数，不设置时为单行省略 | `<Ellipsis :maxLines="2">长文本内容</Ellipsis>` |
-| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | Tooltip 弹出的位置，默认在触发器正上方向上偏移 10px | `<Ellipsis position="bottom">长文本</Ellipsis>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 Tooltip 提示（禁用后悬停不会显示完整内容） | `<Ellipsis disabled>长文本</Ellipsis>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| maxLines | `number` | `undefined` | 否 | 定义多行省略最大行数，不设置时为单行省略 | - | `<Ellipsis :maxLines="2">长文本内容</Ellipsis>` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | Tooltip 弹出的位置，默认在触发器正上方向上偏移 10px | - | `<Ellipsis position="bottom">长文本</Ellipsis>` |
+| theme | `"dark" | "light"` | `"light"` | 否 | Tooltip 主题 | - | `<Ellipsis theme="dark">长文本</Ellipsis>` |
+| hoverable | `boolean` | `false` | 否 | 悬浮提示层是否在鼠标移入 Tooltip 内容时仍然保持显示 | - | `<Ellipsis hoverable>长文本</Ellipsis>` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 Tooltip 提示（禁用后悬停不会显示完整内容） | - | `<Ellipsis disabled>长文本</Ellipsis>` |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 容器未设置宽度
 > **错误用法**: `<Ellipsis>长文本内容</Ellipsis>`
 > **正确写法**: `<div style="width: 200px;">
   <Ellipsis>长文本内容</Ellipsis>
 </div>`
 > **说明**: Ellipsis 需要父容器有明确的宽度限制才能生效
 
+### maxLines 使用字符串而非数字
 > **错误用法**: `<Ellipsis maxLines="2">文本</Ellipsis>`
 > **正确写法**: `<Ellipsis :maxLines="2">文本</Ellipsis>`
 > **说明**: maxLines 是数字类型，需要使用 v-bind 语法
 
+### 误解 disabled 属性的含义
 > **错误用法**: `<Ellipsis disabled> <!-- 以为会禁用省略效果 -->`
 > **正确写法**: `<Ellipsis disabled> <!-- 实际是禁用 Tooltip，省略效果仍然存在 -->`
 > **说明**: disabled 只是禁用悬停时的 Tooltip 提示，文本省略效果仍然生效

package/docs_for_llm/filtertablefieldsdialog.doc.md

@@ -0,0 +1,99 @@
+# 表格字段筛选弹窗 (FilterTableFieldsDialog)
+
+用于自定义表格可见列的配置弹窗，常与 ProTable、标准列表页联动，让用户自行决定展示哪些字段。
+
+**关键词**: filter table fields dialog, column settings, 列筛选弹窗, 字段配置, 列展示设置, column chooser, 表格列管理, 隐藏列
+
+**使用场景**: 表格字段自定义、列表列设置、列显示偏好持久化、用户自定义列表展示字段
+
+## 导入语句
+```typescript
+import { FilterTableFieldsDialog } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `boolean` | `undefined` | 否 | 弹窗显示状态 | - | - |
+| fields | `TableFieldItem[]` | `undefined` | 是 | 可配置字段列表 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 弹窗开关状态变化时触发，用于控制列设置面板显隐。 | `value?: boolean` | - |
+| change:noCheckedColFields | `@change:noCheckedColFields` | 未勾选列集合变化时触发，便于把列配置持久化到本地或服务端。 | `value?: string[]` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `boolean` | 否 | - | 当前列设置弹窗是否显示。 |
+
+**change:noCheckedColFields**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string[]` | 否 | - | 当前未勾选字段的 key 列表。 |
+
+## 使用示例
+### 列表列展示配置
+**场景**: 让用户自主配置列表页中要显示的列。
+
+通过字段列表控制表格哪些列默认展示。
+
+**使用的 API**: 属性: modelValue, fields | 事件: update:modelValue, change:noCheckedColFields
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FilterTableFieldsDialog } from '@ksyun-internal/versatile';
+
+const visible = ref(true);
+const fields = [
+  { key: 'id', label: '实例 ID', checked: true },
+  { key: 'name', label: '实例名称', checked: true },
+  { key: 'privateIp', label: '内网 IP', checked: false },
+];
+</script>
+
+<template>
+  <FilterTableFieldsDialog v-model="visible" :fields="fields" />
+</template>
+```
+
+### 持久化隐藏列配置
+**场景**: 让用户的列显示偏好在刷新页面后仍然保留。
+
+监听未勾选字段变化并保存到本地缓存。
+
+**使用的 API**: 属性: modelValue, fields | 事件: change:noCheckedColFields
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FilterTableFieldsDialog } from '@ksyun-internal/versatile';
+
+const visible = ref(true);
+const fields = [
+  { key: 'id', label: '实例 ID', checked: true },
+  { key: 'zone', label: '可用区', checked: true },
+  { key: 'privateIp', label: '内网 IP', checked: false },
+];
+const handleChange = (hiddenFields: string[]) => {
+  localStorage.setItem('instance-hidden-fields', JSON.stringify(hiddenFields));
+};
+</script>
+
+<template>
+  <FilterTableFieldsDialog
+    v-model="visible"
+    :fields="fields"
+    @change:noCheckedColFields="handleChange"
+  />
+</template>
+```
+
+## 相关组件
+ProTable, LayoutStandardList
+

package/docs_for_llm/flex.doc.md

@@ -0,0 +1,74 @@
+# 弹性布局 (Flex)
+
+对 Flexbox 的业务友好封装，适合快速实现工具栏、卡片头部、表单辅助区等横向或纵向弹性布局。
+
+**关键词**: flex, layout, 弹性布局, 对齐, gap
+
+**使用场景**: 工具栏布局、信息块横向或纵向排列、纵向摘要区排版
+
+## 导入语句
+```typescript
+import { Flex } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| align | `'normal' | 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch'` | `'normal'` | 否 | 交叉轴对齐方式 | - | - |
+| justify | `'normal' | 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around'` | `'normal'` | 否 | 主轴对齐方式 | - | - |
+| wrap | `'nowrap' | 'wrap' | 'wrap-reverse' | boolean` | `'nowrap'` | 否 | 换行方式 | - | - |
+| inline | `boolean` | `false` | 否 | 是否以行内 flex 容器渲染 | - | - |
+| vertical | `boolean` | `false` | 否 | 是否启用纵向布局 | - | - |
+| gap | `'small' | 'middle' | 'large' | string` | `'small'` | 否 | 子元素间距，支持预设值或自定义字符串 | - | - |
+| component | `string | Component` | `'div'` | 否 | 容器渲染的标签或组件类型 | - | - |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | Flex 容器内容 | `<Flex>...</Flex>` | - |
+
+## 使用示例
+### 工具栏左右分布布局
+**场景**: 搭建列表页顶部的标题和操作区。
+
+用 Flex 快速搭建常见的左右两端对齐工具栏。
+
+**使用的 API**: 属性: justify, align, gap
+
+```vue
+<script setup lang="ts">
+import { Flex } from '@ksyun-internal/versatile';
+</script>
+
+<template>
+  <Flex justify="space-between" align="center" gap="middle">
+    <div>实例列表</div>
+    <div>刷新 / 导出 / 新建</div>
+  </Flex>
+</template>
+```
+
+### 纵向信息堆叠
+**场景**: 在详情摘要区纵向排列多条关键信息。
+
+使用 vertical 和 gap 快速搭建纵向信息区。
+
+**使用的 API**: 属性: vertical, gap
+
+```vue
+<script setup lang="ts">
+import { Flex } from '@ksyun-internal/versatile';
+</script>
+
+<template>
+  <Flex vertical gap="large">
+    <div>实例规格：4C8G</div>
+    <div>系统盘：100GB SSD</div>
+    <div>网络：经典网络</div>
+  </Flex>
+</template>
+```
+
+## 相关组件
+LayoutContent, LayoutListContent
+

package/docs_for_llm/form.doc.md

@@ -12,20 +12,35 @@ import { Form, FormItem } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| labelWidth | `string | number` | `undefined` | 否 | 定义所有子孙 FormItem 组件的 label 宽度 | `<Form :labelWidth="120"></Form>` |
-| layout | `"horizontal" | "vertical" | "inline"` | `"horizontal"` | 否 | 指定表单布局方式 | `<Form layout="vertical"></Form>` |
-| starOnRequired | `boolean` | `false` | 否 | 当 FormItem 必填时，是否在 label 前面展示 * | `<Form starOnRequired></Form>` |
-| size | `"default" | "small" | "mini"` | `"default"` | 否 | 定义表单之间的间隔大小 | `<Form size="small"></Form>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| labelWidth | `string | number` | `undefined` | 否 | 定义所有子孙 FormItem 组件的 label 宽度 | - | `<Form :labelWidth="120"></Form>` |
+| layout | `"horizontal" | "vertical" | "inline"` | `"horizontal"` | 否 | 指定表单布局方式 | - | `<Form layout="vertical"></Form>` |
+| starOnRequired | `boolean` | `false` | 否 | 当 FormItem 必填时，是否在 label 前面展示 * | - | `<Form starOnRequired></Form>` |
+| size | `"default" | "small" | "mini"` | `"default"` | 否 | 定义表单之间的间隔大小 | - | `<Form size="small"></Form>` |
+| acceptcharset | `string` | `undefined` | 否 | 原生 acceptcharset 属性，指定服务器可处理的字符编码 | `native` | `<Form acceptcharset="UTF-8"></Form>` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定表单自动补全行为 | `native` | `<Form autocomplete="off"></Form>` |
+| name | `string` | `undefined` | 否 | 原生 name 属性 | `native` | `<Form name="loginForm"></Form>` |
+| rel | `string` | `undefined` | 否 | 原生 rel 属性，指定表单与目标资源的关系 | `native` | `<Form rel="external"></Form>` |
+| action | `string` | `undefined` | 否 | 原生 action 属性，指定表单提交地址 | `native` | `<Form action="/api/submit"></Form>` |
+| enctype | `string` | `undefined` | 否 | 原生 enctype 属性，指定表单提交编码类型 | `native` | `<Form enctype="multipart/form-data"></Form>` |
+| method | `"post" | "get" | "dialog"` | `undefined` | 否 | 原生 method 属性，指定表单提交方法 | `native` | `<Form method="post"></Form>` |
+| novalidate | `boolean` | `undefined` | 否 | 原生 novalidate 属性，提交时跳过原生表单校验 | `native` | `<Form novalidate></Form>` |
+| target | `string` | `undefined` | 否 | 原生 target 属性，指定表单响应的打开位置 | `native` | `<Form target="_blank"></Form>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | submit | `@submit` | 当表单提交并且所有规则都验证通过时触发 | `event: Event` | `<Form @submit="handleSubmit"></Form>` |
 
-### 事件处理函数示例
-**submit**:
+### 事件参数说明
+**submit**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| event | `Event` | 是 | - | 原生表单提交事件对象 |
+
+事件处理示例:
 ```typescript
 const handleSubmit = (e: Event) => {
   console.log('表单验证通过，提交中...');
@@ -35,10 +50,10 @@ const handleSubmit = (e: Event) => {
 ## 方法 (Methods)
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| validate | 验证表单所有规则 | `` | `Promise<boolean>` |
-| reset | 重置表单验证状态 | `` | `void` |
-| getFirstInvalidFormItem | 获取第一条出错的 FormItem | `` | `FormItem` |
-| getAllInvalidFormItems | 获取所有校验失败的 FormItem | `` | `FormItem[]` |
+| validate | 验证表单所有规则 | `-` | `Promise<boolean>` |
+| reset | 重置表单验证状态 | `-` | `void` |
+| getFirstInvalidFormItem | 获取第一条出错的 FormItem | `-` | `FormItem` |
+| getAllInvalidFormItems | 获取所有校验失败的 FormItem | `-` | `FormItem[]` |
 
 ## 子组件 (Sub-Components)
 ### FormItem
@@ -63,6 +78,7 @@ const handleSubmit = (e: Event) => {
 - `undefined`: 往后面追加的内容
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### FormItem 配置了 rules 但未绑定 value
 > **错误用法**: `<FormItem label="用户名" :rules="{required: true}">
   <Input v-model="model.username" />
 </FormItem>`
@@ -71,14 +87,17 @@ const handleSubmit = (e: Event) => {
 </FormItem>`
 > **说明**: 使用验证规则时，必须通过 :value 属性绑定需要验证的数据，否则验证不会生效
 
+### 使用不存在的 layout 值
 > **错误用法**: `<Form layout="flex">`
 > **正确写法**: `<Form layout="horizontal">`
 > **说明**: Form 的 layout 只支持 horizontal, vertical, inline 三种值
 
+### rules 格式错误
 > **错误用法**: `<FormItem :rules="'required'">`
 > **正确写法**: `<FormItem :rules="{required: true}">`
 > **说明**: rules 必须是对象格式，key 为规则名，value 为规则参数（通常为 true 或具体值）
 
+### validate 方法未使用 await
 > **错误用法**: `const valid = form.value?.validate();
 if (valid) { /* ... */ }`
 > **正确写法**: `const valid = await form.value?.validate();
@@ -91,7 +110,7 @@ if (valid) { /* ... */ }`
 
 基本的表单验证用法
 
-**使用的 API**: 属性: label, value, rules | 事件: submit
+**使用的 API**: 属性: label, value, rules | 事件: submit | 方法: validate
 
 ```vue
 <script setup lang="ts">
@@ -271,7 +290,7 @@ const model = reactive({
 
 重置表单验证状态
 
-**使用的 API**: 属性: label, value, rules
+**使用的 API**: 属性: label, value, rules | 方法: reset
 
 ```vue
 <script setup lang="ts">

package/docs_for_llm/formiteminput.doc.md

@@ -0,0 +1,128 @@
+# 输入框表单项 (FormItemInput)
+
+带标题、必填、规则校验和辅助说明的输入框表单项，适合业务表单中承载实例名称、域名、备注等字段。
+
+**关键词**: form item input, business input, 输入框表单项, 表单输入, 名称输入
+
+**使用场景**: 常规文本输入、业务表单字段录入、高风险字段提示输入
+
+## 导入语句
+```typescript
+import { FormItemInput } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `string` | `"text"` | 否 | 在原生 input 标签的 type 取值的基础上扩展了 textarea 值，当取该值时渲染成 <textarea> | `inherited:Input` | `<Input type="textarea" :rows="4" placeholder="请输入内容" />` |
+| name | `string` | `undefined` | 否 | 原生 input 标签的 name 属性 | `native`, `inherited:Input` | `<Input name="username" />` |
+| readonly | `boolean` | `false` | 否 | 是否只读 | `native`, `inherited:Input` | `<Input v-model="value" readonly />` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定浏览器自动补全行为 | `native`, `inherited:Input` | `<Input autocomplete="username" />` |
+| autofocus | `boolean` | `undefined` | 否 | 原生 autofocus 属性，页面加载后自动聚焦输入框 | `native`, `inherited:Input` | `<Input autofocus />` |
+| form | `string` | `undefined` | 否 | 原生 form 属性，指定输入框关联的表单 id | `native`, `inherited:Input` | `<Input form="searchForm" />` |
+| maxlength | `number | string` | `undefined` | 否 | 原生 maxlength 属性，限制最大输入长度 | `native`, `inherited:Input` | `<Input :maxlength="50" showCount />` |
+| pattern | `string` | `undefined` | 否 | 原生 pattern 属性，指定输入值需要匹配的正则模式 | `native`, `inherited:Input` | `<Input pattern="[0-9]{6}" placeholder="请输入6位数字" />` |
+| required | `boolean` | `false` | 否 | 是否必填 | - | - |
+| clearable | `boolean` | `false` | 否 | 是否展示快速清除按钮 | `inherited:Input` | `<Input v-model="value" clearable />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Input` | `<Input disabled placeholder="禁用状态" />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `inherited:Input` | `<Input size="large" placeholder="大尺寸输入框" />` |
+| rows | `number | string` | `2` | 否 | 当 type="textarea" 时，默认展示文本行数 | `native`, `inherited:Input` | `<Input type="textarea" :rows="6" />` |
+| cols | `number` | `undefined` | 否 | 原生 cols 属性，当 type="textarea" 时指定可见宽度 | `native`, `inherited:Input` | `<Input type="textarea" :cols="40" />` |
+| datalist | `string` | `undefined` | 否 | 原生 datalist 属性，关联 datalist 元素 id | `native`, `inherited:Input` | `<Input datalist="city-list" />` |
+| dirname | `string` | `undefined` | 否 | 原生 dirname 属性，提交时附带输入方向信息 | `native`, `inherited:Input` | `<Input dirname="comment.dir" />` |
+| wrap | `"hard" | "soft"` | `undefined` | 否 | 原生 wrap 属性，当 type="textarea" 时指定换行提交方式 | `native`, `inherited:Input` | `<Input type="textarea" wrap="hard" />` |
+| autoWidth | `boolean` | `false` | 否 | 是否宽度随输入的文本的长度变化而变化 | `inherited:Input` | `<Input autoWidth placeholder="宽度自适应" />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Input` | `<Input fluid placeholder="宽度100%" />` |
+| width | `string | number` | `undefined` | 否 | 指定宽度，组件会加上单位 px | `inherited:Input` | `<Input :width="300" placeholder="宽度300px" />` |
+| stackClearIcon | `boolean` | `false` | 否 | 是否将清空按钮覆盖在 suffix 按钮上展示来节省空间 | `inherited:Input` | `<Input clearable stackClearIcon />` |
+| frozenOnInput | `boolean` | `false` | 否 | 是否在输入的过程中冻结 value 更新到视图 | `inherited:Input` | `<Input frozenOnInput />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `inherited:Input` | `<Input inline />` |
+| waveDisabled | `boolean` | `false` | 否 | 是否禁用点击波纹效果 | `inherited:Input` | `<Input waveDisabled />` |
+| resize | `"none" | "vertical" | "horizontal" | "both"` | `"vertical"` | 否 | 指定 textarea 输入框拖动调整大小的方向，默认只能垂直方向调整 | `inherited:Input` | `<Input type="textarea" resize="both" />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Input` | `<Input flat placeholder="扁平样式" />` |
+| showCount | `boolean` | `false` | 否 | 是否展示字符长度提示数字 | `inherited:Input` | `<Input showCount maxlength="50" />` |
+| showPassword | `boolean` | `false` | 否 | 当 type="password" 时，是否展示显隐密码按钮 | `inherited:Input` | `<Input type="password" showPassword />` |
+| modelValue | `string | null` | `undefined` | 否 | 当前输入值 | - | - |
+| hideLabel | `boolean` | `undefined` | 否 | 是否隐藏 label 区域 | - | - |
+| label | `string` | `""` | 否 | 表单项标题 | - | - |
+| placeholder | `string` | `undefined` | 否 | 输入框占位文案 | - | - |
+| tip | `string` | `undefined` | 否 | 输入框下方提示文案 | - | - |
+| warnTip | `string` | `undefined` | 否 | 警告提示文案 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| rules | `Record<string, any>` | `{}` | 否 | 表单校验规则 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 输入框值实时变化时触发，适合双向绑定表单字段。 | `value?: string | null` | - |
+| change:value | `@change:value` | 输入值完成一次确认变更时触发，通常用于失焦校验或联动查询。 | `value?: string | null` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | null` | 否 | - | 当前输入框中的值。 |
+
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | null` | 否 | - | 本次确认后的输入值。 |
+
+## 使用示例
+### 实例名称输入项
+**场景**: 在创建实例表单中录入资源名称。
+
+结合 label、placeholder 和 tip 构造标准业务表单项。
+
+**使用的 API**: 属性: modelValue, label, placeholder, tip, required | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemInput } from '@ksyun-internal/versatile';
+
+const instanceName = ref('web-prod-01');
+</script>
+
+<template>
+  <FormItemInput
+    v-model="instanceName"
+    label="实例名称"
+    placeholder="请输入实例名称"
+    tip="长度 2 到 63 个字符，支持字母、数字和中划线"
+    :required="true"
+  />
+</template>
+```
+
+### 带警告提示的输入项
+**场景**: 在高风险配置项旁直接展示风险和补充说明。
+
+在输入可能影响线上流量的字段时补充警告说明。
+
+**使用的 API**: 属性: modelValue, label, warnTip, info
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemInput } from '@ksyun-internal/versatile';
+
+const domain = ref('api.example.com');
+</script>
+
+<template>
+  <FormItemInput
+    v-model="domain"
+    label="回源域名"
+    warn-tip="修改后可能影响现网回源路径"
+    info="请确保 DNS 已正确解析"
+  />
+</template>
+```
+
+## 相关组件
+Input, FormItemSpinner
+

package/docs_for_llm/formitemspinner.doc.md

@@ -0,0 +1,105 @@
+# 数字步进表单项 (FormItemSpinner)
+
+把数字步进器和表单项包装在一起的业务组件，适合 CPU 核数、带宽、节点数等带单位和范围限制的数值输入。
+
+**关键词**: form item spinner, number input, 数字步进, 表单项, 带单位输入
+
+**使用场景**: 数量输入、规格和配额设置、带精度控制的数值输入
+
+## 导入语句
+```typescript
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Spinner` | `<Spinner disabled />` |
+| max | `number` | `Infinity` | 否 | 最大值 | - | - |
+| min | `number` | `0` | 否 | 最小值 | - | - |
+| step | `number` | `1` | 否 | 步长 | - | - |
+| size | `"default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Spinner` | `<Spinner size="small" />` |
+| vertical | `boolean` | `false` | 否 | 控制按钮是否竖直排列 | `inherited:Spinner` | `<Spinner vertical />` |
+| precision | `number` | `0` | 否 | 保留小数位数 | - | - |
+| formatter | `(value: number) => string` | `undefined` | 否 | 定义格式化展示值的函数 | `inherited:Spinner` | `<Spinner :formatter="(val) => `${val}%`" :parser="(val) => parseFloat(val)" /></Spinner>` |
+| parser | `(value: string) => number` | `undefined` | 否 | 与 formatter 结合使用，定义解析格式化的值的函数 | `inherited:Spinner` | `<Spinner :formatter="(val) => `${val}%`" :parser="(val) => parseFloat(val)" /></Spinner>` |
+| prefix | `string` | `undefined` | 否 | 定义展示的值的前缀，优先级低于 formatter | `inherited:Spinner` | `<Spinner prefix="¥" />` |
+| suffix | `string` | `undefined` | 否 | 定义展示的值的后缀，优先级低于 formatter | `inherited:Spinner` | `<Spinner suffix="元" />` |
+| width | `string | number` | `undefined` | 否 | 指定 Input 输入框的宽度 | `inherited:Spinner` | `<Spinner :width="150" />` |
+| forceStep | `boolean` | `false` | 否 | value 值除了边界值，都必须满足 min + step * n（n 为整数） | `inherited:Spinner` | `<Spinner :min="0" :step="5" forceStep />` |
+| modelValue | `number | null` | `undefined` | 否 | 当前数值 | - | - |
+| label | `string` | `undefined` | 否 | 表单项标题 | - | - |
+| required | `boolean` | `false` | 否 | 是否必填 | - | - |
+| rules | `Record<string, any>` | `{}` | 否 | 表单校验规则 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+| unit | `string` | `undefined` | 否 | 数值单位 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 数值变化时触发，可用于实时计算价格、配额或资源总量。 | `value?: number | null` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | null` | 否 | - | 当前数值输入结果。 |
+
+## 使用示例
+### 带宽数值表单项
+**场景**: 在购买页中配置带宽大小并联动价格。
+
+通过最小值、最大值和单位控制业务数值输入。
+
+**使用的 API**: 属性: modelValue, label, min, max, unit | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+
+const bandwidth = ref(20);
+</script>
+
+<template>
+  <FormItemSpinner
+    v-model="bandwidth"
+    label="带宽峰值"
+    :min="1"
+    :max="200"
+    unit="Mbps"
+  />
+</template>
+```
+
+### 带精度控制的数值输入
+**场景**: 在高精度资源配置场景中输入支持小数的指标值。
+
+使用 step 和 precision 录入带小数的资源规格。
+
+**使用的 API**: 属性: modelValue, label, step, precision, unit
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+
+const bandwidth = ref(1.5);
+</script>
+
+<template>
+  <FormItemSpinner
+    v-model="bandwidth"
+    label="弹性带宽"
+    :step="0.5"
+    :precision="1"
+    unit="Gbps"
+  />
+</template>
+```
+
+## 相关组件
+Spinner, FormItemInput, InstanceNum
+