@hw-component/table API 文档

基于 antd + @ant-design/pro-table + @hw-component/form 二次封装的 React 表格业务组件库。

安装

yarn add @hw-component/table

import { HTable, useHTable } from "@hw-component/table";
import "@hw-component/table/es/index.css";

peerDependencies：@ant-design/[email protected]、@ant-design/[email protected]、@hw-component/form@^1.9.12、[email protected]、antd@^4.20.7、[email protected]、[email protected]

基础示例

import { HTable } from "@hw-component/table";

const configData = [
  { title: "订单编号", dataIndex: "orderNo", showSearch: true, valueType: "copy" },
  { title: "创建时间", dataIndex: "createTime", showSearch: true, searchType: "rangePicker", valueType: "date", sorter: true },
];

const request = (params) => api.getList(params); // => { records, current, size, total }

export default () => <HTable configData={configData} request={request} rowKey="id" />;

HTable

查询表头 + 表格主体 + 分页一体化组件，基于 ProTableProps 扩展（Omit request / dataSource / rowSelection / pagination，透传其余 pro-table 属性如 scroll / columnsState / headerTitle / bordered 等）。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | configData | 列与查询项配置（见 ConfigItemModal） | ConfigDataModal | — | | request | 请求函数，参数携带 size / current 分页字段 | (params: ParamsModal) => Promise<ResultModal> | — | | dataSource | 受控数据；传数组时组件内部本地分页 | ResultModal \| any[] | — | | reload | dataSource 为对象时的受控刷新函数 | (params: any) => Promise<any> | — | | manual | 是否手动触发首次请求（经 table.reload() 触发） | boolean | false | | formInitValues | 查询表单初始值（同时作为首次请求参数） | Record<string, any> | — | | table | 表格实例（useHTable() 创建） | HTableInstance | — | | rowKey | 行 key | string \| (record) => string | "id" | | rowSelection | 行选择配置（见 HRowSelection），false 关闭 | HRowSelection \| false | — | | action | 自定义动作表，配合列 render 中 tableInstance.table.dispatch(key, params) 触发 | Record<string, (...arg) => void> | {} | | actionRender | 选中行后展示的批量操作区 | (selectedRowKeys: RowObj, tableInstance) => ReactNode | — | | hideHeader | 隐藏查询表头 | boolean | — | | searchSpan | 查询项栅格占宽 | ColProps | {xxl:4, xl:6, lg:8, md:12, sm:24} | | onFinish | 查询表单提交前拦截，返回 Promise 则等待后再请求 | (value) => Promise<any> | — | | onReset | 查询表单重置回调 | VoidFunction | — | | emptyRender | 空态自定义渲染 | (tableInstance?) => ReactNode | 内置空图 | | errorRender | 错误态自定义渲染 | ({ error, tableInstance?, reload? }) => ReactNode | 内置错误图 + 刷新按钮 | | loading | 外部受控 loading | boolean | — | | error | 外部受控错误对象 | Error | — | | options | 工具栏配置（列设置/密度等），false 关闭 | OptionModal \| false | {} | | optionsRender | 工具栏整体自定义渲染 | (node: ReactNode) => ReactNode | — | | localSorter | 排序在前端本地处理（不触发请求） | boolean | — | | affixProps | 分页吸底配置，false 关闭吸底 | AffixProps \| false | — | | goTop | 是否显示回到顶部按钮 | boolean | true | | pagination | 分页配置，false 关闭 | IPaginationProps \| false | {} | | paginationActionRender | 分页左侧操作区 | (tableInstance) => ReactNode | — | | paginationStyle / headerStyle / tableStyle / style | 各区域样式 | React.CSSProperties | — | | headerClassName / bodyClassName / footerClassName / className | 各区域类名 | string | — | | labelWidth | 查询表单 label 宽度 | number | — | | hideLabel | 隐藏查询表单 label | boolean | — | | spaceSize | 表头与主体间距 | number | 15 | | defaultHeaderOpen | 查询表头初始展开状态 | boolean | — | | onOpenChange | 表头展开/收起回调 | (open: boolean) => void | — | | configItemRender | configData 项渲染前加工钩子 | (data: ConfigItemModal) => ConfigItemModal | — |

