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

package/Notification/component.json

@@ -0,0 +1,184 @@
+{
+    "name": "Notification",
+    "category": "Feedback",
+    "description": "全局通知提醒框，通过命令式 API（Notification.open / .success / .info / .warning / .error）触发，支持角落定位、标题 + 内容 + 操作按钮、可关闭回调、key 管理",
+    "semantic": {
+        "intent": [
+            "系统通知",
+            "重要提醒",
+            "复杂反馈"
+        ],
+        "useCases": [
+            "系统升级通知",
+            "后台任务完成提醒",
+            "带操作按钮的系统消息"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**命令式 API，不是 React 组件**。调用方式:\n```\nNotification.success({ message: '标题', description: '内容', duration: 3 })\nNotification.info({ message: '提示', description: '详情' })\nNotification.warning({ message: '警告', description: '说明' })\nNotification.error({ message: '错误', description: '信息' })\nNotification.open({ message: '标题', description: '内容', type: 'success' })  // open 是 success/info/warning/error 的底层\nNotification.close('my-key')  // 关闭指定 key 的通知\nNotification.destroy()  // 关闭所有通知\nNotification.config({ placement, top, maxCount, duration })  // 全局配置\n```\n**duration 单位是秒**（与 Message.duration 毫秒不同！）。默认 5 秒自动关闭；传 null 不自动关闭。",
+    "variants": {
+        "success": { "meaning": "成功（绿色 ✓ 图标）" },
+        "info": { "meaning": "普通信息（蓝色 i 图标）" },
+        "warning": { "meaning": "警告（黄色 ! 图标）" },
+        "error": { "meaning": "错误（红色 × 图标）" }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "message": {
+            "type": "ReactNode",
+            "description": "通知标题（必填），通知卡片上方的粗体文字"
+        },
+        "description": {
+            "type": "ReactNode",
+            "description": "通知正文内容；与 message 同时出现时，message 作为标题，description 作为正文"
+        },
+        "duration": {
+            "type": "number | null",
+            "default": 5,
+            "description": "**自动关闭延时，单位秒**（注意：与 Message 组件的毫秒单位不同！）；传 null 不自动关闭（需用户点击关闭按钮或调用 Notification.close(key)）"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["topLeft", "topRight", "bottomLeft", "bottomRight"],
+            "default": "topRight",
+            "description": "弹出位置，4 个角落，topRight 最常用"
+        },
+        "key": {
+            "type": "string",
+            "description": "通知唯一标志；传了 key 才能用 Notification.close(key) 程序性关闭；同一 key 再次 open 会更新已有通知"
+        },
+        "onClose": {
+            "type": "() => void",
+            "description": "关闭时触发（自动关闭 + 用户手动关闭都触发）"
+        },
+        "onClick": {
+            "type": "() => void",
+            "description": "点击通知内容区域（非关闭按钮）时触发"
+        },
+        "btn": {
+            "type": "ReactNode",
+            "description": "通知卡片底部自定义操作区域（如 '立即更新' 按钮）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标，覆盖 type 默认图标"
+        },
+        "top": {
+            "type": "number",
+            "default": 20,
+            "description": "topLeft/topRight 时距顶部距离（px）"
+        },
+        "bottom": {
+            "type": "number",
+            "default": 20,
+            "description": "bottomLeft/bottomRight 时距底部距离（px）"
+        },
+        "getContainer": {
+            "type": "() => HTMLElement",
+            "description": "渲染容器，默认 document.body"
+        }
+    },
+    "commonPatterns": {
+        "basic": "Notification.success({ message: '操作成功', description: '数据已保存', duration: 3 })",
+        "persistent": "Notification.warning({ message: '需要确认', description: '请及时处理', duration: null, key: 'warn-1' });\n// 处理完成后：\nNotification.close('warn-1');",
+        "withButton": "Notification.info({\n    message: '发现新版本',\n    description: 'v2.0.0 已发布',\n    duration: null,\n    key: 'update',\n    btn: <Button onClick={() => { window.open(releaseUrl); Notification.close('update'); }}>立即更新</Button>\n});",
+        "globalConfig": "Notification.config({ placement: 'topRight', top: 60, maxCount: 5, duration: 3 });"
+    },
+    "commandApi": {
+        "Notification.open": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "打开通知，所有 ideaProps 字段均为 ArgsProps 的字段"
+        },
+        "Notification.success": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "等价于 Notification.open({...args, type: 'success'})"
+        },
+        "Notification.info": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.warning": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "Notification.warn 是 Notification.warning 的别名"
+        },
+        "Notification.error": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.close": {
+            "signature": "(key: string) => void",
+            "description": "关闭指定 key 的通知，遍历所有 placement 实例"
+        },
+        "Notification.destroy": {
+            "signature": "() => void",
+            "description": "销毁所有通知实例（包括已显示的和正在动画的）"
+        },
+        "Notification.config": {
+            "signature": "(options: ConfigProps) => void",
+            "description": "全局配置，应用入口调用一次"
+        }
+    },
+    "do": [
+        "用于比 Message 更重要的、需要用户关注的全局通知（如系统升级、任务完成）",
+        "**duration 单位是秒**（默认 5），不是毫秒——与 Message 组件不同",
+        "需要程序性关闭时传 key 字段并用 Notification.close(key)",
+        "App 入口调用 Notification.config 设置全局 placement / maxCount / duration"
+    ],
+    "dont": [
+        "频繁使用 Notification 打断用户操作——轻提示用 Message，重要操作确认用 FunctionModal",
+        "堆叠过多——配合 maxCount 限制同时显示数量",
+        "把 duration 写成毫秒——duration 是秒，写 3000 会导致通知 3000 秒后才关闭"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '提示', onClose: () => console.log('已关闭') }) — 自动关闭和手动关闭都触发",
+                "持久通知 + 关闭回调：Notification.warning({ message: '警告', duration: null, key: 'w1', onClose: () => markAsRead() })",
+                "配合 key 程序关闭：Notification.close('w1') 也会触发 onClose"
+            ],
+            "commonMistakes": [
+                "期望 onClose 签名是 (e) => void——实际无参 () => void",
+                "传了 onClose 但没有显式关闭路径——duration=null 时通知不自动关闭，onClose 永不触发（除非用户点 × 或程序调用 close）",
+                "在 onClose 里再次调 Notification.open 期望实现替换效果——会新开一条通知，建议用 key 复用已有实例"
+            ]
+        },
+        "onClick": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '新消息', onClick: () => router.push('/messages') }) — 点击跳转",
+                "onClick 不关闭通知——需在 onClick 里手动调 Notification.close(key) 或让 duration 到期",
+                "onClick 和 btn 的 onClick 独立——通知区域点击 + 底部按钮点击是两个独立事件"
+            ],
+            "commonMistakes": [
+                "期望点击通知后自动关闭——onClick 不触发关闭，需在 onClick 里手动 Notification.close(args.key)",
+                "在 btn 里写关闭逻辑而不传 key——没有 key 就无法调 Notification.close，需预先生成 key",
+                "期望 onClick 阻止通知关闭——点击关闭按钮（×）触发的是关闭逻辑，不能被 onClick 拦截"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 单位是秒，不是毫秒——与 Message 不一致是常见陷阱",
+            "wrong": "Notification.success({ message: '成功', duration: 3000 }) // 3000 秒后才关闭！不是 3 秒",
+            "right": "Notification.success({ message: '成功', duration: 3 }) // 3 秒后自动关闭"
+        },
+        {
+            "issue": "Notification 是命令式 API，default export 是 api 对象，不是 React 组件，不能写 JSX",
+            "wrong": "import Notification from '@para-ui/core/Notification'; return <Notification message='提示' />; // JSX 类型错误",
+            "right": "import Notification from '@para-ui/core/Notification'; Notification.info({ message: '提示' }); // 命令式调用"
+        },
+        {
+            "issue": "message 类型是 ReactNode，但 ArgsProps 中 message 是必填字段，不传会导致 TS 报错",
+            "wrong": "Notification.open({ description: '内容' }) // TS2345: Property 'message' is missing",
+            "right": "Notification.open({ message: '标题', description: '内容' }) // message 必填"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Notification",
+        "adapter": null
+    }
+}

