@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.13

package/Menu/component.json

@@ -0,0 +1,180 @@
+{
+    "name": "Menu",
+    "category": "Navigation",
+    "description": "为页面和功能提供导航的菜单列表",
+    "semantic": {
+        "intent": [
+            "页面导航",
+            "功能索引",
+            "模块切换"
+        ],
+        "useCases": [
+            "侧边栏导航",
+            "顶部菜单",
+            "系统功能入口"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "vertical": {
+            "meaning": "垂直菜单（侧边）"
+        },
+        "horizontal": {
+            "meaning": "水平菜单（顶部）"
+        },
+        "inline": {
+            "meaning": "内嵌菜单"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed",
+        "selected"
+    ],
+    "idealProps": {
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "**菜单列表核心配置（src/Menu/index.tsx:19,71-82 实证，src/Menu/interface.ts:67-90 MenuListProps 定义）**。⚠️ **菜单数据源通过此 prop 的 `list` 字段传入，而非顶层 `list` prop**（顶层无 list prop）。MenuListProps 主要字段：`list: MenuChildrenProps[]`（菜单项数组）、`jumpIcon: ReactNode`（菜单分享图标）、`onClickJump: (item) => void`（分享点击回调）、`size`/`color`/`expansion`/`selectMenu`/`onClickMenu`/`shrinkOthers`（由 Menu 顶层 prop 自动下透，一般不需要在此重复传）",
+            "objectShape": {
+                "list": { "type": "MenuChildrenProps[]", "description": "菜单项数组（MenuChildrenProps 核心字段见下方 subComponents）" },
+                "jumpIcon": { "type": "ReactNode", "description": "菜单项右侧分享/跳转图标" },
+                "onClickJump": { "type": "(item: MenuChildrenProps) => void", "description": "点击分享图标回调" }
+            }
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中的菜单 key/path（src/Menu/index.tsx:21,77 实证：向下透传给 VerticalMenuList，与 MenuChildrenProps 的 path 字段比对高亮）"
+        },
+        "expansion": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否展开菜单（src/Menu/index.tsx:20,31-33 实证：受控，变化后同步到内部 expansionCom state）"
+        },
+        "color": {
+            "type": "enum",
+            "values": ["deep", "light"],
+            "default": "deep",
+            "description": "菜单主题色（src/Menu/interface.ts:12 ColorType 实证：'deep'=深色主题，'light'=浅色主题；透传 CSS 类 paraui-v4-vertical-menu-{color}）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "large"],
+            "default": "large",
+            "description": "菜单尺寸（src/Menu/index.tsx:17,50 实证：控制 CSS 类 paraui-v4-vertical-menu-{size}）"
+        },
+        "onClickMenu": {
+            "type": "function",
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "description": "点击菜单项回调（src/Menu/interface.ts:173-174 MenuProps 实证：参数为点击的 MenuChildrenProps 对象或 false；false 表示点击了非叶子节点的折叠操作）"
+        },
+        "shrinkOthers": {
+            "type": "boolean",
+            "default": true,
+            "description": "展开一个菜单时自动收起其他展开的同级菜单（src/Menu/index.tsx:26,78 实证，透传给 VerticalMenuList）"
+        },
+        "logoProps": {
+            "type": "LogoProps",
+            "objectShape": {
+                "expansion": { "type": "boolean", "description": "Logo 展开/收起状态（由 Menu 自动传入，一般不手动传）" },
+                "render": { "type": "ReactNode", "description": "自定义 Logo 内容区域" },
+                "className": { "type": "string", "description": "Logo 区域自定义 class" }
+            },
+            "description": "Logo 区域配置（src/Menu/interface.ts:15-22 LogoProps 实证，src/Menu/index.tsx:18,57-66 实证：logoProps 存在时渲染 Logo 子组件）"
+        },
+        "footerExpansionProps": {
+            "type": "FooterExpansionProps",
+            "description": "底部展开/收起按钮区域配置（src/Menu/index.tsx:27,87-94 实证，src/Menu/interface.ts:127-145 FooterExpansionProps 定义）。主要字段：`expandIcon: ReactNode`（展开图标）、`shrinkIcon: ReactNode`（收起图标）、`render: ReactNode`（完全自定义底部内容替换默认按钮）、`version: ReactNode`（版本号显示）、`className: string`（底部区域 class）",
+            "objectShape": {
+                "expandIcon": { "type": "ReactNode", "description": "展开状态图标" },
+                "shrinkIcon": { "type": "ReactNode", "description": "收起状态图标" },
+                "render": { "type": "ReactNode", "description": "完全自定义底部内容" },
+                "version": { "type": "ReactNode", "description": "版本号展示" },
+                "className": { "type": "string", "description": "底部区域自定义 class" }
+            }
+        },
+        "showExpansion": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示底部展开/收起按钮（src/Menu/index.tsx:28,87 实证：false 时 FooterExpansion 不渲染）"
+        },
+        "onClickExpansion": {
+            "type": "function",
+            "signature": "(expansion: boolean) => void",
+            "description": "点击底部展开/收起按钮回调（src/Menu/index.tsx:22,39-41 实证：参数为点击后新的展开状态 boolean）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Menu/index.tsx:24,49 实证，追加到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Menu/index.tsx:25,100 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "保持菜单层级不要过深（建议不超过 3 级）",
+        "配置 shrinkOthers 以提升用户查找效率",
+        "使用 icon 辅助识别菜单项",
+        "**菜单数据通过 menuListProps.list 传入**（不是顶层 list prop）：`<Menu menuListProps={{ list: menuData }} />`，menuData 是 MenuChildrenProps[] 数组",
+        "MenuChildrenProps 核心字段（src/Menu/interface.ts:25-63）：`label: ReactNode`（菜单名），`path: string`（路径，与 selectMenu 比对高亮），`icon: ReactNode`（图标），`children: MenuChildrenProps[]`（子菜单），`type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'`（菜单类型），`href: string`（a 标签地址），`badge: ReactNode`（标记）"
+    ],
+    "dont": [
+        "在菜单项中放置非导航类的复杂交互组件",
+        "过度使用动态生成的菜单导致性能问题",
+        "把菜单数据传给顶层 list prop——Menu 没有顶层 list prop,数据必须通过 menuListProps.list 传入"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击叶子菜单项时 item 是该菜单项的 MenuChildrenProps 对象,包含 label/path/type 等字段",
+                "点击非叶子节点(有 children 的菜单项)展开/收起时,item 可能为 false",
+                "用 path 字段实现路由跳转:onClickMenu={(item) => item && item.path && navigate(item.path)}"
+            ],
+            "commonMistakes": [
+                "假设参数是字符串 key 或 path——实际是整个 MenuChildrenProps 对象或 false,需要取 item.path 或 item.label",
+                "不处理 item 为 false 的情况——点击有子菜单的父节点时 item 是 false,直接访问 item.path 会报错",
+                "假设 onClickMenu 只在叶子节点触发——父节点展开/收起时也会触发(item=false)"
+            ]
+        },
+        "onClickExpansion": {
+            "signature": "(expansion: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击底部展开/收起按钮时触发:expansion 是点击后新的展开状态",
+                "与 expansion prop 配合实现受控:onClickExpansion={(v) => setExpanded(v)}"
+            ],
+            "commonMistakes": [
+                "假设参数是事件对象 → 实际只有 boolean 一个参数(新的展开状态)",
+                "只传 expansion 不传 onClickExpansion → 底部按钮点击无响应(受控模式下 expansion 不更新)"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onClickMenu 参数类型是 MenuChildrenProps | false,必须判空后才能访问其属性",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false,直接访问 item.path 运行时报错",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "菜单数据通过 menuListProps.list 传入,顶层没有 list prop",
+            "wrong": "<Menu list={menuData} />  // TS 报错:list 不在 MenuProps 中",
+            "right": "<Menu menuListProps={{ list: menuData }} />  // menuData 是 MenuChildrenProps[] 类型"
+        },
+        {
+            "issue": "MenuChildrenProps 的 [name: string]: unknown 索引签名允许任意字段,但核心字段类型有约束",
+            "wrong": "const item: MenuChildrenProps = { label: '首页', type: 'page' }  // 'page' 不在 MenuListTypeType 枚举中",
+            "right": "const item: MenuChildrenProps = { label: '首页', type: 'router', path: '/home' }  // type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'"
+        },
+        {
+            "issue": "color prop 只有 'deep' 和 'light' 两个有效值(ColorType),传其他字符串 TS 报错",
+            "wrong": "color='dark'  // TS2322: Type '\"dark\"' is not assignable to type 'ColorType'",
+            "right": "color='deep'  // 合法值: 'deep'(深色主题) | 'light'(浅色主题)"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Menu",
+        "adapter": null
+    }
+}