数据结构

ResultModal

interface ResultModal {
  records: any[];  // 当前页数据
  current: string; // 当前页码
  size: string;    // 每页条数
  total: string;   // 总条数
}

ParamsModal

interface ParamsModal extends Record<string, any> {
  size?: number;    // 每页条数，默认 "10"
  current?: number; // 页码，默认 "1"
}

RowObj

interface RowObj {
  keys?: React.Key[];      // 选中行 key
  rowData?: any[];         // 选中行数据
  selectAll?: boolean;     // 是否处于"选择全部"状态
}

HRowSelection

基于 antd TableProps["rowSelection"] 扩展：

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | allPageCheck | 是否开启"选择全部（跨页全选）"能力 | boolean | — | | allCheckType | 全选按钮形态：batch 批量 / single 单页 | "batch" \| "single" | — | | alwaysShowAlert | 是否始终展示选中提示条 | boolean | — | | selectedRowData | 受控传入已选行数据 | Record<string, any>[] | — | | onChange | 选中变化回调 | (keys: Key[], data: any[]) => void | — | | 其余 | 透传 antd rowSelection（如 preserveSelectedRowKeys / selectedRowKeys / getCheckboxProps） | — | — |

configData 列配置

ConfigItemModal = @hw-component/form HItemProps + ProColumns + 以下扩展：

查询侧（自动生成表单项）

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | showSearch | 是否生成查询表单项 | boolean | — | | searchType | 查询控件类型（复用 HForm 的 HItemProps["type"]，如 input / select / selectInput / rangePicker） | string | — | | itemProps | 查询控件透传属性（如 options / placeholder） | HItemProps | — | | searchRender | 查询项自定义渲染 | (item, node, form, tableInstance) => ReactNode | — | | shouldUpdate | 联动更新条件 | (prev, cur) => boolean | — | | name | 查询字段名（缺省取 dataIndex） | string | — |

展示侧（列渲染）

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | valueType | 内置渲染器类型（见下表） | string | — | | valueTypeProps | 渲染器配置（见下表） | Record<string, any> | — | | render | 单元格自定义渲染（第 4 参为 tableInstance） | (dom, data, index, tableInstance) => ReactNode | — | | rowSelectionTitle | 该列是否作为选择列标题区 | boolean | — | | children / childrenDataIndex | 子列配置 / 子列 dataIndex 集合 | ConfigItemModal[] | — | | titleStr | 列标题文本（与 title 二选一） | string | — | | 其余 | 透传 ProColumns（width / fixed / sorter / align / ellipsis 等） | — | — |

valueType 内置渲染器

| valueType | 渲染说明 | valueTypeProps | | --- | --- | --- | | date | 时间戳转格式化时间 | format（默认 YYYY-MM-DD HH:mm:ss）、timeStampType（默认 X） | | tags | 多标签展示（可关闭、tooltip） | 透传 TagsComponent（closable / tooltip 等） | | copy | 点击复制 | successMsg（默认 复制{title}成功!）、text（string 或 (itemData) => string）、ellipsis | | link | 超链接 | href（string 或 (itemData) => string）、target（默认 _blank）、ellipsis | | text | 段落文本 | addonBefore / addonAfter / type / ellipsis / emptyNode | | image | 图片预览（48px） | 透传 antd Image（含 fallback） | | avatar | 头像（32px） | 透传 antd Avatar | | 其他 | 直接透传 pro-table valueType（如 digit / option） | — |

空值（null / undefined / 空串）统一渲染为 -。

表格实例

useHTable / useHDialogTable / useHDialogEditTable

const table = useHTable(); // 创建实例，经 <HTable table={table} /> 注入

HTableInstance：