package/OperateBtn/component.json

@@ -0,0 +1,134 @@
+{
+    "name": "OperateBtn",
+    "category": "General",
+    "description": "表格列操作按钮组，将多个行操作收纳为图标按钮 + 更多浮层，常配合 Table 使用",
+    "semantic": {
+        "intent": [
+            "行操作",
+            "批量操作",
+            "操作收纳"
+        ],
+        "useCases": [
+            "表格操作列",
+            "卡片操作区",
+            "工具栏"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "loading"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "OperateBtnListProps[]",
+            "itemSchema": {
+                "key": { "type": "string", "description": "唯一标识（与组件 key prop 配合，用于 loadingMapping 索引）" },
+                "label": { "type": "ReactNode", "description": "按钮显示文案" },
+                "icon": { "type": "ReactNode", "description": "按钮图标（外显按钮展示区域，显示 icon 而非 label）" },
+                "disabled": { "type": "boolean", "description": "是否禁用" },
+                "danger": { "type": "boolean", "description": "是否为危险按钮（红色）" },
+                "toolTipTitle": { "type": "ReactNode", "description": "hover tooltip 文案；外显按钮默认取 toolTipTitle ?? label 作 tooltip" },
+                "popConfirmProps": { "type": "PopConfirmProps", "description": "点击弹出气泡确认框的配置" },
+                "onClick": { "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean|any>", "description": "单项点击事件（优先级高于组件级 onClick）；Promise resolve(false) 关闭 loading" }
+            },
+            "description": "按钮列表配置（每项含 label/icon/key/disabled/danger/toolTipTitle/popConfirmProps/onClick）"
+        },
+        "showNum": {
+            "type": "number",
+            "default": 3,
+            "description": "前 N 个按钮外显，超出折叠到更多浮层；⚠️ 仅 list.length > showNum + 1 才出现更多按钮（差值严格大于 1），若 list.length === showNum+1 最后一个也外显不进更多"
+        },
+        "key": {
+            "type": "string",
+            "default": "key",
+            "description": "指定 list 项中作为 loadingMapping 索引的字段名（不是 React key，是 list 项对象里用于 loadingMapping 映射的字段路径名）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "small",
+            "description": "按钮大小；表格行内推荐 small"
+        },
+        "placement": {
+            "type": "Placement",
+            "default": "bottom-end",
+            "description": "外显按钮 Tooltip 及更多浮层的定位方向（src/OperateBtn/index.tsx:88 interface 实证，默认 bottom-end）"
+        },
+        "clickCloseMore": {
+            "type": "boolean",
+            "default": true,
+            "description": "点击 list 项后是否自动关闭更多浮层"
+        },
+        "onClick": {
+            "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "description": "组件级点击事件；list 项自带 item.onClick 时对本项失效（item.onClick 优先级更高）；非受控 loading 下 Promise resolve(false) 表示失败、保持按钮 loading；resolve(true/undefined) 关闭 loading"
+        },
+        "loadingMapping": {
+            "type": "{[name: string]: boolean}",
+            "description": "受控 loading 映射；键 = item[key] 字段值；传入后 onClick 返回值不再控制 loading，由外部控制"
+        },
+        "popoverClassName": {
+            "type": "string",
+            "description": "更多浮层的自定义 className（src/OperateBtn/index.tsx:73 interface 实证）"
+        }
+    },
+    "do": [
+        "表格行内操作首选 OperateBtn，将编辑/删除/查看等图标按钮组合为一组，超出 showNum 自动收纳到更多",
+        "危险操作（删除等）配合 list[i].popConfirmProps 弹二次确认，避免误操作",
+        "提供 loading 状态反馈：短请求用内置非受控 loading（onClick 返回 Promise），长请求或多处联动用 loadingMapping 受控",
+        "list 每项必须有 icon 或 toolTipTitle 其中之一，外显按钮以图标展示，tooltip 才能给用户提示操作语义"
+    ],
+    "dont": [
+        "不要在 loadingMapping 键中使用数组下标——键应匹配 item[key] 字段（默认 item.key），而非 list 索引",
+        "危险操作不加 popConfirmProps 确认直接删除",
+        "操作按钮超过 5 个不分组——超出部分应通过 showNum 折叠，或拆分为多个操作区"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "asyncSupported": true,
+            "examples": [
+                "基本同步点击：onClick={(item, e) => { handleAction(item); }}",
+                "异步操作自动 loading：onClick={async (item, e) => { await deleteRow(item.id); return true; }} // resolve(true) 关闭 loading",
+                "配合 key prop 做受控 loading：loadingMapping={{ [row.id]: isDeleting }} // 外部控制 loading 状态"
+            ],
+            "commonMistakes": [
+                "item.onClick 与组件级 onClick 混用——item.onClick 存在时组件级 onClick 对该项失效，二选一即可",
+                "期望 Promise resolve(false) 关闭 loading——resolve(false) 是失败语义，loading 保持；resolve(true/undefined) 才关闭",
+                "同时传 loadingMapping 又在 onClick 里 return Promise——传 loadingMapping 后 Promise 返回值不影响 loading，由外部 state 控制"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "OperateBtnListProps 的 key 字段与 React 的 key 属性同名但语义不同",
+            "wrong": "// 期望 React key：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}  // OperateBtn 的 key prop 用于 loadingMapping 索引，不是 React reconcile key",
+            "right": "// loadingMapping 键要和 list 项里的 key 字段值对应：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}\nloadingMapping={{ edit: isLoading }}"
+        },
+        {
+            "issue": "OperateBtnProps.key 是字符串（字段路径名），不是数组下标",
+            "wrong": "<OperateBtn key='id' list={list} loadingMapping={{ 0: true }} />  // 用数组下标做 mapping 键",
+            "right": "<OperateBtn key='id' list={list} loadingMapping={{ [list[0].id]: true }} />  // 键应是 item[keyProp] 的值"
+        },
+        {
+            "issue": "list 每项的 onClick 签名是 (item, e)，不是单参数 (e)",
+            "wrong": "list={[{ icon: <Edit />, onClick: (e) => e.stopPropagation() }]}  // 签名不匹配",
+            "right": "list={[{ icon: <Edit />, onClick: (item, e) => { e.stopPropagation(); handleEdit(item); } }]}"
+        },
+        {
+            "issue": "@para-ui/icons 中不存在 View 和 Share 图标，使用会导致 TS2307 模块找不到",
+            "wrong": "import View from '@para-ui/icons/View';  // TS2307: 找不到模块\nimport Share from '@para-ui/icons/Share'; // TS2307: 找不到模块",
+            "right": "import PreviewOpen from '@para-ui/icons/PreviewOpen';  // 查看/预览\nimport More from '@para-ui/icons/More';  // 更多操作\n// 可用图标：Edit, Delete, Copy, More, PreviewOpen, PreviewClose 等"
+        }
+    ],
+    "mapping": {
+        "realComponent": "OperateBtn",
+        "adapter": null
+    }
+}

