king-design-analyzer 2.1.7 → 2.2.0

package/components/timeline.json

@@ -0,0 +1,213 @@
+{
+    "id": "timeline",
+    "name": "Timeline",
+    "displayName": "时间轴",
+    "category": "data",
+    "description": "时间轴组件，用于按时间顺序展示事件或流程记录。配合 TimelineItem 子组件使用，支持不同状态类型和自定义节点。",
+    "importStatement": "import { Timeline, TimelineItem } from '@king-design/vue';",
+    "props": [],
+    "events": [],
+    "slots": [
+        {
+            "name": "default",
+            "description": "时间轴内容，通常由多个 TimelineItem 组成。",
+            "vueTemplate": "<Timeline>...</Timeline>",
+            "usageExample": "<Timeline><TimelineItem>创建完成</TimelineItem><TimelineItem>审核通过</TimelineItem></Timeline>"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "TimelineItem",
+            "description": "时间轴节点项。",
+            "props": [
+                {
+                    "name": "type",
+                    "description": "节点状态类型。",
+                    "type": {
+                        "raw": "\"primary\" | \"warning\" | \"danger\" | \"success\"",
+                        "kind": "union",
+                        "unionTypes": [
+                            "primary",
+                            "warning",
+                            "danger",
+                            "success"
+                        ]
+                    },
+                    "required": false,
+                    "default": "\"primary\"",
+                    "allowedValues": [
+                        {
+                            "value": "primary",
+                            "label": "默认状态",
+                            "isDefault": true
+                        },
+                        {
+                            "value": "warning",
+                            "label": "警告状态"
+                        },
+                        {
+                            "value": "danger",
+                            "label": "错误状态"
+                        },
+                        {
+                            "value": "success",
+                            "label": "成功状态"
+                        }
+                    ],
+                    "usageExample": "<TimelineItem type=\"success\">发布成功</TimelineItem>"
+                },
+                {
+                    "name": "size",
+                    "description": "节点尺寸。",
+                    "type": {
+                        "raw": "\"large\" | \"default\" | \"small\" | \"mini\"",
+                        "kind": "union",
+                        "unionTypes": [
+                            "large",
+                            "default",
+                            "small",
+                            "mini"
+                        ]
+                    },
+                    "required": false,
+                    "default": "\"default\"",
+                    "allowedValues": [
+                        {
+                            "value": "large",
+                            "label": "大尺寸"
+                        },
+                        {
+                            "value": "default",
+                            "label": "默认尺寸",
+                            "isDefault": true
+                        },
+                        {
+                            "value": "small",
+                            "label": "小尺寸"
+                        },
+                        {
+                            "value": "mini",
+                            "label": "迷你尺寸"
+                        }
+                    ],
+                    "usageExample": "<TimelineItem size=\"small\">日志记录</TimelineItem>"
+                }
+            ],
+            "slots": [
+                {
+                    "name": "dot",
+                    "description": "自定义时间轴节点圆点。",
+                    "vueTemplate": "<template #dot>...</template>",
+                    "usageExample": "<TimelineItem><template #dot><Icon class=\"k-icon-check\" /></template>发布完成</TimelineItem>"
+                }
+            ]
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "TimelineItemType",
+            "definition": "type TimelineItemType = 'primary' | 'warning' | 'danger' | 'success'",
+            "description": "TimelineItem 的状态类型"
+        }
+    ],
+    "examples": [
+        {
+            "id": "timeline_basic",
+            "title": "基础用法",
+            "description": "按时间顺序展示操作记录。",
+            "difficulty": "easy",
+            "code": "<template>\n  <Timeline>\n    <TimelineItem>2026-04-20 10:00 创建任务</TimelineItem>\n    <TimelineItem>2026-04-20 10:10 分配负责人</TimelineItem>\n    <TimelineItem type=\"success\">2026-04-20 10:30 处理完成</TimelineItem>\n  </Timeline>\n</template>",
+            "tags": [
+                "basic",
+                "log"
+            ],
+            "usedProps": [
+                "type"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "展示任务处理过程"
+        },
+        {
+            "id": "timeline_status",
+            "title": "不同状态节点",
+            "description": "用颜色区分不同阶段。",
+            "difficulty": "easy",
+            "code": "<template>\n  <Timeline>\n    <TimelineItem type=\"primary\">等待执行</TimelineItem>\n    <TimelineItem type=\"warning\">处理中</TimelineItem>\n    <TimelineItem type=\"danger\">执行失败</TimelineItem>\n    <TimelineItem type=\"success\">重新执行成功</TimelineItem>\n  </Timeline>\n</template>",
+            "tags": [
+                "status",
+                "type"
+            ],
+            "usedProps": [
+                "type"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "用时间轴展示状态变更"
+        },
+        {
+            "id": "timeline_custom_dot",
+            "title": "自定义节点",
+            "description": "通过 dot 插槽渲染图标或编号。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Icon, Timeline, TimelineItem } from '@king-design/vue';\n</script>\n<template>\n  <Timeline>\n    <TimelineItem>\n      <template #dot>\n        <Icon class=\"k-icon-play-circle\" />\n      </template>\n      服务启动\n    </TimelineItem>\n    <TimelineItem type=\"success\">\n      <template #dot>\n        <Icon class=\"k-icon-check\" />\n      </template>\n      健康检查通过\n    </TimelineItem>\n  </Timeline>\n</template>",
+            "tags": [
+                "dot",
+                "icon"
+            ],
+            "usedProps": [
+                "type"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "dot"
+            ],
+            "usedMethods": [],
+            "scenario": "用图标增强时间轴状态表达"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "timeline_plain_children",
+            "description": "在 Timeline 中直接写普通 div，而不是 TimelineItem",
+            "wrongCode": "<Timeline><div>创建成功</div><div>发布完成</div></Timeline>",
+            "correctCode": "<Timeline><TimelineItem>创建成功</TimelineItem><TimelineItem>发布完成</TimelineItem></Timeline>",
+            "explanation": "Timeline 负责整体容器结构，具体节点应使用 TimelineItem 渲染，才能获得连线、圆点和状态样式。",
+            "relatedProps": []
+        },
+        {
+            "id": "timeline_dot_outside_item",
+            "description": "把 dot 插槽写在 Timeline 上",
+            "wrongCode": "<Timeline><template #dot>1</template></Timeline>",
+            "correctCode": "<Timeline><TimelineItem><template #dot>1</template>步骤一</TimelineItem></Timeline>",
+            "explanation": "dot 是 TimelineItem 的插槽，不属于 Timeline 容器本身。",
+            "relatedProps": []
+        }
+    ],
+    "searchKeywords": [
+        "timeline",
+        "时间轴",
+        "操作记录",
+        "流程日志",
+        "TimelineItem",
+        "dot"
+    ],
+    "useCases": [
+        "操作日志",
+        "订单轨迹",
+        "发布流程",
+        "任务执行记录"
+    ],
+    "relatedComponents": [
+        "Steps",
+        "Tag",
+        "Icon"
+    ]
+}

package/components/timepicker.json

@@ -39,6 +39,28 @@
             "default": "false",
             "usageExample": "<Timepicker multiple />"
         },
+        {
+            "name": "filterable",
+            "description": "是否支持筛选输入",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker filterable />"
+        },
+        {
+            "name": "loading",
+            "description": "数据加载状态",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker :loading=\"loading\" />"
+        },
         {
             "name": "disabled",
             "description": "是否禁用",
@@ -50,6 +72,17 @@
             "default": "false",
             "usageExample": "<Timepicker disabled />"
         },
+        {
+            "name": "name",
+            "description": "表单元素的 name 属性",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Timepicker name=\"startTime\" />"
+        },
         {
             "name": "clearable",
             "description": "是否可清空",
@@ -174,6 +207,18 @@
             "default": "undefined",
             "usageExample": "<Timepicker max=\"18:00:00\" />"
         },
+        {
+            "name": "disabledDate",
+            "description": "禁用日期的函数，返回 true 表示禁用该日期",
+            "type": {
+                "raw": "(v: Dayjs) => boolean",
+                "kind": "function",
+                "functionSignature": "(v: Dayjs) => boolean"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Timepicker :disabledDate=\"(d) => d.day() === 0\" />"
+        },
         {
             "name": "hideIcon",
             "description": "是否隐藏后面的图标",
@@ -228,6 +273,78 @@
             "required": false,
             "default": "undefined",
             "usageExample": "<Timepicker :width=\"150\" />"
+        },
+        {
+            "name": "container",
+            "description": "指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body",
+            "type": {
+                "raw": "string | ((parentDom: Element, anchor: Node | null) => Element)",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Timepicker :container=\"() => document.body\" />"
+        },
+        {
+            "name": "show",
+            "description": "是否展示菜单项（受控模式）",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker :show=\"visible\" />"
+        },
+        {
+            "name": "position",
+            "description": "菜单弹出的位置",
+            "type": {
+                "raw": "Position | \"left\" | \"bottom\" | \"right\" | \"top\"",
+                "kind": "union",
+                "unionTypes": [
+                    "left",
+                    "bottom",
+                    "right",
+                    "top"
+                ]
+            },
+            "required": false,
+            "default": "{my: 'left top+8', at: 'left bottom'}",
+            "usageExample": "<Timepicker position=\"top\" />"
+        },
+        {
+            "name": "nowrap",
+            "description": "选中值区域是否不换行展示，适合单行紧凑布局",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker nowrap />"
+        },
+        {
+            "name": "draggable",
+            "description": "多选值是否支持拖动排序",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker multiple draggable />"
+        },
+        {
+            "name": "virtual",
+            "description": "是否开启虚拟列表，用于大数据量场景",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Timepicker virtual />"
         }
     ],
     "events": [
@@ -270,13 +387,40 @@
                     "name": "value",
                     "type": "[Dayjs, Dayjs?]",
                     "description": "当前选择的值"
+                },
+                {
+                    "name": "confirmed",
+                    "type": "boolean",
+                    "description": "当前这次 selecting 是否已经进入确认完成态；常见交互过程中通常为 `false`。"
                 }
             ],
             "usageExample": "<Timepicker range @selecting=\"handleSelecting\" />",
-            "handlerExample": "const handleSelecting = (value) => {\n  console.log('正在选择:', value);\n};"
+            "handlerExample": "const handleSelecting = (value, confirmed) => {\n  console.log('正在选择:', value, confirmed);\n};"
+        }
+    ],
+    "methods": [
+        {
+            "name": "show",
+            "description": "主动展开时间选择面板。",
+            "params": [],
+            "returnType": "void",
+            "usageExample": "timepickerRef.value?.show();"
+        },
+        {
+            "name": "hide",
+            "description": "主动关闭时间选择面板。",
+            "params": [],
+            "returnType": "void",
+            "usageExample": "timepickerRef.value?.hide();"
+        },
+        {
+            "name": "position",
+            "description": "重新计算时间选择面板的位置。",
+            "params": [],
+            "returnType": "void",
+            "usageExample": "timepickerRef.value?.position();"
         }
     ],
