@supcon-qlab/table

基于 Ant Design Table 的增强表格组件，提供列配置、行选择、拖拽调整列宽等高级功能。

📚 相关文档

• Ant Design Table 官方文档
• Ant Design Table GitHub 源码

🚀 安装

npm install @supcon-qlab/table

💡 使用

import Table from '@supcon-qlab/table';

function App() {
  const dataSource = [
    { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
    { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  ];

  const columns = [
    { title: 'Name', dataIndex: 'name', key: 'name', width: 120 },
    { title: 'Age', dataIndex: 'age', key: 'age', width: 80 },
    { title: 'Address', dataIndex: 'address', key: 'address', width: 200 },
  ];

  return (
    <Table
      dataSource={dataSource}
      columns={columns}
      pagination={false}
    />
  );
}

✨ 核心功能

1. 自动序号列

表格会自动添加序号列，支持自定义标题或禁用。

<Table
  indexTitle="序号" // 自定义序号列标题
  // indexTitle={false} // 禁用序号列
  dataSource={dataSource}
  columns={columns}
/>

2. 列配置功能

支持列的显示/隐藏、宽度调整、固定列等配置。

<Table
  columnConfigOptions={{
    onSaveColumnConfigs: (configs) => {
      // 保存列配置
      console.log('保存列配置:', configs);
    },
    onShowColumnsChange: (columns) => {
      // 列显示变化
      console.log('显示列变化:', columns);
    },
  }}
  columns={[
    { title: 'Name', dataIndex: 'name', key: 'name', width: 120 },
    { title: 'Email', dataIndex: 'email', key: 'email', width: 150, hidden: true },
  ]}
/>

3. 显示模式切换

支持紧凑、标准、宽松三种显示模式。

<Table
  enableShowMode={true}
  defaultShowMode="normal" // 'loose' | 'normal' | 'tight'
  dataSource={dataSource}
  columns={columns}
/>

4. 列宽拖拽调整

支持拖拽调整列宽，提升用户体验。

<Table
  disableResize={false} // 默认启用
  columns={[
    { title: 'Name', dataIndex: 'name', key: 'name', width: 120 },
    { title: 'Age', dataIndex: 'age', key: 'age', width: 80 },
  ]}
/>

5. 增强行选择

支持点击行进行选择，扩展了 Ant Design 的行选择功能。

<Table
  rowSelection={{
    type: 'checkbox',
    rowClickSelect: true, // 点击行进行选择
    onChange: (selectedRowKeys, selectedRows) => {
      console.log('选中的行:', selectedRowKeys, selectedRows);
    },
  }}
  dataSource={dataSource}
  columns={columns}
/>

6. 列标题增强

支持必填标识和提示信息。

<Table
  columns={[
    { 
      title: 'Name', 
      dataIndex: 'name', 
      key: 'name',
      required: true, // 显示红色 * 号
      tooltip: '用户姓名' // 显示提示信息
    },
  ]}
/>

8. 固定列功能

支持左固定和右固定列，在水平滚动时保持固定位置。当列总宽度超过容器宽度时，会自动启用水平滚动。

<Table
  columns={[
    { title: '样品编号', dataIndex: 'sampleId', key: 'sampleId', width: 120, fixed: 'left' },
    { title: '样品名称', dataIndex: 'sampleName', key: 'sampleName', width: 150 },
    { title: '质量等级', dataIndex: 'qualityLevel', key: 'qualityLevel', width: 100, fixed: 'right' },
  ]}
  dataSource={dataSource}
/>

如果需要强制启用水平滚动，可以显式设置 scroll 属性：

<Table
  columns={columns}
  scroll={{ x: 1500 }} // 强制设置水平滚动宽度
  dataSource={dataSource}
/>

9. 自定义样式

支持奇偶行颜色自定义和行样式类名。

<Table
  oddRowColor="#f8f9fa"
  evenRowColor="#ffffff"
  rowClassName={(record, index) => {
    return index % 2 === 0 ? 'custom-even-row' : 'custom-odd-row';
  }}
  dataSource={dataSource}
  columns={columns}
/>

📋 API

Table Props

| 属性 | 类型 | 默认值 | 描述 | | --------------------- | -------------------------------- | -------------------- | --------------------------------------- | | dataSource | TableDataSource<RecordType> | - | 数据源 | | columns | TableColumnType<RecordType>[] | - | 列配置 | | indexTitle | false \| string | '序号' | 序号列标题，设置为 false 时禁用序号列 | | disableResize | boolean | false | 是否禁用列宽拖拽调整 | | enableShowMode | boolean | false | 是否开启显示模式设置 | | defaultShowMode | 'loose' \| 'normal' \| 'tight' | 'normal' | 默认显示模式 | | columnConfigOptions | TableColumnConfigOptions | - | 列配置选项 | | rowSelection | TableRowSelection<RecordType> | - | 行选择配置 | | oddRowColor | string | '#fff' | 奇数列背景色 | | evenRowColor | string | '#fff' | 偶数列背景色 | | canModalDrag | boolean | true | 列配置弹窗是否可拖拽 | | operationDataIndex | string | 'OPERATION_COLUMN' | 操作列的 dataIndex |

说明：组件使用范型 RecordType（默认 Record<string, unknown>）描述行记录类型；ref 为 React.Ref<HTMLDivElement>。

TableColumnType Props

| 属性 | 类型 | 默认值 | 描述 | | ---------------- | ------------------- | ------- | ----------------------------- | | title | React.ReactNode | - | 列标题 | | dataIndex | string | - | 列数据在数据项中对应的路径 | | key | string | - | 列的唯一标识 | | width | number | - | 列宽度 | | required | boolean | false | 是否显示必填标识（红色 * 号） | | tooltip | React.ReactNode | - | 列标题提示信息 | | hidden | boolean | false | 是否隐藏该列 | | disableResize | boolean | false | 是否禁用该列的宽度调整 | | disableUnCheck | boolean | false | 是否禁用取消勾选 | | fixed | 'left' \| 'right' | - | 固定列位置 |

说明：render 支持 (value, record, index) => React.ReactNode；sorter 支持 boolean 或 (a, b) => number。

TableRowSelection Props

继承 Ant Design Table 的 rowSelection 属性，并新增：

| 属性 | 类型 | 默认值 | 描述 | | ---------------- | --------- | ------- | ---------------------- | | rowClickSelect | boolean | false | 是否开启点击行进行选择 |

TableColumnConfigOptions Props

| 属性 | 类型 | 默认值 | 描述 | | --------------------- | -------------------------------------------- | ------ | ---------------- | | columnConfigs | TableColumnConfigType[] | - | 已保存的列配置 | | onSaveColumnConfigs | (configs: TableColumnConfigType[]) => void | - | 保存列配置的回调 | | onShowColumnsChange | (columns: TableColumnBase[]) => void | - | 显示列变化的回调 | | items | MenuProps['items'] | - | 自定义菜单项 |

🛠️ 开发

此组件通过 Storybook 进行开发和调试，请使用根目录的 pnpm dev 命令启动开发服务器。

📝 更新日志 👉 CHANGELOG