package/PageHeader/component.json

@@ -0,0 +1,112 @@
+{
+    "name": "PageHeader",
+    "category": "Navigation",
+    "description": "页头(应用级顶部导航条):左侧 logo/标题 + 中间横向菜单 + 右侧用户/语言/帮助/按钮区",
+    "semantic": {
+        "intent": [
+            "应用顶部导航",
+            "横向菜单展示",
+            "用户/语言/帮助入口聚合"
+        ],
+        "useCases": [
+            "应用主页头",
+            "管理后台顶栏",
+            "工作台首屏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准页头(横向菜单 + 右侧功能区)"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "leftRender": {
+            "type": "ReactNode",
+            "description": "左侧自定义内容(放 logo / 应用标题 / 返回按钮等);**支持纯文本 / 单行 JSX / 多行复合 JSX**(标题+副标题、返回按钮+标题、面包屑+标题、标题+状态彩标);**注意:不是 title / subTitle / backIcon / breadcrumb / onBack prop**(这些 Ant Design PageHeader 命名本组件均不存在,需要时全部组合进 leftRender ReactNode);典型场景见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c/7d"
+        },
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "横向菜单配置对象;MenuListProps = { list?: MenuChildrenProps[]; selectMenu?: string; onClickMenu?: (item: MenuChildrenProps | false) => void; className?: string; moreCustomize?: ReactNode };src/PageHeader/interface.ts:38"
+        },
+        "footerProps": {
+            "type": "FooterProps",
+            "description": "**右侧功能区聚合对象**(放语言切换 / 用户菜单 / 帮助 / 按钮列表 / 自助跳转 / 自定义);FooterProps = { backSelfcareProps?: BackSelfcareProps; languageProps?: LanguageProps; btnListProps?: BtnListProps; userProps?: UserProps; helpProps?: HelpProps; render?: ReactNode; className?: string };**所有右侧功能都在这个对象里嵌套配置,不是顶层独立 prop**;**helpProps 结构同 BackSelfcareProps**(label/icon/render/onClick/className);**render 是「替换」语义**,传入后整个右侧被替换,其他 5 widget 字段都不渲染(无追加模式);src/PageHeader/interface.ts:162"
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中菜单(匹配 menuListProps.list[].path);顶层 selectMenu 会下传到 MenuListProps.selectMenu;src/PageHeader/index.tsx:14"
+        },
+        "onClickMenu": {
+            "type": "(item: MenuChildrenProps | false) => void",
+            "description": "菜单点击回调;**回参 item 是 MenuChildrenProps 对象或 false**(false 表示选中态被清空);MenuChildrenProps = { label?, type?, path?, icon?, children?, ... },典型用法 `item.path` 取菜单路径"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层容器样式 class"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层容器内联样式"
+        }
+    },
+    "do": [
+        "logo / 应用名放 leftRender",
+        "横向菜单走 menuListProps.list(树形结构通过 children 嵌套)",
+        "右侧功能(语言 / 用户 / 帮助 / 按钮)统一在 footerProps 对象里嵌套配置",
+        "selectMenu 受控 — 父维护 string 匹配 list[].path"
+    ],
+    "dont": [
+        "把 title / subTitle / extra / onBack / backIcon / breadcrumb / footer 当作顶层 prop 传(全部 Ant Design 命名,**本组件均不存在**)",
+        "把右侧功能字段(languageProps / userProps / btnListProps / helpProps / backSelfcareProps)拆到顶层(必须嵌套在 footerProps 对象里)",
+        "在 menuListProps.list[].type 上随意填值(仅支持 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage' 五种)",
+        "传 footerProps.render 同时配其他 widget 字段(render 是**替换语义**,会覆盖整个右侧,languageProps/userProps 等都不渲染;无追加模式)",
+        "期望 PageHeader 顶层有 bottomRender / footerRender / statsRender / extraBottom 下方内容区(**本组件不支持下方扩展插槽**;如需统计条/标签栏在 PageHeader 外层 div 包装)",
+        "把「标题 + 副标题」/「返回按钮 + 标题」/「面包屑 + 标题」拆成多个顶层 prop(本组件这类复合内容**全部塞进 leftRender ReactNode**;见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c)"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取路由路径：onClickMenu={(item) => { if (item) navigate(item.path); }}",
+                "清空选中：onClickMenu={(item) => { if (!item) setSelectMenu(''); else setSelectMenu(item.path); }}",
+                "嵌套子菜单点击：回参 item.children 可能有子项，item.path 是当前点击项的路径，非父级路径"
+            ],
+            "commonMistakes": [
+                "假设 item 永远是对象——回参可能是 false（表示选中态被清空），使用前需判断 if (item)",
+                "直接用 item.label 作路由——应用 item.path；item.label 是显示文案",
+                "不更新 selectMenu 导致菜单高亮不同步——onClickMenu 触发后需 setState(item.path) 回写 selectMenu"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "footerProps 内字段不能拆到 PageHeader 顶层，TS 会报未知 prop",
+            "wrong": "<PageHeader userProps={{ label: '张三' }} languageProps={{ ... }} />  // 这些不是顶层 prop",
+            "right": "<PageHeader footerProps={{ userProps: { label: '张三' }, languageProps: { ... } }} />"
+        },
+        {
+            "issue": "MenuChildrenProps.type 是菜单行为类型，有严格枚举，传错值 TS 不会报错但菜单不响应",
+            "wrong": "list={[{ label: '首页', type: 'link', path: '/home' }]}  // 'link' 不在联合类型",
+            "right": "list={[{ label: '首页', type: 'router', path: '/home' }]}  // 合法值: 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage'"
+        },
+        {
+            "issue": "onClickMenu 回参是 MenuChildrenProps | false，直接访问属性前需判空",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false，访问 .path 会 TypeError",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "不要从 @para-ui/core 导入 MenuChildrenProps 用于 onClickMenu 类型标注——PageHeader/interface.ts 和 Menu/interface.ts 各有一个同名 MenuChildrenProps，两者互不兼容，强行标注会导致 TS2322",
+            "wrong": "import { PageHeader, MenuChildrenProps } from '@para-ui/core';\nonClickMenu={(item: MenuChildrenProps | false) => ...}  // MenuChildrenProps 来自 Menu 不来自 PageHeader，类型冲突",
+            "right": "import { PageHeader } from '@para-ui/core';\n// 不标注类型，让 TS 推断，或使用 Parameters<typeof PageHeader>[0]['onClickMenu']\nonClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PageHeader",
+        "adapter": null
+    }
+}

