king-design-analyzer 1.0.0

package/components/tag.json

@@ -0,0 +1,504 @@
+{
+    "id": "tag",
+    "name": "Tag",
+    "displayName": "标签",
+    "category": "data",
+    "description": "标签组件，用于标记和分类信息。支持多种类型、可关闭、可拖拽排序等功能。配合 Tags 组件可管理标签组。",
+    "importStatement": "import { Tag, Tags } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "type",
+            "description": "组件类型，决定标签的视觉样式",
+            "type": {
+                "raw": "\"default\" | \"primary\" | \"success\" | \"warning\" | \"danger\"",
+                "kind": "union",
+                "unionTypes": [
+                    "default",
+                    "primary",
+                    "success",
+                    "warning",
+                    "danger"
+                ]
+            },
+            "required": false,
+            "default": "\"default\"",
+            "allowedValues": [
+                {
+                    "value": "default",
+                    "label": "默认灰色标签",
+                    "isDefault": true
+                },
+                {
+                    "value": "primary",
+                    "label": "主题蓝色标签"
+                },
+                {
+                    "value": "success",
+                    "label": "成功绿色标签"
+                },
+                {
+                    "value": "warning",
+                    "label": "警告橙色标签"
+                },
+                {
+                    "value": "danger",
+                    "label": "危险红色标签"
+                }
+            ],
+            "usageExample": "<Tag type=\"primary\">主要标签</Tag>"
+        },
+        {
+            "name": "closable",
+            "description": "是否可关闭，显示关闭按钮",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tag closable @close=\"handleClose\">可关闭标签</Tag>"
+        },
+        {
+            "name": "closed",
+            "description": "是否已关闭（受控模式）",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tag closable :closed=\"isClosed\" @close=\"handleClose\">标签</Tag>"
+        },
+        {
+            "name": "disabled",
+            "description": "是否展示禁用状态",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Tag disabled>禁用标签</Tag>"
+        },
+        {
+            "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": "<Tag size=\"small\">小标签</Tag>"
+        },
+        {
+            "name": "border",
+            "description": "定义边框样式",
+            "type": {
+                "raw": "\"solid\" | \"dashed\" | \"none\"",
+                "kind": "union",
+                "unionTypes": [
+                    "solid",
+                    "dashed",
+                    "none"
+                ]
+            },
+            "required": false,
+            "default": "\"none\"",
+            "allowedValues": [
+                {
+                    "value": "none",
+                    "label": "无边框",
+                    "isDefault": true
+                },
+                {
+                    "value": "solid",
+                    "label": "实线边框"
+                },
+                {
+                    "value": "dashed",
+                    "label": "虚线边框"
+                }
+            ],
+            "usageExample": "<Tag border=\"solid\">带边框标签</Tag>"
+        }
+    ],
+    "events": [
+        {
+            "name": "close",
+            "vueEventName": "@close",
+            "description": "标签关闭事件，点击关闭按钮时触发",
+            "payload": [
+                {
+                    "name": "e",
+                    "type": "MouseEvent",
+                    "description": "原生鼠标事件对象"
+                }
+            ],
+            "usageExample": "<Tag closable @close=\"handleClose\">可关闭</Tag>",
+            "handlerExample": "const handleClose = (e: MouseEvent) => {\n  console.log('标签已关闭');\n};"
+        }
+    ],
+    "methods": [],
+    "subComponents": [
+        {
+            "name": "Tags",
+            "description": "标签组容器，用于管理多个标签，支持单行展示和拖拽排序",
+            "props": [
+                {
+                    "name": "size",
+                    "description": "定义\"更多\"标签尺寸",
+                    "type": {
+                        "raw": "\"large\" | \"default\" | \"small\" | \"mini\"",
+                        "kind": "union",
+                        "unionTypes": [
+                            "large",
+                            "default",
+                            "small",
+                            "mini"
+                        ]
+                    },
+                    "required": false,
+                    "default": "\"default\"",
+                    "usageExample": "<Tags size=\"small\">"
+                },
+                {
+                    "name": "border",
+                    "description": "定义\"更多\"标签边框样式",
+                    "type": {
+                        "raw": "\"solid\" | \"dashed\" | \"none\"",
+                        "kind": "union",
+                        "unionTypes": [
+                            "solid",
+                            "dashed",
+                            "none"
+                        ]
+                    },
+                    "required": false,
+                    "default": "\"none\"",
+                    "usageExample": "<Tags border=\"solid\">"
+                },
+                {
+                    "name": "nowrap",
+                    "description": "是否单行展示标签组，超出的部分会隐藏，仅展示隐藏数量",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<Tags nowrap>"
+                },
+                {
+                    "name": "draggable",
+                    "description": "标签是否支持拖动排序",
+                    "type": {
+                        "raw": "boolean",
+                        "kind": "boolean"
+                    },
+                    "required": false,
+                    "default": "false",
+                    "usageExample": "<Tags draggable>"
+                }
+            ],
+            "events": [
+                {
+                    "name": "dragstart",
+                    "vueEventName": "@dragstart",
+                    "description": "拖动开始时触发",
+                    "payload": [
+                        {
+                            "name": "key",
+                            "type": "string | number",
+                            "description": "被拖拽标签的 key"
+                        },
+                        {
+                            "name": "from",
+                            "type": "number",
+                            "description": "起始位置索引"
+                        }
+                    ],
+                    "usageExample": "<Tags draggable @dragstart=\"handleDragStart\">",
+                    "handlerExample": "const handleDragStart = ({key, from}) => {\n  console.log('开始拖拽', key, from);\n};"
+                },
+                {
+                    "name": "dragend",
+                    "vueEventName": "@dragend",
+                    "description": "拖动结束时触发",
+                    "payload": [
+                        {
+                            "name": "key",
+                            "type": "string | number",
+                            "description": "被拖拽标签的 key"
+                        },
+                        {
+                            "name": "from",
+                            "type": "number",
+                            "description": "起始位置索引"
+                        },
+                        {
+                            "name": "to",
+                            "type": "number",
+                            "description": "目标位置索引"
+                        }
+                    ],
+                    "usageExample": "<Tags draggable @dragend=\"handleDragEnd\">",
+                    "handlerExample": "const handleDragEnd = ({key, from, to}) => {\n  console.log('拖拽结束', key, 'from', from, 'to', to);\n};"
+                }
+            ],
+            "slots": [
+                {
+                    "name": "append",
+                    "description": "追加到后面的元素，不参与到Tags对Tag的管理中"
+                }
+            ]
+        }
+    ],
+    "typeDefinitions": [
+        {
+            "name": "Key",
+            "definition": "type Key = string | number",
+            "description": "标签的唯一标识类型"
+        },
+        {
+            "name": "TagsDragStartParam",
+            "definition": "type TagsDragStartParam = {\n  key: Key\n  from: number\n}",
+            "description": "拖拽开始事件参数"
+        },
+        {
+            "name": "TagsDragEndParam",
+            "definition": "type TagsDragEndParam = TagsDragStartParam & {\n  to: number\n}",
+            "description": "拖拽结束事件参数"
+        }
+    ],
+    "examples": [
+        {
+            "id": "tag_basic",
+            "title": "基础用法",
+            "description": "不同类型的标签",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Tag } from '@king-design/vue';\n</script>\n<template>\n  <Tag>默认标签</Tag>\n  <Tag type=\"primary\">主要标签</Tag>\n  <Tag type=\"success\">成功标签</Tag>\n  <Tag type=\"warning\">警告标签</Tag>\n  <Tag type=\"danger\">危险标签</Tag>\n</template>",
+            "tags": [
+                "basic",
+                "type"
+            ],
+            "usedProps": [
+                "type"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "展示不同类型的标签"
+        },
+        {
+            "id": "tag_closable",
+            "title": "可关闭标签",
+            "description": "带有关闭按钮的标签",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Tag } from '@king-design/vue';\n\nconst closed = ref(false);\n\nconst handleClose = () => {\n  closed.value = true;\n};\n</script>\n<template>\n  <Tag closable :closed=\"closed\" @close=\"handleClose\">可关闭标签</Tag>\n</template>",
+            "tags": [
+                "closable",
+                "close"
+            ],
+            "usedProps": [
+                "closable",
+                "closed"
+            ],
+            "usedEvents": [
+                "close"
+            ],
+            "usedMethods": [],
+            "scenario": "创建可以关闭的标签"
+        },
+        {
+            "id": "tag_border",
+            "title": "带边框标签",
+            "description": "使用不同边框样式的标签",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Tag } from '@king-design/vue';\n</script>\n<template>\n  <Tag border=\"solid\">实线边框</Tag>\n  <Tag border=\"dashed\">虚线边框</Tag>\n  <Tag border=\"solid\" type=\"primary\">主要边框</Tag>\n</template>",
+            "tags": [
+                "border",
+                "solid",
+                "dashed"
+            ],
+            "usedProps": [
+                "border",
+                "type"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "创建带有边框的标签"
+        },
+        {
+            "id": "tag_sizes",
+            "title": "不同尺寸",
+            "description": "展示不同尺寸的标签",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Tag } from '@king-design/vue';\n</script>\n<template>\n  <Tag size=\"large\">大标签</Tag>\n  <Tag size=\"default\">默认标签</Tag>\n  <Tag size=\"small\">小标签</Tag>\n  <Tag size=\"mini\">迷你标签</Tag>\n</template>",
+            "tags": [
+                "size",
+                "large",
+                "small",
+                "mini"
+            ],
+            "usedProps": [
+                "size"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "使用不同尺寸的标签"
+        },
+        {
+            "id": "tag_group",
+            "title": "标签组",
+            "description": "使用 Tags 组件管理标签组",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Tags, Tag } from '@king-design/vue';\n</script>\n<template>\n  <Tags>\n    <Tag>标签1</Tag>\n    <Tag>标签2</Tag>\n    <Tag>标签3</Tag>\n    <Tag>标签4</Tag>\n    <Tag>标签5</Tag>\n  </Tags>\n</template>",
+            "tags": [
+                "Tags",
+                "group"
+            ],
+            "usedProps": [],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "使用标签组管理多个标签"
+        },
+        {
+            "id": "tag_nowrap",
+            "title": "单行标签组",
+            "description": "超出隐藏并显示隐藏数量",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Tags, Tag } from '@king-design/vue';\n</script>\n<template>\n  <div style=\"width: 300px;\">\n    <Tags nowrap>\n      <Tag>标签1</Tag>\n      <Tag>标签2</Tag>\n      <Tag>标签3</Tag>\n      <Tag>标签4</Tag>\n      <Tag>标签5</Tag>\n      <Tag>标签6</Tag>\n    </Tags>\n  </div>\n</template>",
+            "tags": [
+                "nowrap",
+                "overflow"
+            ],
+            "usedProps": [
+                "nowrap"
+            ],
+            "usedEvents": [],
+            "usedMethods": [],
+            "scenario": "在有限空间内展示标签，超出部分显示数量"
+        },
+        {
+            "id": "tag_draggable",
+            "title": "可拖拽排序",
+            "description": "支持拖拽排序的标签组",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Tags, Tag, Message } from '@king-design/vue';\n\nconst tags = ref(['标签1', '标签2', '标签3', '标签4']);\n\nconst handleDragEnd = ({from, to}: {from: number; to: number}) => {\n  const tag = tags.value.splice(from, 1)[0];\n  tags.value.splice(to, 0, tag);\n  Message.success(`从 ${from} 移动到 ${to}`);\n};\n</script>\n<template>\n  <Tags draggable @dragend=\"handleDragEnd\">\n    <Tag v-for=\"tag in tags\" :key=\"tag\">{{ tag }}</Tag>\n  </Tags>\n</template>",
+            "tags": [
+                "draggable",
+                "drag",
+                "sort"
+            ],
+            "usedProps": [
+                "draggable"
+            ],
+            "usedEvents": [
+                "dragend"
+            ],
+            "usedMethods": [],
+            "scenario": "创建支持拖拽排序的标签组"
+        },
+        {
+            "id": "tag_dynamic",
+            "title": "动态编辑标签",
+            "description": "动态添加和删除标签",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { Tags, Tag, Button, Input } from '@king-design/vue';\n\nconst tags = ref(['标签1', '标签2']);\nconst inputValue = ref('');\n\nconst handleClose = (index: number) => {\n  tags.value.splice(index, 1);\n};\n\nconst handleAdd = () => {\n  if (inputValue.value) {\n    tags.value.push(inputValue.value);\n    inputValue.value = '';\n  }\n};\n</script>\n<template>\n  <Tags>\n    <Tag v-for=\"(tag, index) in tags\" :key=\"tag\" \n      closable @close=\"handleClose(index)\">{{ tag }}</Tag>\n    <template #append>\n      <Input v-model=\"inputValue\" :width=\"100\" size=\"mini\" \n        placeholder=\"新标签\" @keydown.enter=\"handleAdd\" />\n    </template>\n  </Tags>\n</template>",
+            "tags": [
+                "dynamic",
+                "add",
+                "delete"
+            ],
+            "usedProps": [
+                "closable"
+            ],
+            "usedEvents": [
+                "close"
+            ],
+            "usedMethods": [],
+            "scenario": "动态添加和删除标签的完整示例"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "tag_closable_controlled",
+            "description": "可关闭标签未使用受控模式",
+            "wrongCode": "<Tag closable>标签</Tag>",
+            "correctCode": "<Tag closable :closed=\"isClosed\" @close=\"handleClose\">标签</Tag>",
+            "explanation": "closable 只显示关闭按钮，需要配合 closed 属性和 @close 事件来控制关闭行为",
+            "relatedProps": [
+                "closable",
+                "closed"
+            ]
+        },
+        {
+            "id": "tag_type_typo",
+            "description": "使用不存在的 type 值",
+            "wrongCode": "<Tag type=\"info\">信息标签</Tag>",
+            "correctCode": "<Tag type=\"primary\">主要标签</Tag>",
+            "explanation": "Tag 的 type 只支持 default, primary, success, warning, danger，不存在 info 值",
+            "relatedProps": [
+                "type"
+            ]
+        },
+        {
+            "id": "tag_draggable_missing_key",
+            "description": "拖拽标签组未设置 key",
+            "wrongCode": "<Tags draggable>\n  <Tag v-for=\"tag in tags\">{{ tag }}</Tag>\n</Tags>",
+            "correctCode": "<Tags draggable>\n  <Tag v-for=\"tag in tags\" :key=\"tag\">{{ tag }}</Tag>\n</Tags>",
+            "explanation": "使用拖拽功能时，每个 Tag 必须有唯一的 key",
+            "relatedProps": [
+                "draggable"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "标签",
+        "tag",
+        "tags",
+        "分类",
+        "标记",
+        "关闭",
+        "closable",
+        "拖拽",
+        "draggable"
+    ],
+    "useCases": [
+        "文章标签分类",
+        "商品标签",
+        "用户标签",
+        "动态添加删除标签",
+        "标签筛选器",
+        "可排序的标签列表"
+    ],
+    "relatedComponents": [
+        "Tags",
+        "Badge"
+    ]
+}