king-design-analyzer 1.0.0

package/components/tour.json

@@ -0,0 +1,395 @@
+{
+    "id": "tour",
+    "name": "Tour",
+    "displayName": "引导式导航",
+    "category": "feedback",
+    "description": "引导式导航组件，用于新手引导和功能介绍。支持定位到目标元素、自定义步骤内容、步骤切换控制等功能。配合 TourStep 子组件使用。",
+    "importStatement": "import { Tour, TourStep } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "value",
+            "description": "当前显示的步骤索引（从0开始），可用 v-model 双向绑定",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "0",
+            "usageExample": "<Tour v-model=\"currentStep\">"
+        },
+        {
+            "name": "visible",
+            "description": "是否展示引导组件",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Tour :visible=\"showTour\">"
+        },
+        {
+            "name": "data",
+            "description": "步骤数据数组，用于数据驱动方式",
+            "type": {
+                "raw": "TourStepData[]",
+                "kind": "array"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tour :data=\"tourData\">"
+        },
+        {
+            "name": "beforeChange",
+            "description": "步骤切换前的回调函数，返回 false 可阻止切换，支持异步",
+            "type": {
+                "raw": "(current: number) => boolean | Promise<boolean>",
+                "kind": "function",
+                "functionSignature": "(current: number) => boolean | Promise<boolean>"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Tour :beforeChange=\"handleBeforeChange\">"
+        },
+        {
+            "name": "maskClosable",
+            "description": "点击遮罩层是否可关闭",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tour maskClosable>"
+        },
+        {
+            "name": "closable",
+            "description": "是否展示关闭图标",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<Tour :closable=\"false\">"
+        },
+        {
+            "name": "doneText",
+            "description": "完成按钮文本",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "default": "\"完成\"",
+            "usageExample": "<Tour doneText=\"结束引导\">"
+        }
+    ],
+    "events": [
+        {
+            "name": "prev",
+            "vueEventName": "@prev",
+            "description": "点击上一步按钮时触发",
+            "payload": [
+                {
+                    "name": "index",
+                    "type": "number",
+                    "description": "当前步骤索引"
+                }
+            ],
+            "usageExample": "<Tour @prev=\"handlePrev\">",
+            "handlerExample": "const handlePrev = (index: number) => {\n  console.log(`从步骤 ${index} 返回`);\n};"
+        },
+        {
+            "name": "next",
+            "vueEventName": "@next",
+            "description": "点击下一步按钮时触发",
+            "payload": [
+                {
+                    "name": "index",
+                    "type": "number",
+                    "description": "当前步骤索引"
+                }
+            ],
+            "usageExample": "<Tour @next=\"handleNext\">",
+            "handlerExample": "const handleNext = (index: number) => {\n  console.log(`从步骤 ${index} 前进`);\n};"
+        },
+        {
+            "name": "finish",
+            "vueEventName": "@finish",
+            "description": "引导完成或关闭时触发",
+            "payload": [],
+            "usageExample": "<Tour @finish=\"handleFinish\">",
+            "handlerExample": "const handleFinish = () => {\n  showTour.value = false;\n  console.log('引导完成');\n};"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "TourStep",
+            "description": "引导步骤组件，用于定义每个引导步骤的内容",
+            "props": [
+                {
+                    "name": "target",
+                    "description": "目标元素，可以是 CSS 选择器或 DOM 元素。不指定则居中显示",
+                    "type": {
+                        "raw": "string | HTMLElement",
+                        "kind": "union"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<TourStep target=\"#btn1\">"
+                },
+                {
+                    "name": "title",
+                    "description": "步骤标题",
+                    "type": {
+                        "raw": "string | VNode",
+                        "kind": "union"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<TourStep title=\"第一步\">"
+                },
+                {
+                    "name": "content",
+                    "description": "步骤内容",
+                    "type": {
+                        "raw": "string | VNode",
+                        "kind": "union"
+                    },
+                    "required": false,
+                    "default": "undefined",
+                    "usageExample": "<TourStep content=\"这是引导说明\">"
+                },
+                {
+                    "name": "position",
+                    "description": "弹出位置",
+                    "type": {
+                        "raw": "\"top\" | \"right\" | \"bottom\" | \"left\"",
+                        "kind": "union"
+                    },
+                    "required": false,
+                    "default": "\"bottom\"",
+                    "allowedValues": [
+                        {
+                            "value": "top",
+                            "label": "上方"
+                        },
+                        {
+                            "value": "right",
+                            "label": "右侧"
+                        },
+                        {
+                            "value": "bottom",
+                            "label": "下方",
+                            "isDefault": true
+                        },
+                        {
+                            "value": "left",
+                            "label": "左侧"
+                        }
+                    ],
+                    "usageExample": "<TourStep position=\"top\">"
+                },
+                {
+                    "name": "nextText",
+                    "description": "下一步按钮文本",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "\"下一步\"",
+                    "usageExample": "<TourStep nextText=\"继续\">"
+                },
+                {
+                    "name": "prevText",
+                    "description": "上一步按钮文本",
+                    "type": {
+                        "raw": "string",
+                        "kind": "string"
+                    },
+                    "required": false,
+                    "default": "\"上一步\"",
+                    "usageExample": "<TourStep prevText=\"返回\">"
+                }
+            ],
+            "slots": [
+                {
+                    "name": "title",
+                    "description": "自定义标题内容"
+                },
+                {
+                    "name": "footer",
+                    "description": "自定义底部内容"
+                }
+            ]
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "TourStepData",
+            "definition": "type TourStepData = {\n  target?: string | HTMLElement\n  title?: string | VNode\n  content?: string | VNode\n  position?: 'top' | 'right' | 'bottom' | 'left'\n  nextText?: string\n  prevText?: string\n}",
+            "description": "步骤数据配置"
+        }
+    ],
+    "examples": [
+        {
+            "id": "tour_basic",
+            "title": "基础用法",
+            "description": "使用 data 属性定义引导步骤",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Tour, Button } from '@king-design/vue';\n\nconst currentStep = ref(0);\nconst showTour = ref(false);\nconst tourData = reactive([\n  { target: '#btn1', title: '第一步', content: '这是第一步的引导说明', position: 'bottom' },\n  { target: '#btn2', title: '第二步', content: '这是第二步的引导说明', position: 'right' }\n]);\n\nconst startTour = () => {\n  showTour.value = true;\n  currentStep.value = 0;\n};\n\nconst closeTour = () => {\n  showTour.value = false;\n};\n</script>\n<template>\n  <div>\n    <Button id=\"btn1\">元素1</Button>\n    <Button id=\"btn2\" style=\"margin-left: 20px;\">元素2</Button>\n    <Tour v-model=\"currentStep\" :visible=\"showTour\" :data=\"tourData\" @finish=\"closeTour\" />\n    <Button @click=\"startTour\">启动引导</Button>\n  </div>\n</template>",
+            "tags": [
+                "basic",
+                "data"
+            ],
+            "usedProps": [
+                "value",
+                "visible",
+                "data"
+            ],
+            "usedEvents": [
+                "finish"
+            ],
+            "usedMethods": [],
+            "scenario": "创建基本的新手引导"
+        },
+        {
+            "id": "tour_declarative",
+            "title": "声明式步骤",
+            "description": "使用 TourStep 子组件定义步骤",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Tour, TourStep, Button } from '@king-design/vue';\n\nconst currentStep = ref(0);\nconst showTour = ref(false);\n\nconst startTour = () => {\n  showTour.value = true;\n  currentStep.value = 0;\n};\n\nconst closeTour = () => {\n  showTour.value = false;\n};\n</script>\n<template>\n  <div>\n    <Button id=\"btn1\">元素1</Button>\n    <Button id=\"btn2\" style=\"margin-left: 20px;\">元素2</Button>\n    <Tour v-model=\"currentStep\" :visible=\"showTour\" @finish=\"closeTour\">\n      <TourStep target=\"#btn1\" title=\"第一步\" content=\"第一步说明\" position=\"left\" />\n      <TourStep target=\"#btn2\" title=\"第二步\" position=\"top\">第二步说明</TourStep>\n    </Tour>\n    <Button @click=\"startTour\">启动引导</Button>\n  </div>\n</template>",
+            "tags": [
+                "declarative",
+                "TourStep"
+            ],
+            "usedProps": [
+                "value",
+                "visible"
+            ],
+            "usedEvents": [
+                "finish"
+            ],
+            "usedMethods": [],
+            "scenario": "使用声明式方式定义引导步骤"
+        },
+        {
+            "id": "tour_events",
+            "title": "步骤事件",
+            "description": "监听步骤切换事件",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Tour, Button, Message } from '@king-design/vue';\n\nconst currentStep = ref(0);\nconst showTour = ref(false);\nconst tourData = reactive([\n  { target: '#btn1', title: '第一步', content: '点击下一步触发 next 事件' },\n  { target: '#btn2', title: '第二步', content: '点击完成触发 finish 事件' }\n]);\n\nconst handleNext = (index: number) => {\n  Message.info(`下一步，当前索引: ${index}`);\n};\n\nconst handleFinish = () => {\n  Message.success('引导完成！');\n  showTour.value = false;\n};\n</script>\n<template>\n  <div>\n    <Button id=\"btn1\">步骤1</Button>\n    <Button id=\"btn2\">步骤2</Button>\n    <Tour v-model=\"currentStep\" :visible=\"showTour\" :data=\"tourData\" \n      @next=\"handleNext\" @finish=\"handleFinish\" />\n  </div>\n</template>",
+            "tags": [
+                "events",
+                "next",
+                "finish"
+            ],
+            "usedProps": [
+                "value",
+                "visible",
+                "data"
+            ],
+            "usedEvents": [
+                "next",
+                "finish"
+            ],
+            "usedMethods": [],
+            "scenario": "监听步骤切换事件"
+        },
+        {
+            "id": "tour_beforechange",
+            "title": "步骤验证",
+            "description": "切换前进行验证",
+            "difficulty": "hard",
+            "code": "<script setup lang=\"ts\">\nimport { ref, reactive } from 'vue';\nimport { Tour, Button, Message } from '@king-design/vue';\n\nconst currentStep = ref(0);\nconst showTour = ref(false);\nconst tourData = reactive([\n  { target: '#step1', title: '第一步', content: '点击下一步进行验证' },\n  { target: '#step2', title: '第二步', content: '验证通过后到达这里' }\n]);\n\nconst handleBeforeChange = async (current: number): Promise<boolean> => {\n  if (current === 0) {\n    Message.info('正在验证...');\n    await new Promise(r => setTimeout(r, 1000));\n    Message.success('验证通过！');\n    return true;\n  }\n  return true;\n};\n</script>\n<template>\n  <div>\n    <Button id=\"step1\">步骤1</Button>\n    <Button id=\"step2\">步骤2</Button>\n    <Tour v-model=\"currentStep\" :visible=\"showTour\" :data=\"tourData\" \n      :beforeChange=\"handleBeforeChange\" />\n  </div>\n</template>",
+            "tags": [
+                "beforeChange",
+                "validation",
+                "async"
+            ],
+            "usedProps": [
+                "value",
+                "visible",
+                "data",
+                "beforeChange"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "步骤切换前进行异步验证"
+        },
+        {
+            "id": "tour_center",
+            "title": "居中引导",
+            "description": "无目标元素的居中显示",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Tour, TourStep, Button } from '@king-design/vue';\n\nconst currentStep = ref(0);\nconst showTour = ref(false);\n\nconst startTour = () => {\n  showTour.value = true;\n  currentStep.value = 0;\n};\n\nconst closeTour = () => {\n  showTour.value = false;\n};\n</script>\n<template>\n  <div>\n    <Tour v-model=\"currentStep\" :visible=\"showTour\" @finish=\"closeTour\">\n      <TourStep title=\"欢迎页面\">\n        <span>没有指定目标元素时，引导弹窗会居中显示。</span>\n      </TourStep>\n      <TourStep title=\"功能介绍\">\n        <span>适合用于展示全局性的引导说明。</span>\n      </TourStep>\n    </Tour>\n    <Button @click=\"startTour\">启动无目标引导</Button>\n  </div>\n</template>",
+            "tags": [
+                "center",
+                "noTarget"
+            ],
+            "usedProps": [
+                "value",
+                "visible"
+            ],
+            "usedEvents": [
+                "finish"
+            ],
+            "usedMethods": [],
+            "scenario": "无目标元素的居中显示引导"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "tour_target_selector",
+            "description": "target 选择器未匹配到元素",
+            "wrongCode": "<TourStep target=\"btn1\" /> <!-- 缺少 # -->",
+            "correctCode": "<TourStep target=\"#btn1\" />",
+            "explanation": "target 使用 CSS 选择器，ID 选择器需要加 # 前缀",
+            "relatedProps": [
+                "target"
+            ]
+        },
+        {
+            "id": "tour_visible_control",
+            "description": "未正确控制 visible 状态",
+            "wrongCode": "<Tour :visible=\"true\" /> <!-- 无法关闭 -->",
+            "correctCode": "<Tour :visible=\"showTour\" @finish=\"showTour = false\" />",
+            "explanation": "需要通过响应式变量和 finish 事件控制显示隐藏",
+            "relatedProps": [
+                "visible"
+            ]
+        },
+        {
+            "id": "tour_step_index",
+            "description": "步骤索引从 1 开始",
+            "wrongCode": "const currentStep = ref(1); // 期望从第一步开始",
+            "correctCode": "const currentStep = ref(0); // 第一步索引为 0",
+            "explanation": "步骤索引从 0 开始，0 表示第一步",
+            "relatedProps": [
+                "value"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "引导",
+        "tour",
+        "新手引导",
+        "向导",
+        "导览",
+        "教程"
+    ],
+    "useCases": [
+        "新手引导",
+        "功能介绍",
+        "产品导览",
+        "操作教程",
+        "更新公告"
+    ],
+    "relatedComponents": [
+        "TourStep",
+        "Steps"
+    ]
+}