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

package/es/MultiBox/index.js

@@ -10,7 +10,7 @@ import ae from "../GlobalContext/useFormatMessage.js";
 import ie from "./lang/index.js";
 import { Tooltip as ne } from "../Tooltip/index.js";
 import './index.css';/* empty css           */
-const ye = (n) => {
+const ye = (u) => {
   const {
     className: C,
     style: D,
@@ -29,14 +29,14 @@ const ye = (n) => {
     helperText: d = "",
     value: x,
     replaceFields: v,
-    onChange: i,
+    onChange: n,
     fetchSuggestionsKey: j,
     fetchSuggestionsValue: g,
     keyOtherProps: k,
     valueOtherProps: T
-  } = n, S = !!(d && typeof d == "string"), J = d instanceof Array, w = ae("MultiBox", ie), [o, c] = M([]), [a, G] = M({ key: "label", value: "value" });
+  } = u, S = !!(d && typeof d == "string"), J = d instanceof Array, w = ae("MultiBox", ie), [o, c] = M([]), [a, G] = M({ key: "label", value: "value" });
   y(() => {
-    n.defaultValue !== void 0 && c([...n.defaultValue]);
+    u.defaultValue !== void 0 && c([...u.defaultValue]);
   }, []), y(() => {
     x !== void 0 && c([...x]);
   }, [x]), y(() => {
@@ -48,19 +48,19 @@ const ye = (n) => {
   const $ = (t, e) => {
     let l = { error: !1, helperText: "" };
     if (J) {
-      const u = d[t];
-      u && u[e] && (l = {
+      const i = d[t];
+      i && i[e] && (l = {
         error: !0,
-        helperText: u[e]
+        helperText: i[e]
       });
     }
     return l;
   }, Q = () => {
-    s !== !0 && (o.push({}), n.value === void 0 && c([...o]), i && i(o));
+    s !== !0 && (o.push({}), u.value === void 0 && c([...o]), n && n(o));
   }, U = (t) => () => {
-    s !== !0 && (o.splice(t, 1), n.value === void 0 && c([...o]), i && i(o));
+    s !== !0 && (o.splice(t, 1), u.value === void 0 && c([...o]), n && n(o));
   }, A = (t, e) => (l) => {
-    o[e][t] = l.target.value, n.value === void 0 && c([...o]), i && i(o);
+    o[e][t] = l.target.value, u.value === void 0 && c([...o]), n && n(o);
   }, W = () => {
     if (!N && !V) return null;
     const t = () => {
@@ -78,7 +78,7 @@ const ye = (n) => {
       }
     );
   }, X = (t, e) => {
-    const l = t[a.key || ""] || "", u = t[a.value || ""] || "", ee = s instanceof Array ? s[e]?.[l] : s, te = s instanceof Array ? s[e]?.[u] : s, K = $(e, a.key || ""), O = $(e, a.value || "");
+    const l = t[a.key || ""] || "", i = t[a.value || ""] || "", ee = s instanceof Array ? s[e]?.[l] : s, te = s instanceof Array ? s[e]?.[i] : s, K = $(e, a.key || ""), O = $(e, a.value || "");
     let L = "multi-box-content-item-input";
     return (K.error || O.error) && (L += " multi-box-content-item-input-error"), /* @__PURE__ */ r.jsxs("div", { className: L, children: [
       /* @__PURE__ */ r.jsx(
@@ -104,12 +104,12 @@ const ye = (n) => {
           size: f,
           disabled: te,
           placeholder: R,
-          value: u,
+          value: i,
           ...O,
           onChange: A(a.value || "", e),
           fetchSuggestions: g ? E("value") : void 0,
           onSelect: F(a.value || "", e),
-          ...T && T(e, u)
+          ...T && T(e, i)
         }
       )
     ] });
@@ -133,7 +133,12 @@ const ye = (n) => {
   )) }), E = (t) => (e, l) => {
     t === "key" ? j && j(e, l) : g && g(e, l);
   }, F = (t, e) => (l) => {
-    typeof l == "object" && l !== null ? o[e][t] = l.value : o[e][t] = l, n.value === void 0 && c([...o]), i && i(o);
+    if (typeof l == "object" && l !== null) {
+      const i = l.value;
+      o[e][t] = i;
+    } else
+      o[e][t] = l;
+    u.value === void 0 && c([...o]), n && n(o);
   }, Z = () => {
     let t = `${m}-multi-box multi-box`;
     return C && (t += ` ${C}`), f && (t += ` ${m}-multi-box-${f}`), z && (t += ` ${m}-multi-box-error`), s === !0 && (t += ` ${m}-multi-box-disabled`), b && (t += ` ${m}-multi-box-separator`), t;

package/es/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/es/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/es/OperateBtn/index.d.ts

@@ -21,10 +21,10 @@ export interface OperateBtnListProps {
     /** 设置危险按钮 */
     danger?: boolean;
     /** 点击事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
     /** 气泡确认框参数 */
     popConfirmProps?: PopConfirmProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface OperateBtnProps {
     /** 样式class */
@@ -50,7 +50,7 @@ export interface OperateBtnProps {
     /** 点击是否关闭更多 */
     clickCloseMore?: boolean;
     /** 点击事件, 如果listItem里面存在onClick事件,则不触发改事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
 }
 declare const OperateBtn: FunctionComponent<OperateBtnProps>;
 export default OperateBtn;

package/es/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
+    }
+}