| 成员 | 说明 | 类型 | | --- | --- | --- | | form | HForm 表单实例（@hw-component/form） | HFormInstance | | table | 表格操作实例 | TableInstance |

TableInstance 方法：

| 方法 | 说明 | | --- | --- | | reload(params?) | 重新请求（保留此前查询参数，可被 params 覆盖），并清空选中 | | reloadWithParams(params?, filters?, sorter?) | 合并旧参数重新请求，并清空选中 | | getParams() | 获取当前 查询 + 筛选 + 排序 全量参数 | | getSelectedRowData() | 获取选中信息 { keys, rowData, selectAll } | | setSelectedRowData(keys, data) | 手动设置选中行 | | getTableSourceData(full?) | 获取当前页源数据（full 为 true 时含全量字段） | | getColSettingKeys() | 获取列设置状态 { keys, checkCols } | | dispatch(key, params) | 触发 action 中注册的自定义动作 |

useHDialogTable / useHDialogEditTable 额外成员：show(params?) 打开（params 可动态替换 title / configData / request / dataSource / 查询 params）、hide() 关闭、params 当前透传参数。

HTableConfig

全局默认配置 Provider，props 与组件级 props 同名时组件级优先。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | emptyRender | 全局空态渲染 | (tableInstance?) => ReactNode | 内置空图 | | errorRender | 全局错误态渲染 | ({ error, tableInstance?, reload? }) => ReactNode | 内置错误图 | | valueTypeConfig | 自定义/覆盖 valueType 渲染器 | Record<string, (config, itemData, index, tableInstance) => ReactNode> | — | | headerStyle / tableStyle / paginationStyle | 全局区域样式 | React.CSSProperties | — | | defaultSelectedRowClassName | 选中行附加类名（null 关闭高亮） | string \| null | — | | configItemRender | 全局 configData 项加工钩子 | (data: ConfigItemModal) => ConfigItemModal | — |

TableCustomize

自由组合模式：仅创建数据流与实例并注入 Context，不渲染固定 UI。props 同 HTable（Omit request），children 内自行拼装 HTableHeader / HTableBody / HTableFooter / HTablePagination。

HTableHeader

查询表头（基于 HForm），可单独使用。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | configData | 查询项配置（只读取 showSearch 项） | ConfigDataModal | — | | table | 表格实例 | HTableInstance | — | | searchSpan | 查询项栅格占宽 | ColProps | {xxl:4, xl:6, lg:8, md:12, sm:24} | | initValues | 表单初始值 | Record<string, any> | — | | onFinish | 提交拦截 | (value) => Promise<any> | — | | onReset | 重置回调 | VoidFunction | — | | loading | 提交按钮 loading | boolean | — | | headerStyle | 容器样式 | React.CSSProperties | — | | hideLabel / labelWidth | 隐藏 label / label 宽度 | boolean / number | — | | className | 容器类名 | string | — |

HTableBody

表格主体（ProTable 封装），可单独使用。props 基于 ProTableProps 扩展（Omit dataSource / rowSelection / options / pagination），核心增量：

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | configData | 列配置 | ConfigDataModal | — | | table | 表格实例 | HTableInstance | — | | rowSelection | 行选择配置 | HRowSelection \| false | — | | options | 工具栏（列设置 setting 等，扩展 settingRender） | OptionModal \| false | {} | | optionsRender | 工具栏自定义渲染 | (node) => ReactNode | — | | actionRender | 选中提示条右侧操作区 | (selectedRowKeys, tableInstance) => ReactNode | — | | emptyRender / errorRender | 空态/错误态渲染 | 同 HTable | 内置 | | localSorter | 本地排序 | boolean | — | | configItemRender | configData 项加工钩子 | (data) => ConfigItemModal | — | | tableStyle / paginationStyle / className / footerClassName | 样式与类名 | — | — | | 其余 | 透传 ProTable（scroll / headerTitle / columnsState / size / bordered / onChange 等） | — | — |

HTableFooter