-    "methods": [],
     "typeDefinitions": [
         {
             "name": "Value",
@@ -444,4 +588,4 @@
     "relatedComponents": [
         "Datepicker"
     ]
-}
+}

package/components/timerange.json

@@ -0,0 +1,262 @@
+{
+    "id": "timerange",
+    "name": "TimeRange",
+    "displayName": "时间范围",
+    "category": "data",
+    "description": "面向报表、监控和日志场景的时间范围选择组件，支持快捷区间、自定义起止时间以及时间戳格式输出。",
+    "importStatement": "import { TimeRange } from '@ksyun-internal/versatile';",
+    "inherits": [
+        {
+            "component": "Datepicker",
+            "include": [
+                "props"
+            ],
+            "exclude": [
+                "value"
+            ]
+        }
+    ],
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "当前选中的时间范围",
+            "type": {
+                "raw": "[number, number] | [string, string]",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "startTime",
+            "description": "当前时间范围的开始时间",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "endTime",
+            "description": "当前时间范围的结束时间",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "label",
+            "description": "组件标题文案",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"\""
+        },
+        {
+            "name": "times",
+            "description": "快捷时间范围配置，支持分钟数或 today / yesterday 等枚举",
+            "type": {
+                "raw": "(Time | number | 'today' | 'yesterday')[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "defaultValue",
+            "description": "首次渲染时使用的默认快捷值",
+            "type": {
+                "raw": "number | 'today' | 'yesterday'",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "timestamp",
+            "description": "是否以时间戳格式返回值",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false"
+        },
+        {
+            "name": "container",
+            "description": "弹出层挂载容器",
+            "type": {
+                "raw": "Container",
+                "kind": "custom"
+            },
+            "required": false,
+            "default": "undefined"
+        },
+        {
+            "name": "format",
+            "description": "日期格式化字符串",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"YYYY-MM-DD HH:mm:ss\""
+        }
+    ],
+    "events": [
+        {
+            "name": "update:modelValue",
+            "vueEventName": "@update:modelValue",
+            "description": "整个时间范围值变化时触发，适合直接驱动查询参数。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "TimeModelType",
+                    "description": "当前完整时间范围，可能是时间戳元组或格式化后的字符串元组。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "update:startTime",
+            "vueEventName": "@update:startTime",
+            "description": "开始时间变化时触发，可用于单独记录查询区间起点。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string | number",
+                    "description": "当前开始时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。",
+                    "optional": true
+                }
+            ]
+        },
+        {
+            "name": "update:endTime",
+            "vueEventName": "@update:endTime",
+            "description": "结束时间变化时触发，可用于单独记录查询区间终点。",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "string | number",
+                    "description": "当前结束时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。",
+                    "optional": true
+                }
+            ]
+        }
+    ],
+    "slots": [],
+    "methods": [
+        {
+            "name": "setTimeValue",
+            "description": "按快捷值主动切换时间范围",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "number | 'today' | 'yesterday'",
+                    "description": "目标快捷值，可传分钟数或 `today`、`yesterday` 这类内置快捷标识。"
+                }
+            ],
+            "returnType": "void"
+        },
+        {
+            "name": "refetch",
+            "description": "刷新当前时间范围到最新时间",
+            "params": [
+                {
+                    "name": "value",
+                    "type": "number | 'today' | 'yesterday'",
+                    "description": "可选的快捷值；传入后会先切换到该快捷区间，再把结束时间刷新到当前最新时刻。",
+                    "optional": true
+                }
+            ],
+            "returnType": "void"
+        }
+    ],
+    "examples": [
+        {
+            "id": "timerange_monitor",
+            "title": "监控页时间筛选",
+            "description": "提供最近 1 小时、最近 24 小时等快捷时间范围。",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TimeRange } from '@ksyun-internal/versatile';\n\nconst timeRange = ref<[number, number] | undefined>();\n</script>\n\n<template>\n  <TimeRange\n    v-model=\"timeRange\"\n    label=\"统计周期\"\n    :times=\"[60, 360, 'today']\"\n    :timestamp=\"true\"\n  />\n</template>",
+            "tags": [
+                "time",
+                "monitor"
+            ],
+            "usedProps": [
+                "modelValue",
+                "label",
+                "times",
+                "timestamp"
+            ],
+            "usedEvents": [
+                "update:modelValue",
+                "update:startTime",
+                "update:endTime"
+            ],
+            "usedMethods": [],
+            "scenario": "在监控和报表页面中切换查询时间范围。"
+        },
+        {
+            "id": "timerange_refetch_latest",
+            "title": "刷新到最新时间窗口",
+            "description": "通过组件方法把当前时间范围刷新到最新时刻，适合日志和监控实时查看场景。",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { TimeRange } from '@ksyun-internal/versatile';\n\nconst rangeRef = ref<InstanceType<typeof TimeRange>>();\nconst timeRange = ref<[number, number] | undefined>();\nconst refreshLatest = () => {\n  rangeRef.value?.refetch(60);\n};\n</script>\n\n<template>\n  <button @click=\"refreshLatest\">刷新最近 1 小时</button>\n  <TimeRange\n    ref=\"rangeRef\"\n    v-model=\"timeRange\"\n    :times=\"[60, 360, 1440]\"\n    :default-value=\"60\"\n    :timestamp=\"true\"\n  />\n</template>",
+            "tags": [
+                "time",
+                "methods"
+            ],
+            "usedProps": [
+                "modelValue",
+                "times",
+                "defaultValue",
+                "timestamp"
+            ],
+            "usedEvents": [
+                "update:modelValue"
+            ],
+            "usedMethods": [
+                "refetch"
+            ],
+            "scenario": "在日志和监控页面中一键把查询区间重置到最新时间窗口。"
+        }
+    ],
+    "searchKeywords": [
+        "time range",
+        "date range",
+        "time filter",
+        "时间范围",
+        "时间筛选",
+        "快捷时间",
+        "监控时间段",
+        "日志时间查询"
+    ],
+    "useCases": [
+        "监控页时间筛选",
+        "报表页时间范围选择",
+        "日志页最近时间窗口查询",
+        "按快捷区间切换统计周期"
+    ],
+    "relatedComponents": [
+        "Datepicker",
+        "Duration"
+    ],
+    "typeDefinitions": [
+        {
+            "name": "TimeShortcut",
+            "definition": "type TimeShortcut = number | 'today' | 'yesterday'",
+            "description": "快捷时间范围值，支持分钟数以及 today、yesterday 等内置枚举。"
+        },
+        {
+            "name": "TimeModelType",
+            "definition": "type TimeModelType = [number, number] | [string, string]",
+            "description": "时间范围模型值类型，表示开始和结束时间组成的二元组。"
+        }
+    ]
+}

package/components/tip.json

@@ -315,6 +315,13 @@
     "重要信息提示",
     "页面公告"
   ],
+  "typeDefinitions": [
+    {
+      "name": "TipType",
+      "definition": "type TipType = 'default' | 'primary' | 'success' | 'warning' | 'danger'",
+      "description": "提示条语义类型枚举。"
+    }
+  ],
   "relatedComponents": [
     "Tag",
     "Message"