ProTable

何时用

企业中后台「一整个列表页」的旗舰组件：顶部查询区（SearchForm）+ 工具栏（密度/列设置/刷新/全屏）+ 主表（Table）+ 底部分页一套打包。只要列表 + 服务端分页/排序/筛选，优先用它。区别于 Table：Table 是裸表皮，要自己拼查询区、工具栏、分页、请求生命周期；ProTable 的「托管模式」（传 request）连这些都自管。

导入

Props

继承 Omit<TableProps<TData>, "data">（即 Table 的 columns/enableSorting/enableRowSelection/density/getRowId/rowClassName… 全可用），并新增：

大数据列表记得开 `virtual`。 它继承自 Table，透传下去即生效，但因为没有出现在下面这张表里， 很容易被当成 ProTable 不支持而把上万行直接铺进 DOM： tsx <ProTable columns={columns} request={fetchRows} virtual={{ enabled: true, height: 480 }} /> 参数与禁忌见 Table 的 `virtual`（需装 @tanstack/react-virtual；不建议与树形/明细面板、行拖拽同开）。

Events

继承的 Table 事件（onSortingChange / onRowSelectionChange / onExpandedChange / onColumnFiltersChange）随 Omit<TableProps,"data"> 一并可用。ProTable 自有：

Slots

禁忌 / 坑

• `columns` 必须 memo（与 Table 同源）：cell 函数经 TanStack 的 flexRender 被当作组件类型渲染，identity 一变整格卸载重挂。格子里有输入框时直接坏功能 —— 受控输入框每敲一个字失焦 + 光标跳末尾，挂了 onBlur 提交的还会被重挂时的 blur 触发误提交。useMemo 的依赖里不要放逐键变化的输入值（那等于没 memo），行内编辑优先让输入框非受控。

• 托管模式（传 request）下 data/pagination/loading 三个 prop 被忽略——别两种模式混用。cursor 分页无 total/不能随机跳页，且 filters/sort/pageSize 任一变化会自动重置回第 1 页。
• 托管模式必须给 getRowId，否则行选择/批量在翻页后 key 不稳。
• 行选择的判据是「你有没有接管」，不是「是不是托管模式」：传了 rowSelection 就走受控（须同时给 onRowSelectionChange，否则勾不动且只有 dev 告警提示），不传才由组件内部自持。0.29.0 及之前托管模式一律自持、把这两个 prop 静默丢弃——页面上勾得动、表头全选框也会变半选，看起来完全正常，但消费方的 state 恒为 {}，直到提交时拿到空数组才暴露（#202）。
• 列显隐同一套受控判据（#236）：传 columnVisibility 就是你接管（须同时给 onColumnVisibilityChange，否则列设置点不动且只有 dev 告警）。不接管时列偏好只活在内部 useState 里 —— 工具栏点得动、刷新就没了，「同一个运营换台机器、列偏好跟人走」这件事在组件外一行都写不了。映射口径是缺省即可见，所以落库只需要记被关掉的那几列。
• 身份列与操作列要挂 `meta.lockVisible`：全量开关表达不了「这两列不给关」，而关掉了它们的那一行既没有身份也没有出口。锁定列在工具栏里置灰且恒选中，受控值对它写 false 也不生效 —— 否则一份旧的落库偏好就能把出口关掉，而界面上根本打不开。
• 组件仍留着「不允许关掉最后一列可见列」的保底（避免空表头），受控模式下这一步表现为回调不触发。
• request reject 默认走 console.error 兜底（保证不 unhandled），生产里接 onRequestError 弹 toast / 上报。
• batchActions 需配合 enableRowSelection 且有选中行才显示警示条。
• `request` 走 ref 持有，不进请求依赖：内联写 request={async (p) => …} 不会因函数身份每次 render 变化而无限请求（组件层防呆，不需要消费者 useCallback）。代价是换一个 request 函数本身不会触发重查——要换数据源请改 params，或调 actionRef.reload()。
• `defaultSorting` 是非受控默认值：只在首次挂载读一次，之后由用户点表头接管，后续改这个 prop 不会回灌（同 defaultValue 家族）。想在运行中强制改排序请用 key 重挂或改用受控 sorting。展示模式下它不生效（展示模式的默认排序直接传 sorting）。首点方向由 TanStack 按列类型决定（数值列默认 desc 优先），要精确控制请写 defaultSorting 而非依赖点击。
• `params` 是浅比较（只比第一层）：params={{ scopeId }} 这种内联对象字面量安全，不用 useMemo；但 params={{ filter: { a: 1 } }} 这种嵌套对象每次 render 都是新引用 → 每次都重查，嵌套值请自己保持引用稳定或拍平成一层。
• params 不会并入 `filters`：filters 只装查询区提交的值，params 单独一个字段。这样固定条件不会被同名 filter 覆盖、也不受查询区「重置」影响；request 里自己合并 { ...p.filters, ...p.params }。
• params 内容变化会强制回到第 1 页（cursor 模式同时重置游标栈）——旧页码/旧游标在新固定条件下已无意义。

相关

Table · Book3D · PricingTable · JsonViewer · EditableTable · List