package/Pagination/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Pagination",
+    "category": "Navigation",
+    "description": "分页组件，支持 simple / complex 双模式及自定义布局组合",
+    "semantic": {
+        "intent": [
+            "展示数据",
+            "分批加载",
+            "导航"
+        ],
+        "useCases": [
+            "数据列表",
+            "搜索结果",
+            "评论区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "simple": {
+            "meaning": "简单模式（仅翻页按钮/数字页码）"
+        },
+        "complex": {
+            "meaning": "复杂模式（含总数 + 每页行数 + 页码 + 跳转）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "total": {
+            "type": "number",
+            "default": 0,
+            "description": "数据总数"
+        },
+        "page": {
+            "type": "number",
+            "default": 1,
+            "description": "当前页码(受控)"
+        },
+        "rowsPerPage": {
+            "type": "number[]",
+            "default": [10, 20, 50, 100],
+            "description": "每页行数候选项列表(下拉选项)"
+        },
+        "currentRowsPerPage": {
+            "type": "number",
+            "default": 10,
+            "description": "当前选中的每页行数"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "simple",
+                "complex",
+                "PaginationLayout[]"
+            ],
+            "default": "simple",
+            "description": "分页类型;**'simple'** = 仅翻页按钮/数字(sizes/pageRow/jumper 均不显示);**'complex'** = 完整布局(总数+每页行数+页码+跳转,支持 autoType 响应式收叠);**PaginationLayout[]** = 自定义组合，合法值 'sizes'|'pageRow'|'pager'|'jumper'"
+        },
+        "pagerType": {
+            "type": "enum",
+            "values": [
+                "btn",
+                "num"
+            ],
+            "default": "num",
+            "description": "页码显示模式 btn=上下页按钮 / num=数字页码列表"
+        },
+        "flippingArrow": {
+            "type": "PaginationFlippingArrow[]",
+            "values": [
+                "prev",
+                "next"
+            ],
+            "default": ["prev", "next"],
+            "description": "方向键 layout;传空数组隐藏全部箭头"
+        },
+        "autoType": {
+            "type": "boolean",
+            "default": true,
+            "description": "type=complex 自适应模式(响应宽度自动收叠)"
+        },
+        "resizeLine": {
+            "type": "string | number",
+            "description": "type=complex 时重新计算换行(传值变化触发自适应)"
+        },
+        "pageMaxLimit": {
+            "type": "boolean",
+            "default": true,
+            "description": "当前页超过总页数时自动回落到最大页"
+        },
+        "skipFunc": {
+            "type": "function",
+            "signature": "(num?: number, skipValue?: number) => void",
+            "description": "回车跳页回调；num 是校正后目标页（已 clamp 到 1~totalPage），skipValue 是输入框原始值（未校正）"
+        },
+        "changePage": {
+            "type": "function",
+            "signature": "(num?: number) => void",
+            "description": "页码改变回调（点击页码 / prev / next / 回车跳转时均触发）；num 是目标页码"
+        },
+        "changeRowsPerPage": {
+            "type": "function",
+            "signature": "(num: number) => void",
+            "description": "每页行数改变回调；num 是新选中行数（非下标，是实际数值）"
+        },
+        "getPopupContainer": {
+            "type": "function",
+            "description": "rowsPerPage 下拉的渲染父节点 (triggerNode) => HTMLElement"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Pagination/index.tsx:33 interface 实证，追加到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Pagination/index.tsx:35 interface 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "Table 独立分页时：changePage 里更新父组件 page state 并重新请求数据，将最新 page 回传给 Pagination 维持受控",
+        "展示总记录数 + 每页行数切换：使用 type='complex'，changeRowsPerPage 里同时重置 page=1 再发请求",
+        "在数据量较大时使用服务端分页——本地分页仅适合 <200 条",
+        "保持每页数量适中（10-50）"
+    ],
+    "dont": [
+        "在极少量数据（<20）时使用 Pagination",
+        "隐藏当前页码标识",
+        "changePage/changeRowsPerPage 里不更新父组件 page state——Pagination 是受控组件，不回写 page prop 会导致翻页后页码回弹"
+    ],
+    "events": {
+        "changePage": {
+            "signature": "(num?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控翻页：changePage={(num) => { setPage(num ?? 1); fetchData(num ?? 1, currentRowsPerPage); }}",
+                "配合 Table：changePage={(num) => { tableRef.current.reload({ page: num }); }}",
+                "防止 undefined：changePage={(num) => setPage(num ?? 1)}  // num 在正常翻页时有值，极端情况下可能 undefined"
+            ],
+            "commonMistakes": [
+                "收到 changePage 后不更新 page prop——Pagination 是受控组件，不回写会导致页码状态不一致",
+                "期望 changePage 在组件内部状态已更新后触发——组件内部先 setPageCom(num) 再触发 changePage，父组件需自行维护独立的 page state",
+                "changeRowsPerPage 里忘记重置 page=1——切换每页条数后通常应回到第一页"
+            ]
+        },
+        "changeRowsPerPage": {
+            "signature": "(num: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换每页行数并重置页码：changeRowsPerPage={(num) => { setCurrentRowsPerPage(num); setPage(1); fetchData(1, num); }}",
+                "受控写法：currentRowsPerPage={currentRowsPerPage} changeRowsPerPage={(num) => setCurrentRowsPerPage(num)}"
+            ],
+            "commonMistakes": [
+                "忘记同步更新 currentRowsPerPage prop——不回写 prop 导致下拉显示旧值",
+                "假设 num 是下标而非实际行数值——num 是 rowsPerPage 数组里选中的那个数字本身"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type prop 接受 PaginationLayout[] 数组，但内部枚举是 'sizes'|'pageRow'|'pager'|'jumper'，不是 'complex'|'simple'",
+            "wrong": "type={['simple', 'pager']}  // 'simple' 不在 PaginationLayout 联合类型",
+            "right": "type={['pager', 'jumper']}  // 自定义布局组合只能用 PaginationLayout 枚举值"
+        },
+        {
+            "issue": "changeRowsPerPage 回参 num 是 number，不是可选 number | undefined",
+            "wrong": "(num?: number) => setCurrentRowsPerPage(num ?? 10)  // 多余的 ?? 语法噪音",
+            "right": "(num: number) => setCurrentRowsPerPage(num)  // num 保证有值"
+        },
+        {
+            "issue": "skipFunc 与 changePage 在回车跳页时都会触发，不要做重复请求",
+            "wrong": "skipFunc={(num) => fetchData(num)} changePage={(num) => fetchData(num)}  // 回车时两个都触发，重复请求",
+            "right": "// 只需 changePage 处理翻页逻辑；skipFunc 是可选补充，跳页专用（例如记录跳转日志）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Pagination",
+        "adapter": null
+    }
+}