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

package/es/Button/index.js

@@ -11,32 +11,32 @@ const z = (b) => {
     variant: N = "contained",
     size: T = "large",
     className: p,
-    disabled: o = !1,
-    children: r,
+    disabled: s = !1,
+    children: l,
     startIcon: e,
-    endIcon: s,
-    loading: i = !1,
+    endIcon: o,
+    loading: c = !1,
     toolTipTitle: x = "",
     TooltipProps: B,
     danger: L = !1,
     href: h,
     target: j,
-    disabledTooltip: l,
+    disabledTooltip: a,
     ...f
-  } = b, [c, m] = y(!1), d = "href" in b, a = () => P(
+  } = b, [r, m] = y(!1), d = "href" in b, i = () => P(
     `${n}-button`,
     p,
     `${n}-button-${N}`,
     `${n}-button-${T}`,
-    c && `${n}-button-loading`,
-    L && !o && `${n}-button-dangerous`,
+    r && `${n}-button-loading`,
+    L && !s && `${n}-button-dangerous`,
     d && `${n}-button-link`,
-    d && o && `${n}-button-link-disabled`
+    d && s && `${n}-button-link-disabled`
   ), u = (k) => {
-    if (!c)
-      return k === "start" && e ? /* @__PURE__ */ t.jsx("span", { className: "button-icon", children: e }) : k === "end" && s ? /* @__PURE__ */ t.jsx("span", { className: "button-icon button-icon-end", children: s }) : null;
-    if (typeof i == "object") {
-      const v = i.delay || 0;
+    if (!r)
+      return k === "start" && e ? /* @__PURE__ */ t.jsx("span", { className: "button-icon", children: e }) : k === "end" && o ? /* @__PURE__ */ t.jsx("span", { className: "button-icon button-icon-end", children: o }) : null;
+    if (typeof c == "object") {
+      const v = c.delay || 0;
       setTimeout(() => m(!1), v);
     }
     return k === "start" ? /* @__PURE__ */ t.jsx("span", { className: "button-icon button-icon-loading", children: /* @__PURE__ */ t.jsx(C, {}) }) : null;
@@ -46,34 +46,34 @@ const z = (b) => {
       ...f,
       href: h,
       target: j,
-      className: a(),
+      className: i(),
       children: [
         u("start"),
-        r && /* @__PURE__ */ t.jsx("span", { className: "button-label", children: r }),
+        l && /* @__PURE__ */ t.jsx("span", { className: "button-label", children: l }),
         u("end")
       ]
     }
   ) : /* @__PURE__ */ t.jsxs(
     "button",
     {
-      disabled: o,
+      disabled: s || r,
       type: "button",
-      className: a(),
+      className: i(),
       ...f,
       children: [
         u("start"),
-        r && /* @__PURE__ */ t.jsx("span", { className: "button-label", children: r }),
+        l && /* @__PURE__ */ t.jsx("span", { className: "button-label", children: l }),
         u("end")
       ]
     }
   );
   return I(() => {
-    m(!!i);
-  }, [i]), o && l ? /* @__PURE__ */ t.jsx(
+    m(!!c);
+  }, [c]), s && a ? /* @__PURE__ */ t.jsx(
     g,
     {
       disabled: !0,
-      ...l,
+      ...a,
       children: /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: $() })
     }
   ) : x ? /* @__PURE__ */ t.jsx(
@@ -82,9 +82,9 @@ const z = (b) => {
       arrow: !1,
       placement: "bottomLeft",
       ...B,
-      disabled: o,
+      disabled: s,
       title: x,
-      children: o ? /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: $() }) : $()
+      children: s ? /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: $() }) : $()
     }
   ) : $();
 }, E = (b) => {
@@ -92,33 +92,33 @@ const z = (b) => {
     variant: N = "contained",
     size: T = "large",
     toolTipTitle: p = "",
-    children: o,
-    className: r,
+    children: s,
+    className: l,
     disabled: e = !1,
-    loading: s = !1,
-    TooltipProps: i,
+    loading: o = !1,
+    TooltipProps: c,
     danger: x = !1,
     href: B,
     target: L,
     disabledTooltip: h,
     ...j
-  } = b, [l, f] = y(!1), c = "href" in b, m = () => P(
+  } = b, [a, f] = y(!1), r = "href" in b, m = () => P(
     `${n}-button ${n}-icon-button`,
-    r,
+    l,
     `${n}-icon-button-${N}`,
     `${n}-icon-button-${T}`,
-    l && `${n}-icon-button-loading`,
+    a && `${n}-icon-button-loading`,
     x && !e && `${n}-icon-button-dangerous`,
-    c && `${n}-button-link`,
-    c && e && `${n}-button-link-disabled`
+    r && `${n}-button-link`,
+    r && e && `${n}-button-link-disabled`
   ), d = () => {
-    if (!l) return o;
-    if (typeof s == "object") {
-      const u = s.delay || 0;
+    if (!a) return s;
+    if (typeof o == "object") {
+      const u = o.delay || 0;
       setTimeout(() => f(!1), u);
     }
     return /* @__PURE__ */ t.jsx("span", { className: "button-loading-icon", children: /* @__PURE__ */ t.jsx(C, {}) });
-  }, a = () => c ? /* @__PURE__ */ t.jsx(
+  }, i = () => r ? /* @__PURE__ */ t.jsx(
     "a",
     {
       ...j,
@@ -131,33 +131,33 @@ const z = (b) => {
     "button",
     {
       ...j,
-      disabled: e,
+      disabled: e || a,
       type: "button",
       className: m(),
       children: d()
     }
   );
   return I(() => {
-    f(!!s);
-  }, [s]), e && h ? /* @__PURE__ */ t.jsx(
+    f(!!o);
+  }, [o]), e && h ? /* @__PURE__ */ t.jsx(
     g,
     {
       disabled: !0,
       ...h,
-      children: /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: a() })
+      children: /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: i() })
     }
   ) : p ? /* @__PURE__ */ t.jsx(
     g,
     {
       arrow: !1,
       placement: "bottomLeft",
-      ...i,
+      ...c,
       disabled: e,
       title: p,
-      children: e ? /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: a() }) : a()
+      children: e ? /* @__PURE__ */ t.jsx("span", { className: `${n}-button--disabled`, children: i() }) : i()
     },
