@para-ui/core 5.0.0-beta.9 → 5.0.1

package/lib/Table/component.json

@@ -0,0 +1,547 @@
+{
+    "name": "Table",
+    "category": "Data Display",
+    "description": "基于配置的高性能数据表格，支持远程请求、本地数据、虚拟滚动、行选择、排序过滤、列显隐、展开行等能力",
+    "semantic": {
+        "intent": [
+            "展示数据列表",
+            "数据管理",
+            "查看详情",
+            "批量操作"
+        ],
+        "useCases": [
+            "管理后台列表",
+            "数据报表",
+            "资源清单"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准表格"
+        }
+    },
+    "states": [
+        "loading",
+        "empty",
+        "error"
+    ],
+    "idealProps": {
+        "className": {
+            "type": "string",
+            "description": "自定义 CSS class 名（src/Table/interface.ts:193 TableProps.className）"
+        },
+        "style": {
+            "type": "CSSProperties",
+            "description": "自定义内联样式（src/Table/interface.ts:195 TableProps.style）"
+        },
+        "data": {
+            "type": "T[]",
+            "description": "本地数据源数组。url 与 data 二选一：传 url 走内置请求模式，传 data 走本地数据。**支持泛型**：使用方可写 `<Table<User>>` 让 headData/render 的 row 类型推断为 User。**本地分页行为**：传完整 data 即可，Table 自动按 page/size 切片渲染当前页（DEFECT-005：total 取自 data.length，无需也不接受外部 total prop）"
+        },
+        "headData": {
+            "type": "HeadDataProps<T>[]",
+            "itemSchema": {
+                "name": { "type": "string", "description": "取数据行的字段 key（如 'username'）（src/Table/interface.ts:44）" },
+                "label": { "type": "ReactNode", "required": true, "description": "表头显示名（不是 displayName）（src/Table/interface.ts:46）" },
+                "render": { "type": "(row: T, head?: HeadDataProps<T>, val?: unknown, index?: number, rowIndex?: number) => ReactNode", "description": "自定义单元格渲染，**第一参数是 row（整行数据），不是 value**（与 antd 惯例相反）；需要单元格值时用 row[head.name] 或第三参 val（src/Table/interface.ts:52）" },
+                "operateBtnRender": { "type": "(row: T, rowIndex: number) => OperateBtnProps", "description": "渲染操作列按钮（与 render 互斥，用于快速渲染标准操作按钮组）（src/Table/interface.ts:54）" },
+                "width": { "type": "string | number", "description": "列宽（固定列必须设置 width，否则 fixed 不生效）（src/Table/interface.ts:85）" },
+                "align": { "type": "'left' | 'center' | 'right'", "description": "对齐方式（src/Table/interface.ts:56）" },
+                "fixed": { "type": "'left' | 'right'", "description": "固定列方向（必须配合 width 使用，否则固定不生效）（src/Table/interface.ts:83）" },
+                "sort": { "type": "boolean", "description": "是否排序（**不是 sorter**）——需配合顶层 sortTable=true 才生效（src/Table/interface.ts:49）" },
+                "filter": { "type": "boolean", "description": "是否过滤（src/Table/interface.ts:58）" },
+                "filterRadio": { "type": "boolean", "default": false, "description": "过滤单选（true）还是多选（false，默认）（src/Table/interface.ts:60）" },
+                "filterRender": { "type": "(item: { filterValue: unknown[]; selectFilter: Record<string, unknown[]>; headData: HeadDataProps; setFilter: (selectFilter: Record<string, unknown[]>) => void }) => ReactNode", "description": "过滤浮层自定义渲染（src/Table/interface.ts:67）" },
+                "filterMaxWidth": { "type": "string | number", "description": "过滤浮层最大宽度（src/Table/interface.ts:75）" },
+                "selected": { "type": "boolean", "description": "是否显示该列（showColumns='inside' 时控制列的默认显示/隐藏）（src/Table/interface.ts:79）" },
+                "disabledSelection": { "type": "boolean", "description": "禁用该列的选择（showColumns 列选择器中不可勾选）（src/Table/interface.ts:81）" },
+                "drag": { "type": "boolean", "description": "是否允许拖拽该列（配合顶层 dragColumn=true）（src/Table/interface.ts:48）" },
+                "enums": { "type": "FilterEnumsProps[]", "description": "过滤枚举选项，每项 { displayName: ReactNode, value: unknown }（**displayName 在 enums 里，不是列字段**）（src/Table/interface.ts:77）" },
+                "beyondText": { "type": "boolean", "default": true, "description": "超出内容显示文字 tooltip 还是 dom（src/Table/interface.ts:87）" },
+                "autoTips": { "type": "boolean", "description": "超出时不显示省略号（src/Table/interface.ts:89）" },
+                "tipMaxWidth": { "type": "number | string", "description": "tooltip 最大宽度（src/Table/interface.ts:91）" },
+                "className": { "type": "string", "description": "列的自定义 CSS class（src/Table/interface.ts:42）" },
+                "style": { "type": "CSSProperties", "description": "列的自定义内联样式（src/Table/interface.ts:95）" }
+            },
+            "description": "列配置数组（**真实 prop 名是 headData，非 columns/head**）。**每列字段名（DEFECT-007 修复）**：name（取数据 key）/ label（表头显示名，**不是 displayName**）/ render（自定义渲染，签名见下）/ width / align / fixed / sort（是否排序，**不是 sorter**）/ filter / enums / selected。完整字段见 src/Table/interface.ts 的 HeadDataProps 与 docs/view/table/api.ts 末尾 HeadDataProps Props 表。**displayName 仅出现在 enums.[].displayName（过滤枚举项），不是列字段**。**render 签名（DEFECT-008 修复）**：`(row: T, head?, val?, index?, rowIndex?) => ReactNode`——**第一个参数是 row 不是 value**（与 antd `(value, row, index)` 惯例不同），需要单元格值时用 row[head.name] 或 val 第三参",
+            "_namingNote": "曾经文档误写为 columns 与 head，spec 附录 B 实证修订后统一为 headData，与源码实际一致；displayName/sorter 是 antd 习惯，本组件用 label/sort"
+        },
+        "operate": {
+            "type": "HeadDataProps",
+            "description": "操作列单独配置（不放在 headData 数组里），渲染在每行末尾"
+        },
+        "rowKey": {
+            "type": "string",
+            "default": "key",
+            "description": "行唯一标识字段名。**默认值是 'key' 但绝大多数业务数据没有 key 字段——请几乎总是显式传 rowKey='id' 或对应字段名**，否则会导致 React key 警告 + 行渲染异常。当前实现仅支持 string，**不支持 (row, index) => string 函数形式**"
+        },
+        "loading": {
+            "type": "boolean",
+            "default": false
+        },
+        "search": {
+            "type": "object",
+            "objectShape": {
+                "searchKey": { "type": "string", "description": "搜索关键词字段名（服务端场景）" },
+                "[key: string]": { "type": "any", "description": "任意查询参数，合并到请求的 query/body" }
+            },
+            "description": "远程模式下与每次请求合并发送的查询参数（GET 拼到 query string，POST 合并到 body JSON）。**search 引用变化即触发刷新**——父组件请用 useMemo 包裹避免 render 时新建对象触发死循环刷新；search 对象变化时分页会自动回到第 1 页（业务侧不需手动 setPage(1)）。仅 url 远程模式有效；本地 data 模式不使用此 prop"
+        },
+        "paramsCallback": {
+            "type": "function",
+            "signature": "(data: unknown, cb: (handObj: ReqProps) => void) => void",
+            "description": "请求发送前的请求对象改写钩子（src/Table/interface.ts:306）；第 1 参数是原始请求数据（unknown），调用 cb(改写后对象) 才会真正发请求。常用于在 body 中加业务字段或加签名"
+        },
+        "requestCallback": {
+            "type": "function",
+            "signature": "(data: Record<string, unknown>, cb: (data: Record<string, unknown>) => void) => void",
+            "description": "远程请求返回后回调（src/Table/interface.ts:239）；第 1 参数是响应数据，第 2 参数 cb 是将处理后数据回传给 Table 的回调，**必须调用 cb(data) 才能更新表格数据**"
+        },
+        "loadMore": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用『加载更多』模式（src/Table/interface.ts:293，类型为纯 boolean）；与分页器互斥。触底或点击按钮请求下一页并 append 到 nowPageData。**本地 data 模式**：loadMore=true 时仍渲染按钮但不会自动追加，业务方需在 onClickMore 中 setData 追加"
+        },
+        "loadMoreRender": {
+            "type": "ReactNode",
+            "description": "**自定义加载更多按钮的渲染节点（DEFECT-010 修复，src/Table/interface.ts:295 实证为静态 ReactNode，不是 (props) => ReactNode 函数）**——传函数会触发 React `Functions are not valid as a React child` 警告。需要内部状态/loading 时直接在外层 JSX 闭包引用，不要写函数。本地 data 模式下：loadMore=true + 触发 onClickMore（不会再自动 setData，业务方需在 onClickMore 中追加 data）"
+        },
+        "onClickMore": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击 / 触底加载更多回调（与 loadMore 配套）。本地 data 模式下：业务方在此 setData(prev => [...prev, ...nextChunk]) 实现追加；远程 url 模式下：内部自动请求下一页，无需业务方处理"
+        },
+        "onClickRow": {
+            "type": "function",
+            "signature": "(row: T, e: React.MouseEvent) => void",
+            "description": "点击行事件。**真实 prop 名是 onClickRow，不是 onRowClick**（antd 习惯）。row 是当前行数据；e 是 React MouseEvent，可用于阻止冒泡"
+        },
+        "pagination": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否启用分页（仅 boolean 开关）。具体分页配置（页码/每页数量/分页模式）通过独立的顶层 prop 传：page/size/sizeArr/paginationType——不接受对象形式"
+        },
+        "page": {
+            "type": "number",
+            "default": 1,
+            "description": "当前页码（与 pagination=true 配套）。**半受控（DEFECT-006）**：传 page prop 时 Table 内部 pageCom 同步跟随；不传时 Table 内部自管理 pageCom 初始 1。配合 onPageChange 使用方一般做受控：useState + onPageChange 里 setPage 即可"
+        },
+        "size": {
+            "type": "number",
+            "default": 10,
+            "description": "每页条数。**半受控（DEFECT-006）**：传 size prop 时跟随同步；不传时 Table 自管理。与 page 配套；onPageChange 在用户改每页条数时也会触发"
+        },
+        "paginationType": {
+            "type": "string | PaginationLayout[]",
+            "values": ["simple", "complex"],
+            "description": "分页模式（src/Table/interface.ts:230）：'simple' 简单模式 / 'complex' 完整模式（默认）/ PaginationLayout[] 自定义布局数组",
+            "default": "complex"
+        },
+        "onPageChange": {
+            "type": "function",
+            "signature": "(page: number, size: number) => void",
+            "description": "分页变化回调（DEFECT-003 修复，2026-05-01 新增）。用户切换页码或每页条数时触发，本地 data 模式与远程 url 模式都生效。未传时不影响任何现有行为；与远程模式 requestCallback 互不干扰，可同时使用"
+        },
+        "check": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用复选框（行选择）"
+        },
+        "radio": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用单选框"
+        },
+        "url": {
+            "type": "string",
+            "description": "远程数据请求地址（内置请求模式；与 data 二选一）"
+        },
+        "method": {
+            "type": "enum",
+            "values": ["Get", "Post"],
+            "default": "Get"
+        },
+        "refresh": {
+            "type": "any",
+            "description": "触发刷新的信号（值变化即触发，常用 + 1 模式）"
+        },
+        "sizeArr": {
+            "type": "number[]",
+            "default": "[10, 20, 30]",
+            "description": "每页条数选择列表。传入 size 不在 sizeArr 中时仍以 size 为准（不会自动加入选项）"
+        },
+        "serialNumber": {
+            "type": "boolean | HeadDataProps",
+            "default": false,
+            "description": "**自动序号列**——`true` 渲染默认序号列；传 HeadDataProps 自定义列（如 `{ width: 60, label: '#' }`）。docs/api.ts 已有此 prop，本次提升到 idealProps（DEFECT-014）"
+        },
+        "virtual": {
+            "type": "boolean",
+            "default": false,
+            "description": "**虚拟滚动**——大数据量（>1000 行）建议开启。配合 lineHeight（默认 56px）准确计算可视区。**virtual + pagination=false** 是『一次性渲染全部数据』场景的标准组合；virtual + pagination=true 仍按当前页虚拟。docs/api.ts 已有此 prop，本次提升到 idealProps（DEFECT-014）"
+        },
+        "lineHeight": {
+            "type": "number",
+            "default": 56,
+            "description": "用于虚拟滚动 / autoSize 计算的行高（px）。与单元格 padding 内联高度一致；virtual=true 时建议显式设置避免计算偏差"
+        },
+        "autoSize": {
+            "type": "boolean",
+            "default": true,
+            "description": "**自动计算每页条数**——根据 Table 容器高度 / lineHeight 动态计算 size，**会运行时覆盖外部传入的 size prop**。需要严格控制 size 时设 autoSize=false"
+        },
+        "sortTable": {
+            "type": "boolean",
+            "default": false,
+            "description": "**全表排序开关（顶层）**——开启后 headData 列上的 sort=true 才生效。与 `sortTableRadio` 配合：sortTableRadio=false（默认）允许多列同时排序；true 则单列排序（互斥）。`HeadDataProps.sort` 是单列开关；三者关系：sortTable（全局）+ headData[].sort（列级）+ sortTableRadio（多/单列模式）"
+        },
+        "sortTableRadio": {
+            "type": "boolean",
+            "default": false,
+            "description": "排序模式开关：false=多列排序（默认），true=单列排序（每次仅一列生效）"
+        },
+        "expandable": {
+            "type": "Function",
+            "description": "**展开行渲染函数**（src 实证类型仅 Function 较宽泛；推荐签名 `(row: T) => ReactNode`）——返回展开行的内容；`null/undefined/false` 表示该行不可展开。配合 expandValue / expandMultiple 控制初始展开态与多选展开"
+        },
+        "expandValue": {
+            "type": "string[]",
+            "description": "默认展开的行 key 数组（**匹配 row[rowKey]**——不传 rowKey 时默认匹配 row.key；建议显式传 rowKey）。expandMultiple=false 时只取 [0]"
+        },
+        "expandMultiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否允许多行同时展开（默认仅单行展开）（src/Table/interface.ts:299）"
+        },
+        "disabledExpand": {
+            "type": "string[]",
+            "description": "禁用展开的行 key 数组（匹配 row[rowKey]）（src/Table/interface.ts:301）"
+        },
+        "defaultExpandAllRows": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否默认展开所有行（src/Table/interface.ts:303）"
+        },
+        "onExpand": {
+            "type": "function",
+            "signature": "(row: T, status: 'develop' | 'retract' | undefined) => void",
+            "description": "展开/收起行的事件回调；status='develop' 展开，'retract' 收起（src/Table/interface.ts:314）"
+        },
+        "tableKey": {
+            "type": "string",
+            "description": "表格唯一 id，用来在 localStorage 中存储列显示状态做索引（未传时自动用 url/pathname 作 key）（src/Table/interface.ts:197）"
+        },
+        "expirationTime": {
+            "type": "number",
+            "default": 7,
+            "description": "列显示状态 localStorage 过期时间（单位天，0=永久）（src/Table/interface.ts:199）"
+        },
+        "rememberColumns": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否记住列显示/隐藏状态到 localStorage（false 则每次重置为 headData.selected 默认值）（src/Table/interface.ts:201）"
+        },
+        "ctx": {
+            "type": "string",
+            "description": "请求上下文（传给内置 HTTP 请求函数的 ctx 参数，用于区分多租户/环境等）（src/Table/interface.ts:212）"
+        },
+        "refreshInside": {
+            "type": "boolean",
+            "description": "是否启用内置刷新按钮（带 url 模式下默认 true）（src/Table/interface.ts:208）"
+        },
+        "align": {
+            "type": "enum",
+            "values": ["left", "center", "right"],
+            "default": "left",
+            "description": "全表默认对齐方式（可被 headData 列级 align 覆盖）（src/Table/interface.ts:167）"
+        },
+        "fixedTable": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否等分表格（超出宽度时出现横向滚动条，false 时列宽自适应不出现滚动条）（src/Table/interface.ts:173）"
+        },
+        "fixedColumn": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否启用固定列功能（false 时 headData[].fixed 不生效；IE 浏览器下自动强制为 false）（src/Table/interface.ts:175）"
+        },
+        "showColumns": {
+            "type": "enum",
+            "values": ["inside", false],
+            "default": "inside",
+            "description": "列显隐控制器显示位置：'inside' 在表格右上角内嵌（默认），false 不显示（src/Table/interface.ts:171）"
+        },
+        "filter": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否开启全局过滤功能（顶层开关；headData 列级 filter=true 才真正显示过滤图标）（src/Table/interface.ts:272）"
+        },
+        "defaultSortValue": {
+            "type": "object",
+            "description": "默认排序值，对象 key 为列的 name，value 为 'asc' | 'desc'（src/Table/interface.ts:276）"
+        },
+        "defaultFilterValue": {
+            "type": "object",
+            "description": "默认过滤值，对象 key 为列的 name，value 为过滤值数组（src/Table/interface.ts:281）"
+        },
+        "searchKeyName": {
+            "type": "string[]",
+            "description": "本地搜索时匹配的字段列表（配合 search.searchKey 做客户端过滤；仅本地 data 模式有效）（src/Table/interface.ts:224）"
+        },
+        "tableCell": {
+            "type": "function",
+            "signature": "(row: T, params: unknown) => ReactNode",
+            "description": "整行自定义渲染（与 headData 列级 render 互斥；不推荐：会覆盖所有列渲染逻辑）（src/Table/interface.ts:237）"
+        },
+        "formatter": {
+            "type": "function",
+            "signature": "(row: T, item: HeadDataProps, val: unknown, index: number, rowIndex: number) => ReactNode",
+            "description": "全局单元格内容格式化（在 headData[].render 之外再套一层；适用于全表统一加 tooltip 等）（src/Table/interface.ts:308）"
+        },
+        "rowClassMapping": {
+            "type": "object",
+            "description": "行 className 映射：key 为 row[rowKey]，value 为 className 字符串，用于给特定行加高亮 class（src/Table/interface.ts:310）"
+        },
+        "beyondText": {
+            "type": "boolean",
+            "default": true,
+            "description": "全表单元格超出时显示文字 tooltip（true）还是 DOM（false）（src/Table/interface.ts:262）"
+        },
+        "tipMaxWidth": {
+            "type": "number | string",
+            "default": 500,
+            "description": "全表单元格 tooltip 最大宽度（px 数字或 CSS 字符串）（src/Table/interface.ts:187）"
+        },
+        "lineWidth": {
+            "type": "number",
+            "default": 80,
+            "description": "未设置 width 的列的默认最小宽度（px），用于计算 tableMinWidth（src/Table/interface.ts:287）"
+        },
+        "checkDefaultValue": {
+            "type": "string[]",
+            "description": "复选框默认选中行的 rowKey 数组（始终为 string[]；业务主键为 number 时需 .map(String) 转换）（src/Table/interface.ts:241）"
+        },
+        "checkCount": {
+            "type": "boolean",
+            "description": "是否在分页区显示已选条数（check=true 时默认 true）（src/Table/interface.ts:243）"
+        },
+        "setCheck": {
+            "type": "function",
+            "signature": "(keys: string[], data: T[]) => void",
+            "description": "复选框选中变化回调；keys 为选中行的 rowKey 数组（始终 string[]），data 为选中行的完整数据数组（src/Table/interface.ts:248）"
+        },
+        "radioDefaultValue": {
+            "type": "string | number",
+            "description": "**单选默认选中值（非受控初始值）**——首次挂载后由内部 state 接管；外部完全受控需用 key={value} 强制 remount（src/Table/interface.ts:250）"
+        },
+        "setRadio": {
+            "type": "function",
+            "signature": "(val: string | number, row: T) => void",
+            "description": "单选切换回调。⚠️ **第二参数是单行数据 row，不是数组**（与 setCheck 不同）（src/Table/interface.ts:252）"
+        },
+        "checkRememberPage": {
+            "type": "boolean",
+            "default": false,
+            "description": "翻页时是否保留复选框选中状态（false=翻页自动清空选中）（src/Table/interface.ts:254）"
+        },
+        "disabledArr": {
+            "type": "Array<string | number>",
+            "description": "禁用选择框的行 key 数组（匹配 row[rowKey]；src 内部统一 String() 转换，传数字/字符串都安全）（src/Table/interface.ts:256）"
+        },
+        "disabledArrStatus": {
+            "type": "object",
+            "description": "禁用行的选择框状态映射：true=选中禁用，false=不选中禁用，null=不显示选择框（src/Table/interface.ts:258）"
+        },
+        "autoPagination": {
+            "type": "boolean",
+            "default": true,
+            "description": "自适应分页：根据外容器宽度自动切换分页器模式（src/Table/interface.ts:234）"
+        },
+        "flippingArrow": {
+            "type": "PaginationFlippingArrow[]",
+            "description": "分页方向键布局配置（默认全有；用于隐藏部分翻页按钮）（src/Table/interface.ts:232）"
+        },
+        "onClickColumns": {
+            "type": "function",
+            "signature": "(columns: HeadDataProps[], clickedItem?: unknown) => void",
+            "description": "列显隐切换事件回调；columns 为当前显示列数组（src/Table/interface.ts:321）"
+        },
+        "onSort": {
+            "type": "function",
+            "signature": "(data: { orderField?: string[]; orderType: OrderType[] }) => void",
+            "description": "排序变化回调（**主要用于本地 data 模式**；远程模式排序会直接带参数刷新请求，无需 onSort 处理）（src/Table/interface.ts:337）"
+        },
+        "onError": {
+            "type": "function",
+            "signature": "(err: unknown) => Promise<boolean | void> | (boolean | void)",
+            "description": "接口错误回调；返回 true 走组件内部错误处理（清空数据），不返回或返回 false 走外部自定义逻辑（src/Table/interface.ts:343）"
+        },
+        "filterSearchCallback": {
+            "type": "function",
+            "signature": "(item: T, condition: { search?: unknown; filter?: unknown }) => boolean",
+            "description": "本地数据自定义过滤函数；返回 true 表示该行满足条件保留，false 过滤掉（覆盖内置 search.searchKey + filter 逻辑）（src/Table/interface.ts:330）"
+        },
+        "onDragRow": {
+            "type": "function",
+            "signature": "(list: T[], evt: unknown) => Promise<boolean | void> | (boolean | void)",
+            "description": "行拖拽排序完成回调；list 为排序后的完整数据；返回 true 则组件内部不自动更新行顺序（业务方自行控制）（src/Table/interface.ts:350）"
+        },
+        "columnsInfoEvent": {
+            "type": "function",
+            "signature": "(columnsInfo: HeadDataProps[]) => void",
+            "description": "当前显示列信息变化事件（每次列显隐/重排后触发）（src/Table/interface.ts:354）"
+        },
+        "onRefreshCallback": {
+            "type": "function",
+            "signature": "(type: 'empty' | 'refresh') => void",
+            "description": "内置刷新按钮点击回调；type='empty' 为清空刷新，type='refresh' 为保留分页刷新（src/Table/interface.ts:358）"
+        }
+    },
+    "do": [
+        "为每一列指定 width 以优化渲染性能和体验",
+        "复杂操作建议放入 operate 列",
+        "**几乎总是显式传 rowKey='id'（或对应字段名）**——默认值 'key' 在真实业务数据中几乎不存在",
+        "headData 列字段名是 label / sort（不是 displayName / sorter）",
+        "render 第一参数是 row（不是 value）——需要单元格值时用 row[head.name] 或第三参 val",
+        "远程模式 search 对象用 useMemo 包装，避免父 render 时新建字面量触发死循环刷新",
+        "Table 不接受外部 total/totalCount——本地分页 total 取自 data.length；远程分页期望响应里含 total 字段（典型 { data, total }；不一致请用 requestCallback 改写）",
+        "需要『加载更多』场景请用 loadMore + loadMoreRender——不要尝试 footerRender（不存在）",
+        "**排序三者关系**（DEFECT-014）：先开 `sortTable=true` 启用全表排序，再在 headData 中给需要排序的列写 `sort: true`；`sortTableRadio=true` 切换到单列排序模式（互斥）。三者缺一不可——只设 headData[].sort 而不设 sortTable 列上不会出现排序图标",
+        "**radio 受控**（DEFECT-012）：`radioDefaultValue` 是非受控初始值（命名带 default 实证），切换需 `setRadio` 回调；外部完全受控需用 `key={radioValue}` 强制 remount 或自行管理状态",
+        "**expandable 推荐签名**（DEFECT-013）：`expandable={(row) => <RowDetail row={row} />}`——返回 ReactNode；`expandValue` 是默认展开行的 row[rowKey] 数组，配合 `expandMultiple` 控制是否多行同展开",
+        "**虚拟滚动 + 一次性全量**（DEFECT-014）：`virtual={true} pagination={false}` + 显式 `lineHeight={X}` 是 12k 行级别的标准组合；virtual + pagination=true 时按页虚拟",
+        "**autoSize 与 size 优先级**（DEFECT-014）：autoSize=true（默认）会运行时根据容器高度覆盖 size——需要严格固定 size 必须设 autoSize=false"
+    ],
+    "dont": [
+        "在 render 函数中定义新的组件或函数（导致频繁重渲染）",
+        "不处理 empty 状态",
+        "不要按 antd 习惯传 columns / title / dataIndex / sorter / displayName——这些字段名本组件不接受（用 headData / label / name / sort）",
+        "不要按 antd 风格传 render={(value, row, index) => ...}——本组件 render 第一参数是 row 不是 value",
+        "不要传 total / totalCount prop——本地模式自动从 data.length 取；远程模式从响应体取",
+        "不要传 rowKey 函数 (row) => string——当前仅支持 string",
+        "不要假设 footerRender / itemHeight / rowHeight 等 prop 存在——这些 prop 在 TableProps 中不存在",
+        "**不要把 loadMoreRender 写成 `(props) => ReactNode` 函数形式**（DEFECT-010 上轮误导，已修复）——src 实际类型仅 ReactNode；写函数会触发 React `Functions are not valid as a React child` 警告",
+        "**不要给 method 写小写 / 全大写**（如 `'get'` / `'GET'`）——src enum 只接受 `'Get' | 'Post'`（首字母大写，与 HTTP/axios 习惯不同）",
+        "不要假设 disabledArr 字符串与 checkDefaultValue 类型必须严格一致——src 内部统一 String() 转换；业务侧传数字/字符串都安全",
+        "**不要假设 setRadio 第二参 data 是数组**（DEFECT-012）——src 实证类型 `(val: string|number, row: T) => void`，第二参是单行数据"
+    ],
+    "events": {
+        "onClickRow": {
+            "signature": "(row: T, e: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击行获取行数据：onClickRow={(row, e) => console.log(row)}",
+                "阻止冒泡：onClickRow={(row, e) => { e.stopPropagation(); handleRowClick(row); }}",
+                "跳转详情页：onClickRow={(row) => navigate('/detail/' + row.id)}"
+            ],
+            "commonMistakes": [
+                "按 antd 习惯写 onRowClick 而不是 onClickRow——prop 名不同",
+                "假设回调签名是 (e) 或 (index, row)——实际第一参数是 row，第二参数是 MouseEvent",
+                "在 onClickRow 里直接用 e.target 而不是 row——e 是合成事件，行数据在 row"
+            ]
+        },
+        "setCheck": {
+            "signature": "(keys: string[], data: T[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取选中行 id 数组：setCheck={(keys) => setSelectedKeys(keys)}",
+                "同时获取选中行完整数据：setCheck={(keys, data) => { setSelectedKeys(keys); setSelectedRows(data); }}",
+                "主键为数字时先转字符串：checkDefaultValue={selectedIds.map(String)}"
+            ],
+            "commonMistakes": [
+                "假设 keys 是 number[] ——实际始终是 string[]，数字主键需业务侧 .map(String)",
+                "忽略第二参数 data（完整行数据数组），只接收 keys 而丢失行内容",
+                "将 checkDefaultValue 传为 number[] 而非 string[]——类型报错且不生效"
+            ]
+        },
+        "setRadio": {
+            "signature": "(val: string | number, row: T) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控单选：setRadio={(val) => setSelectedId(val)}",
+                "获取选中行数据：setRadio={(val, row) => { setSelectedId(val); setSelectedRow(row); }}"
+            ],
+            "commonMistakes": [
+                "假设 setRadio 签名与 setCheck 一致，把第二参数当数组——实际是单行数据 row，不是数组",
+                "假设 radioDefaultValue 是受控值——实际只是初始非受控值，切换后需通过 key={value} 强制 remount 实现受控",
+                "忘记传 radio={true} 就直接传 setRadio 和 radioDefaultValue——单选框不渲染"
+            ]
+        },
+        "onPageChange": {
+            "signature": "(page: number, size: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控分页：onPageChange={(p, s) => { setPage(p); setSize(s); }}",
+                "切换页码时重置选中：onPageChange={(p) => { setPage(p); setSelectedKeys([]); }}"
+            ],
+            "commonMistakes": [
+                "在本地 data 模式下期望不传 onPageChange 也能分页——Table 内部自管理，但父组件通常需要监听同步状态",
+                "同时用 requestCallback 和 onPageChange 担心冲突——两者互不干扰，可并用",
+                "把翻页和每页数量变化分开处理——onPageChange 在页码和 size 变化时都触发，(page, size) 两个参数都要接收"
+            ]
+        },
+        "onSort": {
+            "signature": "(data: { orderField?: string[]; orderType: OrderType[] }) => void",
+            "asyncSupported": false,
+            "examples": [
+                "本地排序监听：onSort={(sortData) => console.log(sortData.orderField, sortData.orderType)}",
+                "远程模式下排序直接触发刷新请求，onSort 主要用于本地模式记录排序状态"
+            ],
+            "commonMistakes": [
+                "在远程 url 模式下配 onSort 期望手动发请求——远程模式 Table 已自动带排序参数刷新",
+                "假设 onSort 签名是 (field, direction)——实际是对象形式 {orderField, orderType}",
+                "只开 headData[].sort=true 不开 sortTable=true 然后期望 onSort 触发——排序图标根本不显示"
+            ]
+        },
+        "onExpand": {
+            "signature": "(row: T, status: 'develop' | 'retract' | undefined) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听展开/收起：onExpand={(row, status) => console.log(row.id, status)}",
+                "status='develop' 表展开，status='retract' 表收起"
+            ],
+            "commonMistakes": [
+                "假设 status 是 boolean——实际是字符串枚举 'develop' | 'retract' | undefined",
+                "期望 expandable 直接接受 ReactNode 而不是函数——必须是 (row) => ReactNode 的渲染函数",
+                "不传 rowKey 直接用 expandValue——expandValue 匹配 row[rowKey]，rowKey 默认 'key' 在业务数据中几乎不存在"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "headData 列配置字段名与 antd columns 不同：label/sort，不是 title/sorter/dataIndex",
+            "wrong": "headData={[{ title: '姓名', dataIndex: 'name', sorter: true }]}  // antd 风格，headData 不认识这些字段",
+            "right": "headData={[{ label: '姓名', name: 'name', sort: true }]}  // sort 是 boolean，不是函数"
+        },
+        {
+            "issue": "render 第一参数是 row（整行数据），不是 value（单元格值）——与 antd 相反",
+            "wrong": "render={(value) => <Tag>{value}</Tag>}  // antd 惯例，这里 value 实际是整行数据",
+            "right": "render={(row) => <Tag>{row.status}</Tag>}  // 第一参数是 row；需要值用 row[head.name] 或第三参 val"
+        },
+        {
+            "issue": "HeadDataProps 泛型需要与数据行类型对齐，render 的 row 才有类型提示",
+            "wrong": "const headData: HeadDataProps[] = [{ render: (row) => row.username }]  // row: unknown，报 TS 错",
+            "right": "const headData: HeadDataProps<User>[] = [{ render: (row) => row.username }]  // row: User，有类型提示；或 <Table<User> headData={...}> 让泛型传导"
+        },
+        {
+            "issue": "rowKey 默认值 'key' 在业务数据中几乎不存在，不显式传导致 React key 警告",
+            "wrong": "<Table data={users} headData={...} />  // 未传 rowKey，默认 'key'，业务 User 对象没有 key 字段",
+            "right": "<Table data={users} headData={...} rowKey='id' />  // 几乎总应显式传 rowKey"
+        },
+        {
+            "issue": "method prop 只接受首字母大写 'Get' | 'Post'，不是 HTTP 惯例小写/全大写",
+            "wrong": "method='get'  // 或 method='GET'——src enum 不匹配，Table 内部走默认 'Get'",
+            "right": "method='Post'  // 首字母大写；Get 是默认值可省略"
+        },
+        {
+            "issue": "rowKey 只接受 string（字段名），不支持 (row, index) => string 函数形式",
+            "wrong": "rowKey={(row) => row.id}  // 函数形式，TS 类型报错，src 只接受 string",
+            "right": "rowKey='id'  // 字符串字段名"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Table",
+        "adapter": null
+    }
+}

package/lib/Table/index.d.ts

@@ -1,6 +1,6 @@
-import { FunctionComponent } from 'react';
+import { default as React } from 'react';
 import { TableProps } from './interface';
-declare const Table: FunctionComponent<TableProps<any>>;
+declare const Table: <T = any>(props: TableProps<T>) => React.ReactElement | null;
 export default Table;
 export type { Anyjson, MethodType, OrderType, SelectStatus, ExpandableStatus, AlignType, FilterEnumsProps, HeadDataProps, HeadDataReqProps, PosFixedProps, TableHeadBodyPublicProps, TableProps, ExpandableRowItem, ExpandableRow, ReqProps, HeadLocalStorageItem, HeadLocalStorage, HeadDataConfigProps, SetLocalStorageProps } from './interface';
 export type * from './interface';