package/Message/component.json

@@ -0,0 +1,246 @@
+{
+    "name": "Message",
+    "category": "Feedback",
+    "description": "全局展示操作反馈信息(顶部条状提示)。**通过 4 个静态方法触发,非 React 组件挂载**。**关键 API 形态:`Message.{type}(config, duration?)` —— config 是 MsgTypeProps 对象或纯 string,duration 是【独立的第 2 参数】,不是 MsgTypeProps 的字段**(见 commonMisconceptions.M1)",
+    "semantic": {
+        "intent": [
+            "通知用户操作结果",
+            "瞬态状态提示",
+            "顶部条状反馈"
+        ],
+        "useCases": [
+            "提交成功 / 失败反馈",
+            "操作警告(无需用户确认的轻提示)",
+            "瞬态错误信息",
+            "loading 场景(workaround,无原生 loading 类型,见 limitations.L2)"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**4 类型 × 2 参数签名**:\n```\nMessage.info(config, duration?)\nMessage.success(config, duration?)\nMessage.warn(config, duration?)\nMessage.error(config, duration?)\n```\n- `config: string | MsgTypeProps` —— 字符串(直接当 text)或对象(完整配置)\n- `duration?: number` —— **独立第 2 参数**(毫秒),默认 5000,传 0 / 负数 / NaN 时不自动关闭\n\n**3 个全局方法**:\n```\nMessage.clear()       // 关闭当前所有 Message\nMessage.destroyAll()  // clear 的别名\nMessage.config({ maxCount?, duration? })  // 修改全局默认值\n```",
+    "limitations": {
+        "L1_no_onClose_callback": {
+            "issue": "**MsgTypeProps 不支持 onClose / onDismiss / onAfterClose 回调** —— 用户手动关闭或自动关闭后无法触发回调",
+            "rootCause": "src/Message/index.tsx 未暴露 callback 字段",
+            "workaround": "如果业务需要'关闭后执行 X':\n1. **如果是自动关闭**:用 `setTimeout(handler, duration)` 自己计时(精度误差 ~50ms)\n2. **如果是手动关闭(close 按钮)**:Message 本身没法监听,需要换 Toast / Snackbar / Modal 组件"
+        },
+        "L2_no_loading_variant": {
+            "issue": "**没有 Message.loading 方法 / loading variant** —— variants 只有 info/success/warn/error 4 种",
+            "rootCause": "src/Message/index.tsx 未实现 loading 静态方法",
+            "workaround": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)`(duration=0 不自动关闭),loading 完成后调 `Message.clear()` 关闭。**注意**:icon prop 需要传入 Loading 图标组件 ReactNode",
+            "alternative": "需要真正的 loading 视觉(spinner / 进度) → 用 Loading 组件 / Spin 组件,不要硬塞 Message"
+        }
+    },
+    "variants": {
+        "info": {
+            "meaning": "普通信息(蓝色 i 图标)"
+        },
+        "success": {
+            "meaning": "操作成功(绿色 ✓ 图标)"
+        },
+        "warn": {
+            "meaning": "警告(黄色 ! 图标)"
+        },
+        "error": {
+            "meaning": "错误(红色 × 图标)"
+        }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "text": {
+            "type": "string",
+            "description": "主文本(标题)。也可以把整个 config 简化成纯字符串:`Message.info('提交成功', 3000)` 等同于 `Message.info({ text: '提交成功' }, 3000)`"
+        },
+        "desc": {
+            "type": "string",
+            "description": "副描述文案;**出现时 text 会自动加粗变标题**,desc 作为下方说明文本"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标(覆盖 type 默认图标)。loading 场景常传入 `<Loading />` 图标组件配合 duration=0。**与 hideIcon 互斥**(同时传 hideIcon 优先)"
+        },
+        "hideIcon": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏图标,显示纯文本提示。**与 icon 互斥**"
+        },
+        "close": {
+            "type": "boolean",
+            "description": "**强制显示关闭按钮**。undefined 时按 duration 推断:duration>0 不显示关闭按钮(自动关闭即可),duration<=0 或 NaN 显示关闭按钮(需要用户手动关闭)"
+        },
+        "maxCount": {
+            "type": "number",
+            "default": "Infinity",
+            "description": "同时显示最大条数。per-call(MsgTypeProps.maxCount)或全局(Message.config({ maxCount: N }))"
+        },
+        "html": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否把 text 当 innerHTML 渲染。**仅可信来源使用**(避免 XSS)"
+        },
+        "className": {
+            "type": "string",
+            "description": "提示容器的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "提示容器的 style"
+        }
+    },
+    "staticMethods": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "callExample": "// 正确:\nMessage.info('提交成功', 3000)\nMessage.info({ text: '提交成功', desc: '已保存到草稿' }, 3000)\nMessage.info({ text: '加载中', icon: <Loading />, close: true }, 0)\n\n// 错误(M1):\nMessage.info({ text: '提交成功', duration: 3000 })  // ❌ duration 不是 MsgTypeProps 的字段!"
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "clear": {
+            "signature": "() => void",
+            "description": "关闭当前页面所有 Message 实例"
+        },
+        "destroyAll": {
+            "signature": "() => void",
+            "description": "clear 的别名(deprecated 倾向 —— **新代码推荐 clear**)"
+        },
+        "config": {
+            "signature": "(config: { maxCount?: number; duration?: number }) => void",
+            "description": "修改全局默认值(影响后续 Message.{type} 调用)"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 duration 写进 MsgTypeProps 对象: `Message.info({ text: '提交成功', duration: 3000 })`",
+            "result": "**TS 报错 TS2353 'duration does not exist in type MsgTypeProps'** —— R23 Message-005 fail 根因",
+            "fix": "duration 是 Message.{type}() 的**独立第 2 参数**: `Message.info({ text: '提交成功' }, 3000)` 或纯字符串形式 `Message.info('提交成功', 3000)`"
+        },
+        "M2": {
+            "wrong": "传 onClose / onDismiss / onAfterClose 回调期望关闭时触发: `Message.info({ text: '已删除', onClose: handleAfterClose })`",
+            "result": "**MsgTypeProps 无 callback 字段**——TS 报错 或者字段被静默忽略,handleAfterClose 永不触发(L1)",
+            "fix": "1. 自动关闭后回调:用 `setTimeout(handleAfterClose, duration)`(精度 ~50ms 误差)。2. 手动关闭监听:Message 不支持,换 Toast / Snackbar"
+        },
+        "M3": {
+            "wrong": "调用 `Message.loading('加载中...', 0)` 期望显示 loading 类型",
+            "result": "**Message 没有 loading 静态方法**(只有 info/success/warn/error)——runtime 报 `Message.loading is not a function`(L2)",
+            "fix": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)` workaround(duration=0 + Loading 图标),完成后 `Message.clear()`。或者用真正的 Loading 组件而不是 Message"
+        },
+        "M4": {
+            "wrong": "默认 duration 是 0(永远不自动关闭): `Message.info('已保存')` 期望一直显示",
+            "result": "默认 duration = 5000 ms(自动 5 秒后关闭) —— `Message.info('已保存')` 会 5 秒后消失",
+            "fix": "想永久显示用 `Message.info('已保存', 0)` 或显式传 `0` / 负数 / NaN"
+        },
+        "M5": {
+            "wrong": "用 `Message.config({ duration: 0 })` 永久禁用全局自动关闭,然后期望每次 `Message.info('x')` 不自动消失",
+            "result": "**Message.config 修改的是全局默认值**,生效但 per-call 第 2 参数会覆盖。可以用,但容易和 per-call duration 互相覆盖出 bug",
+            "fix": "per-call 显式传 duration 更直观: `Message.info('x', 0)`。全局 config 适合统一调小默认 duration(如 3000)"
+        }
+    },
+    "completeExample": "// 1. 最基础:字符串简写 + 默认 5 秒自动关闭\nimport Message from '@para-ui/core/Message';\nMessage.info('提交成功');\nMessage.success('保存成功', 3000);  // 3 秒后自动关闭\n\n// 2. 完整对象配置(text + desc + icon)\nMessage.info({\n    text: '操作成功',\n    desc: '订单 #1234 已提交,5 个工作日内处理完成'\n}, 8000);\n\n// 3. 不自动关闭 + 显示关闭按钮\nMessage.warn({\n    text: '需要用户确认',\n    close: true\n}, 0);  // duration=0 不自动关闭\n\n// 4. loading 场景 workaround (L2)\nimport Loading from '@para-ui/icons/Loading';\nMessage.info({\n    text: '上传中...',\n    icon: <Loading />,\n    close: false\n}, 0);  // duration=0 不自动关闭\n// 上传完成后:\nawait uploadFile();\nMessage.clear();\nMessage.success('上传成功', 2000);\n\n// 5. 关闭回调 workaround (L1)\nMessage.info('已保存', 3000);\nsetTimeout(() => onAfterClose(), 3000);  // 自己计时,精度 ~50ms\n\n// 6. 全局配置\nMessage.config({ duration: 3000, maxCount: 3 });  // 后续 Message 默认 3 秒,最多 3 条同显",
+    "do": [
+        "**优先用字符串简写**: `Message.info('提交成功', 3000)` —— 不需要对象时省心",
+        "**duration 永远是第 2 参数**(M1) —— 不要写在 MsgTypeProps 对象里",
+        "**长内容用 text + desc 双字段**,desc 出现时 text 自动加粗",
+        "**永久显示**:传 duration=0 / 负数 / NaN,通常配合 close=true 让用户手动关闭",
+        "**全局默认值调整**:用 Message.config({ duration, maxCount }),只在 app 启动时调一次",
+        "loading 场景:用 info + Loading icon + duration=0 workaround(L2)"
+    ],
+    "dont": [
+        "**不要**把 duration 写在 MsgTypeProps 对象里——是第 2 参数(M1,这是 R23 Message-005 fail 根因)",
+        "**不要**传 onClose / onDismiss 回调——MsgTypeProps 无 callback 字段(M2,L1)",
+        "**不要**调 Message.loading —— 不存在,用 info + icon workaround(M3,L2)",
+        "**不要**假设默认 duration 是 0——默认 5000 ms(M4)",
+        "在 Message 中展示过多文字 / 表单 / 复杂交互 —— 换 Modal",
+        "滥用 error 类型 —— 重要错误应结合页面内错误提示"
+    ],
+    "events": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.info('操作成功')  — 字符串简写,默认 5000ms 自动关闭",
+                "Message.info({ text: '操作成功', desc: '已保存到草稿' }, 3000)  — 对象配置 + 独立 duration 第 2 参数",
+                "Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)  — duration=0 不自动关闭,显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "把 duration 写进 MsgTypeProps 对象:Message.info({ text: '成功', duration: 3000 }) → TS2353 报错,duration 不是 MsgTypeProps 字段",
+                "调用 Message.loading() → Message 没有 loading 方法,只有 info/success/warn/error,调用报 'not a function'",
+                "传 onClose/onAfterClose 回调 → MsgTypeProps 无 callback 字段,静默忽略,回调永不触发"
+            ]
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.success('保存成功', 2000)  — 2 秒后自动关闭",
+                "Message.success({ text: '上传完成', desc: '共 3 个文件' })  — 含副描述"
+            ],
+            "commonMistakes": [
+                "假设 success 和 info 签名不同 → 4 种类型签名完全相同,都是 (config, duration?) => void"
+            ]
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.warn({ text: '需要确认', close: true }, 0)  — 永久显示 + 显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "传 onClose 期望点击关闭按钮后回调 → 不支持 onClose,只能用 setTimeout 模拟"
+            ]
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.error('操作失败,请重试', 8000)  — 错误类型展示 8 秒"
+            ],
+            "commonMistakes": [
+                "假设 error 方法接受 Error 对象 → config 必须是 string 或 MsgTypeProps,需手动取 error.message"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 是 Message.{type}() 的独立第 2 参数,不是 MsgTypeProps 对象的字段",
+            "wrong": "Message.info({ text: '操作成功', duration: 3000 })  // TS2353: 'duration' does not exist in type MsgTypeProps",
+            "right": "Message.info({ text: '操作成功' }, 3000)  // 或 Message.info('操作成功', 3000)"
+        },
+        {
+            "issue": "MsgTypeProps 不含 onClose / onAfterClose / onDismiss 回调字段",
+            "wrong": "Message.success({ text: '已删除', onClose: () => refetch() })  // TS 报错 或 字段静默被忽略",
+            "right": "Message.success('已删除', 3000); setTimeout(() => refetch(), 3000);  // 用 setTimeout 自己计时"
+        },
+        {
+            "issue": "Message 没有 loading 静态方法(只有 info/success/warn/error)",
+            "wrong": "Message.loading('上传中...')  // 运行时 TypeError: Message.loading is not a function",
+            "right": "Message.info({ text: '上传中...', close: false }, 0);  // duration=0 + 用 Message.clear?.() 关闭"
+        },
+        {
+            "issue": "MessageObject 导出的是对象实例,不是 React 组件,不能写 <Message> JSX",
+            "wrong": "import Message from '@para-ui/core/Message'; return <Message type='success' text='ok' />;  // JSX 类型错误",
+            "right": "import { Message } from '@para-ui/core/Message'; Message.success('ok');  // 命令式调用,不是 JSX 渲染"
+        },
+        {
+            "issue": "从 @para-ui/core 直接导入 Message 拿到的是 JSX 组件(默认导出)，不是 MessageObject，所有方法 success/error/info/warn/clear/config 均不存在",
+            "wrong": "import { Message } from '@para-ui/core';  // TS2339: Property 'success' does not exist on type '() => Element'",
+            "right": "import { Message } from '@para-ui/core/Message';  // 子路径导入拿到具名 MessageObject 实例"
+        },
+        {
+            "issue": "MessageObject 接口的 clear 和 config 是可选方法（带 ?），直接调用不加可选链会报 TS2722",
+            "wrong": "Message.clear();   // TS2722: Cannot invoke an object which is possibly 'undefined'\nMessage.config({ duration: 3000 });  // 同上",
+            "right": "Message.clear?.();   // 可选链调用\nMessage.config?.({ duration: 3000 });  // 或先检查: if (Message.config) Message.config({ duration: 3000 })"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Message",
+        "adapter": null
+    }
+}