-    +l
-  ) : a();
+    +a
+  ) : i();
 }, S = z;
 S.IconButton = E;
 S.SplitButton = w;

package/es/ButtonGroup/component.json

@@ -0,0 +1,132 @@
+{
+    "name": "ButtonGroup",
+    "category": "General",
+    "description": "按钮组，将多个按钮组合在一起",
+    "semantic": {
+        "intent": [
+            "操作分组",
+            "互斥选择"
+        ],
+        "useCases": [
+            "视图切换",
+            "格式化工具栏",
+            "分段控制"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "图标模式"
+        },
+        "iconSplit": {
+            "meaning": "图标分割模式"
+        },
+        "text": {
+            "meaning": "文本模式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "ButtonItem[]",
+            "itemSchema": {
+                "icon": { "type": "ReactNode", "description": "按钮图标" },
+                "text": { "type": "ReactNode", "description": "按钮文本（icon/iconSplit 模式下仅作 tooltip 默认值；text 模式下为显示文字）" },
+                "disabled": { "type": "boolean", "description": "单项禁用（覆盖组件级 disabled）" },
+                "toolTipTitle": { "type": "ReactNode", "description": "该项 tooltip 文案（优先级高于 text）" },
+                "variant": { "type": "'contained' | 'outlined' | 'text'", "description": "继承自 ButtonProps，text 模式下用于标识激活态" }
+            },
+            "description": "按钮组数据数组,每项 ButtonItem extends ButtonProps(来自 src/Button — 可用 variant / size / loading / type 等全部 Button 字段),额外含 ButtonGroup 专用字段 icon? / text? / toolTipTitle? + 索引签名透传业务字段;src/ButtonGroup/index.tsx:15。**text 字段双语义**:icon/iconSplit 模式下 text 仅作 tooltip 默认值(不显示为按钮文字),text 模式下 text 才是按钮显示文字。**ButtonItem.value 字段冲突**:继承自 Button 类型为 `string | number | readonly string[] | undefined`,**不是单纯 string** — 业务标识请用 viewId / actionKey / menuKey 等独有名避免 tsc 报错(R22 ButtonGroup-004 实证)。**data[].disabled** 是单项独立覆盖字段(boolean,非字符串)"
+        },
+        "mode": {
+            "type": "enum",
+            "values": [
+                "icon",
+                "iconSplit",
+                "text"
+            ],
+            "default": "icon",
+            "description": "按钮组模式(icon=纯图标 / iconSplit=分割可见 / text=纯文字)。**text 模式下 variant 切换有效**:variant='contained' 实心高亮 / variant='outlined' 描边弱化 — 配合外部 activeKey state 实现 tabs 视觉切换(组件无内置 active 状态)"
+        },
+        "layout": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "horizontal",
+            "description": "布局方向"
+        },
+        "showToolTip": {
+            "type": "boolean",
+            "default": "false",
+            "description": "对每按钮显示 tooltip,未设 toolTipTitle 时自动用 text 作为提示;单项 toolTipTitle 优先级高于此自动逻辑"
+        },
+        "showIcon": {
+            "type": "boolean",
+            "default": "false",
+            "description": "text 模式下文字前显示 icon(icon/iconSplit 模式无效)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "整组禁用;单项可通过 data[].disabled(**boolean,不是字符串 'true'**)单独覆盖;src/ButtonGroup/index.tsx:88 单项若未设则继承顶层"
+        },
+        "onClick": {
+            "type": "(item: ButtonItem, event?: React.MouseEvent) => void",
+            "description": "点击回调;**item 是被点击的整个 ButtonItem 对象**(含 data 项里的所有自定义字段,如业务 id / viewId 等)— 推荐做法:在 data 每项上挂 value / viewId 等业务字段,onClick 内 item.viewId 直取(不必维护 index → 业务 id 的映射)"
+        }
+    },
+    "do": [
+        "用于互斥或相关操作的分组",
+        "保持按钮数量适中(2-5)",
+        "在 data 每项透传业务字段(如 value / viewId / actionKey),onClick 内 item.业务字段 取值"
+    ],
+    "dont": [
+        "ButtonGroup 内放置不相关的操作",
+        "按钮过多导致布局拥挤",
+        "把 data[].disabled 传字符串 'true'(必须 boolean — runtime 行为不可信)",
+        "假设 ButtonGroup 有内置 active/selected 状态(无此 prop — tabs 切换需外部 state 维护 activeKey,根据 activeKey 在 data 项里切 variant: 'contained' | 'outlined')",
+        "把业务标识透传到 ButtonItem.value 字段(value 继承自 Button 是宽类型 `string | number | readonly string[] | undefined` — tsc 会报错;业务标识用 viewId / actionKey / menuKey 等独有名)"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(item: ButtonItem, event?: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "通用点击入口：onClick={(item) => dispatch({ type: item.actionKey })}",
+                "获取被点击项的业务标识：onClick={(item) => navigate(item.viewId)}",
+                "需要事件对象：onClick={(item, event) => { event?.stopPropagation(); handleItem(item); }}"
+            ],
+            "commonMistakes": [
+                "期望 item 只是 index 或 key——item 是被点击的完整 ButtonItem 对象，含 data[] 中该项的所有字段",
+                "在 data 里用 ButtonItem.value 存业务 id——value 继承自 Button 是宽类型 string|number|readonly string[]|undefined，建议用 viewId/actionKey 等独有字段名",
+                "event 参数是可选的（签名 event?），回调内直接访问 event.target 前需检查 event 非 undefined"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ButtonItem 继承自 ButtonProps，value 字段类型是 string|number|readonly string[]|undefined，不是单纯 string",
+            "wrong": "const items: ButtonItem[] = [{ icon: <Icon/>, text: '编辑', value: 'edit' }];\n// onClick 中：const id: string = item.value;  // TS 报错：不可分配给 string",
+            "right": "// 使用自定义字段名避免冲突\nconst items: ButtonItem[] = [{ icon: <Icon/>, text: '编辑', actionKey: 'edit' }];\n// onClick 中：const key = (item as any).actionKey;"
+        },
+        {
+            "issue": "ButtonGroup 没有内置 active/selected 状态，需要外部 state 维护并通过 variant 切换视觉",
+            "wrong": "// 期望有 activeKey prop 自动高亮\n<ButtonGroup data={tabs} activeKey='tab1' />  // activeKey 不在 ButtonGroupProps，静默失效",
+            "right": "// 外部维护 activeKey，按需设置 variant\nconst [active, setActive] = useState('tab1');\n<ButtonGroup\n  mode='text'\n  data={tabs.map(t => ({ ...t, variant: t.id === active ? 'contained' : 'outlined' }))}\n  onClick={(item) => setActive((item as any).id)}\n/>"
+        },
+        {
+            "issue": "data[].disabled 必须是 boolean，不能是字符串 'true'，因为 ButtonGroup src 用 typeof _disabled === 'undefined' 做判断",
+            "wrong": "const items: ButtonItem[] = [{ text: '删除', disabled: 'true' as any }];  // 字符串 'true' 是 truthy，不是 boolean true",
+            "right": "const items: ButtonItem[] = [{ text: '删除', disabled: true }];  // 明确传 boolean"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ButtonGroup",
+        "adapter": null
+    }
+}