吸底批量操作栏。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | actionRender | 右侧操作区 | (selectedRowData: RowObj, tableInstance) => ReactNode | — | | footerRender | 整体自定义渲染（优先级最高） | (tableInstance, selectedRowData, data?) => ReactNode | — | | footerBtnRender | 左侧"选择全部/统计"区域自定义渲染 | (btnDom, total, selectedRowData, setAllCheck) => ReactNode | — | | footerStyle | 容器样式 | React.CSSProperties | — |

HTablePagination

分页（可单独使用）。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | onPageChange | 翻页/改条数回调 | (params: ParamsModal) => void | — | | data | 分页数据源 | Record<string, any> | Context | | table | 表格实例 | HTableInstance | Context | | affixProps | 吸底配置，false 关闭 | AffixProps \| false | — | | goTop | 显示回到顶部按钮 | boolean | — | | actionRender | 左侧操作区 | (tableInstance) => ReactNode | — | | showTotal | 总数文案，false 隐藏 | false \| (total, range) => ReactNode | 第x-y/总共z条 | | paginationStyle / className | 样式与类名 | — | — | | 其余 | 透传 antd PaginationProps | — | — |

HEditTable

可编辑表格（EditableProTable 封装），基于 EditableProTableProps 扩展（Omit recordCreatorProps / request / pagination / dataSource）。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | configData | 列配置（透传 ProColumns，编辑项用 valueType + fieldProps + formItemProps） | ProColumns[] | — | | request | 请求函数 | (params) => Promise<T> | — | | dataSource | 受控数据 | ResultModal \| any[] | — | | manual | 手动触发首次请求 | boolean | — | | onAdd | 新增行保存回调（返回 Promise，reject 可阻断） | (data: T) => Promise<void> | — | | onEdit | 编辑行保存回调 | (data: T) => Promise<void> | — | | creatorButtonText | 新增按钮文案 | string | "新增一行" | | defaultRecordValue | 新增行默认值 | T | {} | | recordCreatorProps | 新增配置透传 | recordCreatorProps | {} | | table | 编辑表实例（useEditTable() 创建） | EditTableInstance | — | | pagination | 分页配置 | IPaginationProps \| false | — | | emptyRender / errorRender | 空态/错误态渲染 | 同 HTable | 内置 | | rowKey | 行 key | string | "id" | | 其余 | 透传 EditableProTable（editable / controlled 等） | — | — |

useEditTable

EditTableInstance：reload(params?) 重新请求、editableForm（EditableFormInstance）、action（pro-table ActionType：startEditable / cancelEditable / reloadAndRest 等）。

HModalTable / HDwTable

弹窗（Modal）/ 抽屉（Drawer）内嵌完整表格。

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | dialogTable | 弹窗表格实例（useHDialogTable() 创建） | HDiaLogTableInstance | 内部创建 | | configData | 列配置 | ConfigDataModal | — | | request | 请求函数（自动合并 params） | (params) => Promise<ResultModal> | — | | params | 额外查询参数（每次请求合并） | Record<string, any> | — | | dataSource | 受控数据 | ResultModal \| any[] | — | | tableProps | 透传 HTable 的其余 props | Omit<HTableProps, "configData" \| "request"> | {} | | editTableProps | （HModalEditTable/HDwEditTable）透传 HEditTable props | Omit<HEditTableProps, "configData" \| "request"> | — | | contentRender | 内容整体自定义渲染 | (node: ReactNode) => ReactNode | — | | 其余 | 透传 antd ModalProps / DrawerProps（title / width / visible / onCancel 等） | — | — |

配套 hooks：useHDialogTable（+ useHDialogEditTable 用于可编辑弹窗），show(params?) 打开、hide() 关闭。

DragTable

列宽拖拽表格，props 完全同 HTable，基于 react-resizable 实现表头拖拽调宽（列需配置 width）。

HTableHeaderSubBtn

查询表头"展开/收起"按钮，配合 TableCustomize 自由组合模式使用，样式与状态由 HTableContext 驱动。