package/es/ButtonGroup/index.d.ts

@@ -5,7 +5,7 @@ export interface ButtonItem extends ButtonProps {
     icon?: ReactNode;
     /** 文本*/
     text?: ReactNode;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface ButtonGroupProps {
     /** 按钮组模式 */

package/es/Card/component.json

@@ -0,0 +1,162 @@
+{
+    "name": "Card",
+    "category": "Data Display",
+    "description": "list-driven 卡片容器——按 list 数据源渲染多张卡片，支持每行个数 / 加载更多 / 投影边框配置。**注意：不是 antd 风格的单卡片容器**（没有 title / extra / hoverable / actions 这些 prop）",
+    "semantic": {
+        "intent": [
+            "卡片网格容器",
+            "信息分组",
+            "列表卡片展示"
+        ],
+        "useCases": [
+            "仪表盘卡片网格",
+            "商品卡片网格",
+            "应用列表"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准卡片网格"
+        }
+    },
+    "states": [
+        "default",
+        "loadingMore"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "CardItemProps[]",
+            "itemSchema": {
+                "render": { "type": "ReactNode", "description": "卡片内容，静态 ReactNode（不是函数），闭包引用循环变量：data.map(d => ({ render: <div>{d.title}</div> }))" },
+                "style": { "type": "React.CSSProperties", "description": "透传到该卡片外层 div 的样式（可覆盖 boxShadow / border 等组件级配置）" }
+            },
+            "description": "卡片数据源数组。**`CardItemProps = { render?: ReactNode; style?: CSSProperties; [key]: any }`**——核心字段：①`render` 是**静态 ReactNode**（不是 `(item) => ReactNode` 函数！直接写 JSX 即可，需引用循环变量时用闭包：`docs.map(d => ({ render: <div>{d.title}</div> }))`，不要写 `render: () => <div>{d.title}</div>`）；②`style` 透传到该卡片外层 div；③允许任意业务字段平铺存放（`id` / `title` 等仅供业务方在 render 中闭包引用，不被 Card 内部使用）。**list 项**不需要传 React `key`——src 内部用数组 index 做 key。"
+        },
+        "lineNum": {
+            "type": "number | CardLineNumProps[]",
+            "itemSchema": {
+                "width": { "type": "number", "required": true, "description": "容器宽度阈值（px），当容器宽度超过此值时使用此断点配置" },
+                "size": { "type": "number", "required": true, "description": "该断点下每行展示的卡片数" }
+            },
+            "description": "**每行展示的卡片数**（不是总行数！）。与 `width` 互斥：仅当未传 `width` 时 `lineNum` 才生效，每张卡片宽度按容器宽度均分。传数组可做响应式：`[{width: 容器宽阈值, size: 该断点每行个数}]`，src 按 width 升序匹配第一个 `item.width > 容器宽` 的 size；都不命中时取最大档 size。**src 行为细节**(DEFECT-006):src 内部按 width 升序自动 sort,Infinity 作 width 合法且与 `>` 比较恒真;\"最大档\" = 排序后最后一项(width 最大),与 size 数值无关。"
+        },
+        "width": {
+            "type": "string",
+            "default": "300px",
+            "description": "每张卡片固定宽度（与 `lineNum` 互斥，**`width` 优先级高于 `lineNum`**——src 在 `props.width === undefined` 时才进入 `lineNum` 分支）。仅接受 px 等具体单位字符串；不支持 `'auto'` / 百分比（src 直接 inline style 透传，但宽度模式下 Card 不会重新计算 marginRight 收尾对齐）。"
+        },
+        "height": {
+            "type": "string",
+            "default": "140px",
+            "description": "每张卡片高度。仅接受 px 等具体单位字符串；**不支持 `'auto'`**——src 把 height 直接写到外层 div inline style，'auto' 会让卡片高度按 render 内容撑开但失去等高网格视觉。如需自适应内容高度，需在 render 内部用 `display: flex; flex-direction: column` 自管理。**height 不支持 'auto' / 百分比**(DEFECT-008):如需高度跟随内容,父组件需先测量后传 px 字符串(可用 ResizeObserver),Card 不感知父容器高度变化。"
+        },
+        "boxShadow": {
+            "type": "boolean | string",
+            "default": false,
+            "description": "是否带投影。`true` 默认值 `'1px 1px 10px 2px rgba(212,218,227,0.40)'`（src/Card/index.tsx:203）；传字符串则直接作为 CSS box-shadow 值透传。**作用于所有卡片**(组件级);单卡覆盖在 list[].style.boxShadow 中传值,后者优先(Card-DEFECT-003(详见 docs/superpowers/ai-test/defects.md))。"
+        },
+        "border": {
+            "type": "boolean | string",
+            "default": false,
+            "description": "是否带边框。`true` 默认值 `'1px solid rgba(212, 218, 227, 0.4)'`（src/Card/index.tsx:210）；传字符串则直接作为 CSS border 简写值（如 `'2px dashed #1677ff'`）透传。**作用于所有卡片**(组件级);单卡覆盖在 list[].style.border 中传值,后者优先(Card-DEFECT-003(详见 docs/superpowers/ai-test/defects.md))。"
+        },
+        "marginRight": {
+            "type": "string",
+            "default": "20px",
+            "description": "**卡片之间的右间距**（不是 Card 容器外边距）。每张卡片 inline `style.marginRight`；每行最后一张卡片自动重置为 0。"
+        },
+        "marginBottom": {
+            "type": "string",
+            "default": "20px",
+            "description": "**卡片之间的下间距**（不是 Card 容器外边距）。每张卡片 inline `style.marginBottom`。"
+        },
+        "showMore": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用『加载更多』机制（与 `onMore` 配合：showMore=true 时滚动到底部触发 onMore；底部展示 moreRender / loadingMoreRender 文案）。**注意**：5.x 没有独立 `hasMore` prop——『已加载完所有数据』需在业务方 `onMore` 内自行判断后 return 短路（参见 do 段）。议题见 discussions/Card-hasMore-prop.md。"
+        },
+        "moreRender": {
+            "type": "ReactNode",
+            "default": "intl('more')",
+            "description": "底部『可加载』状态展示节点（非 loading 时）。点击后触发 onMore。与 loadingMoreRender 互斥：loadingMore 状态展示 loadingMoreRender，否则展示 moreRender。"
+        },
+        "loadingMoreRender": {
+            "type": "ReactNode",
+            "default": "intl('loadingMore')",
+            "description": "底部『加载中』状态展示节点（onMore 执行期间）。与 moreRender 互斥（见 moreRender 描述）。"
+        },
+        "onMore": {
+            "type": "function",
+            "signature": "() => Promise<void> | void",
+            "description": "加载更多回调（showMore=true 时滚动到底部触发）。返回 Promise 时 Card 自动管理 loadingMore 状态——业务方应在 onMore 内 await 数据请求后 setState 追加 list；同步返回时立即结束 loading。**业务方需自行维护 hasMore 标记**：到达末页时在 onMore 入口 `if (!hasMore) return` 短路。"
+        },
+        "backgroundImage": {
+            "type": "string",
+            "description": "**作用于所有卡片的统一背景图**(组件级,Card-DEFECT-002(详见 docs/superpowers/ai-test/defects.md):所有卡片共享同一张背景图,不是按 list[].cover 渲染单卡封面)。url 设置后 Card 自动追加 `backgroundSize: 100% 100%; backgroundRepeat: no-repeat`。如需每张卡封面不同,请在 list[].render 内自管理图片渲染。"
+        },
+        "className": {
+            "type": "string",
+            "description": "卡片容器自定义类名（src/Card/index.tsx:33 interface 实证，透传到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "卡片容器自定义样式（src/Card/index.tsx:35 interface 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "用 list 一次传入数据源，让 Card 自动按 lineNum / width 排版",
+        "**业务数据派生 list 时**：用 `data.map(d => ({ render: <CardContent {...d} /> }))` 或 `data.map(d => ({ render: <div>{d.title}</div> }))` —— render 直接写 JSX 节点（闭包引用循环变量 d），**不要写 `render: () => <div>...</div>` 函数形式**",
+        "**自定义渲染撑满整张卡片**：render 节点内部用 `<div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>...</div>`，因为 Card 已经把外层 div 高度固定为 props.height",
+        "在 render 根 div 加 `boxSizing: border-box`(DEFECT-007):因 Card 外层 height 固定时,padding 默认会撑超溢出",
+        "需要响应式列数时给 lineNum 传数组（按容器宽断点；按 width 升序匹配第一个超过容器宽的档位）",
+        "数据较多时启用 showMore + onMore 实现分页加载；**业务方在 onMore 入口判断业务侧 hasMore 标记，到达末页 `if (!hasMore) return`** 短路（src 无 hasMore prop）",
+        "lineNum / width 二选一即可——传 width 时 lineNum 不生效（src 在 props.width === undefined 时才进入 lineNum 分支）",
+        "list 项不需要传 React `key`——src 内部用数组 index 做 key（业务字段 `id` 仅供业务方 render 内闭包引用）"
+    ],
+    "dont": [
+        "**不要把 render 写成 `() => ReactNode` 函数形式**——CardItemProps.render 是静态 `ReactNode`，传函数会被 React 当作 child 直接渲染，触发 `Warning: Functions are not valid as a React child` 警告（runtime 层验证失败）",
+        "lineNum 与 width 同时传（互斥；src 在 width 已定义时直接走 width 分支，lineNum 被忽略）",
+        "在 list 中传入超大 ReactNode 致渲染卡顿（应只放轻量数据，render 用 memo）",
+        "**试图传 antd 风格 prop**：`title` / `extra` / `hoverable` / `actions` / `cover` / `renderItem` / `dataSource` —— 这些 prop 不存在；自定义渲染只能通过 `list[].render` 节点",
+        "传 `height='auto'` 或百分比——src 直接 inline 透传，'auto' 会让卡片高度按内容撑开但失去等高视觉",
+        "依赖 `showMore=false` 切换来停止 onMore 触发——切换 false 会让底部按钮消失但已触发的 onMore 不会撤销；正确做法是 `onMore` 内 `if (!业务侧 hasMore) return`"
+    ],
+    "events": {
+        "onMore": {
+            "signature": "() => Promise<void> | void",
+            "asyncSupported": true,
+            "examples": [
+                "基础分页加载：onMore={async () => { const data = await api.getPage(page++); setList(prev => [...prev, ...data]); }}",
+                "Card 自动管理 loadingMore 状态——onMore 执行期间显示 loadingMoreRender，执行完毕自动恢复",
+                "业务侧维护 hasMore 标记：onMore={async () => { if (!hasMore) return; const res = await load(); if (!res.hasNext) setHasMore(false); }}"
+            ],
+            "commonMistakes": [
+                "期望 src 自动检测是否到达末页——src 无 hasMore prop，到达末页需在 onMore 内 return 短路",
+                "依赖 showMore=false 停止触发——切换 false 只隐藏底部按钮，已触发的 onMore Promise 不会撤销",
+                "onMore 里直接 setState 覆盖整个 list 而非追加——滚动加载应追加新数据：setList(prev => [...prev, ...newItems])"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list[].render 是静态 ReactNode，不是 (item) => ReactNode 函数——传函数导致 React child 警告",
+            "wrong": "const list = data.map(d => ({ render: () => <CardContent data={d} /> }));  // 函数被当作 child 渲染，报 Warning",
+            "right": "const list = data.map(d => ({ render: <CardContent data={d} /> }));  // 闭包引用 d，直接写 JSX"
+        },
+        {
+            "issue": "lineNum 与 width 互斥——同时传时 width 优先（src 在 props.width === undefined 时才进 lineNum 分支）",
+            "wrong": "// 期望 lineNum 和 width 都生效\n<Card list={list} width='300px' lineNum={4} />  // lineNum 被忽略",
+            "right": "// 二选一：固定宽度用 width；响应式列数用 lineNum（不传 width）\n<Card list={list} lineNum={4} />"
+        },
+        {
+            "issue": "height 不支持 'auto'——src 直接 inline 透传，'auto' 会破坏等高网格视觉",
+            "wrong": "<Card list={list} height='auto' />  // 卡片高度按内容撑开，等高网格失效",
+            "right": "// 如需自适应内容高度，先测量再传 px 字符串，或在 render 内部自管理\n<Card list={list} height='200px' />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Card",
+        "adapter": null
+    }
+}

package/es/Card/index.d.ts

@@ -2,7 +2,7 @@ import { default as React, FunctionComponent, ReactNode } from 'react';
 export interface CardItemProps {
     render?: ReactNode;
     style?: React.CSSProperties;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface CardLineNumProps {
     /** 容器宽度 */
@@ -41,7 +41,7 @@ export interface CardProps {
     loadingMoreRender?: ReactNode;
     /** 加载更多事件 */
     onMore?: () => Promise<void> | void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Card: FunctionComponent<CardProps>;
 export default Card;

package/es/Card/index.js

@@ -4,7 +4,7 @@ import { $prefixCls as z } from "../GlobalContext/constant.js";
 import K from "clsx";
 import P from "../GlobalContext/useFormatMessage.js";
 import Q from "./lang/index.js";
-import U from "../Utils/Hooks/useResizeObserver.js";
+import U from "../Hooks/useResizeObserver.js";
 import './index.css';/* empty css           */
 const cr = (c) => {
   const {
@@ -57,7 +57,7 @@ const cr = (c) => {
       h && (a = a + 4);
       const G = `${a / n}px`;
       e.current.itemWidth = `calc(${1 / n * 100}% - ${G})`, r.current.querySelectorAll(".card-list > .card-item").forEach((u) => {
-        u.style.width = e.current.itemWidth;
+        u.style.width = e.current.itemWidth || "";
       });
     }
     n !== e.current.lineNumCom && (e.current.lineNumCom = n, D(n));