@gmfe/table-x 2.14.29 → 2.14.30-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmfe/table-x",
-  "version": "2.14.29",
+  "version": "2.14.30-beta.0",
   "description": "",
   "author": "liyatang <liyatang@qq.com>",
   "homepage": "https://github.com/gmfe/gmfe#readme",

package/src/hoc/two_level_header_table_x/flatten_helper.js

@@ -0,0 +1,29 @@
+/**
+ * 扁平化 columns（用于 select 和 diy 处理）
+ * 将带有 subColumns 的 columns 展开为扁平结构
+ *
+ * 对于有 subColumns 的列，会给每个 subColumn 添加：
+ * - parentKey: 父级列的 id（用于重建时识别分组）
+ * - parentHeader: 父级列的 Header（用于重建时显示一级表头）
+ * - parentFixed: 父级列的 fixed 属性（用于重建时设置 fixed）
+ */
+export function flattenColumnsForSelectAndDiy(columns) {
+  const flattened = []
+  columns.forEach(column => {
+    if (column.subColumns && column.subColumns.length > 0) {
+      // 如果有 subColumns，将子列展开，并添加父级信息
+      column.subColumns.forEach(subCol => {
+        flattened.push({
+          ...subCol,
+          parentKey: column.id || column.Header, // 父级标识
+          parentHeader: column.Header, // 父级表头文本
+          parentFixed: column.fixed // 父级 fixed 属性
+        })
+      })
+    } else {
+      // 没有 subColumns，直接添加
+      flattened.push(column)
+    }
+  })
+  return flattened
+}

package/src/hoc/two_level_header_table_x/rebuild_helper.js

@@ -0,0 +1,85 @@
+import {
+  TABLE_X_SELECT_ID,
+  TABLE_X_DIY_ID,
+  TABLE_X_EXPAND_ID
+} from '../../util'
+
+/**
+ * 根据扁平化的 columns 重建嵌套结构
+ * 输入：
+ *   - flatColumns: 处理后的扁平 columns（每个 subColumn 都带有 parentKey、parentHeader、parentFixed 属性）
+ * 输出：重建的嵌套结构（严格按照 flatColumns 的顺序输出）
+ */
+export function rebuildNestedColumnsFromFlat(flatColumns) {
+  const nested = []
+  const specialColumnIds = [
+    TABLE_X_SELECT_ID,
+    TABLE_X_DIY_ID,
+    TABLE_X_EXPAND_ID
+  ]
+
+  // 特殊列（select、diy）放在最前面
+  const specialCols = flatColumns.filter(col =>
+    specialColumnIds.includes(col.id)
+  )
+  nested.push(...specialCols)
+  // 普通列（排除特殊列）
+  const normalCols = flatColumns.filter(
+    col => !specialColumnIds.includes(col.id)
+  )
+  // 收集分组数据：parentKey -> { parentHeader, parentFixed, subCols: [] }
+  const groupMap = new Map()
+
+  // 遍历一次：收集所有分组的数据
+  normalCols.forEach(col => {
+    if (col.parentKey) {
+      // 有 parentKey：二级分类的子列
+      if (!groupMap.has(col.parentKey)) {
+        groupMap.set(col.parentKey, {
+          parentHeader: col.parentHeader,
+          parentFixed: col.parentFixed,
+          subCols: []
+        })
+      }
+      // 移除临时属性并添加到分组
+      const {
+        parentKey: _p,
+        parentHeader: _h,
+        parentFixed: _f,
+        ...colWithoutParent
+      } = col
+      groupMap.get(col.parentKey).subCols.push(colWithoutParent)
+    }
+  })
+
+  // 再次遍历：按 flatColumns 的顺序输出
+  const processedGroups = new Set()
+
+  normalCols.forEach(col => {
+    if (col.parentKey) {
+      // 有 parentKey：在第一次遇到的位置输出分组
+      if (!processedGroups.has(col.parentKey)) {
+        processedGroups.add(col.parentKey)
+        const group = groupMap.get(col.parentKey)
+        const visibleSubCols = group.subCols.filter(
+          subCol => subCol.show !== false
+        )
+        if (visibleSubCols.length > 0) {
+          nested.push({
+            Header: group.parentHeader,
+            id: col.parentKey,
+            fixed: group.parentFixed,
+            subColumns: visibleSubCols
+          })
+        }
+      }
+    } else {
+      // 无 parentKey：单独列，直接输出
+      if (col.show !== false) {
+        nested.push(col)
+      }
+    }
+  })
+
+  return nested
+}

package/src/hoc/two_level_header_table_x/table_x.js

@@ -0,0 +1,176 @@
+import React, { useMemo } from 'react'
+import PropTypes from 'prop-types'
+import { useTable } from 'react-table'
+import { Empty, Loading, afterScroll, __DEFAULT_COLUMN } from '../../util'
+import classNames from 'classnames'
+import _ from 'lodash'
+import TwoLevelTHead from './thead'
+import Tr from '../../base/tr'
+import { rebuildNestedColumnsFromFlat } from './rebuild_helper'
+import { transformColumnsForTwoLevel } from './transform_helper'
+
+const defaultColumn = __DEFAULT_COLUMN
+
+/**
+ * 支持两级表头的 TableX 组件
+ *
+ * 接收：
+ *   - columns: 处理后的扁平 columns（经过 select、diy HOC 处理，每个 subColumn 都带有 parentKey、parentHeader、parentFixed 属性）
+ *
+ * 功能：
+ *   1. 根据 parentKey 重建嵌套结构
+ *   2. 转换为 react-table 格式
+ *   3. 使用 TwoLevelTHead 渲染两级表头
+ */
+const TwoLevelTableX = ({
+  columns, // 处理后的扁平 columns
+  data,
+  loading,
+  SubComponent,
+  keyField = 'value',
+  className,
+  tiled = false,
+  onScroll,
+  isTrDisable = () => false,
+  isTrHighlight = () => false,
+  ...rest
+}) => {
+  // 步骤1: 根据扁平化的 columns 重建嵌套结构
+  const rebuiltColumns = useMemo(() => {
+    return rebuildNestedColumnsFromFlat(columns)
+  }, [columns])
+
+  // 步骤2: 转换为 react-table 格式
+  const { transformedColumns, firstLevelHeaders } = useMemo(() => {
+    return transformColumnsForTwoLevel(rebuiltColumns)
+  }, [rebuiltColumns])
+
+  // 步骤3: 过滤隐藏的列（与原 TableX 逻辑一致）
+  const visibleColumns = useMemo(() => {
+    return transformedColumns.filter(c => c.show !== false)
+  }, [transformedColumns])
+
+  // 步骤4: 使用 react-table 处理列和数据（与原 TableX 逻辑一致）
+  const {
+    getTableProps,
+    headerGroups,
+    getTableBodyProps,
+    rows,
+    prepareRow
+  } = useTable({
+    columns: visibleColumns,
+    data,
+    defaultColumn
+  })
+
+  // 步骤5: 计算总宽度（与原 TableX 逻辑完全一致）
+  let totalWidth = 0
+  if (rows[0] && rows[0].cells.length > 0) {
+    prepareRow(rows[0])
+    const last = rows[0].cells[rows[0].cells.length - 1].column
+    totalWidth = last.totalLeft + last.totalWidth
+  }
+
+  // 步骤6: 准备 table props
+  // 注意：对于 display: table，minWidth 可能不会自动扩展，需要同时设置 width: 100% 来撑满容器
+  const gtp = getTableProps()
+  const tableStyle =
+    totalWidth > 0
+      ? { width: '100%', minWidth: totalWidth + 'px' }
+      : { width: '100%' }
+
+  const tableProps = {
+    ...gtp,
+    style: tableStyle,
+    className: classNames(
+      'gm-table-x-table',
+      'gm-table-x-table-two-level',
+      gtp.className
+    )
+  }
+
+  const gtbp = getTableBodyProps()
+  const tableBodyProps = {
+    ...gtbp,
+    className: 'gm-table-x-tbody'
+  }
+
+  const handleScroll = e => {
+    onScroll && onScroll(e)
+    afterScroll()
+  }
+
+  const RenderRow = ({ index, style }) => {
+    const row = rows[index]
+    prepareRow(row)
+
+    return (
+      <Tr
+        key={row.index}
+        row={row}
+        SubComponent={SubComponent}
+        keyField={keyField}
+        style={style}
+        totalWidth={totalWidth}
+        isTrDisable={isTrDisable}
+        isTrHighlight={isTrHighlight}
+      />
+    )
+  }
+
+  return (
+    <div
+      {...rest}
+      className={classNames(
+        'gm-table-x',
+        {
+          'gm-table-x-empty': data.length === 0,
+          'gm-table-x-tiled': tiled
+        },
+        className
+      )}
+      onScroll={handleScroll}
+    >
+      <table {...tableProps}>
+        <TwoLevelTHead
+          headerGroups={headerGroups}
+          firstLevelHeaders={firstLevelHeaders}
+          totalWidth={totalWidth}
+        />
+        <tbody {...tableBodyProps}>
+          {_.map(rows, row =>
+            RenderRow({
+              index: row.index,
+              style: {}
+            })
+          )}
+        </tbody>
+      </table>
+      {loading && <Loading />}
+      {!loading && data.length === 0 && <Empty />}
+    </div>
+  )
+}
+
+TwoLevelTableX.propTypes = {
+  columns: PropTypes.array.isRequired,
+  data: PropTypes.array.isRequired,
+  loading: PropTypes.bool,
+  SubComponent: PropTypes.func,
+  keyField: PropTypes.string,
+  tiled: PropTypes.bool,
+  isTrDisable: PropTypes.func,
+  isTrHighlight: PropTypes.func,
+  onScroll: PropTypes.func,
+  className: PropTypes.string,
+  style: PropTypes.object
+}
+
+TwoLevelTableX.defaultProps = {
+  keyField: 'value',
+  tiled: false,
+  isTrDisable: () => false,
+  isTrHighlight: () => false
+}
+
+export default TwoLevelTableX

package/src/hoc/two_level_header_table_x/thead.js

@@ -0,0 +1,317 @@
+import PropTypes from 'prop-types'
+import React from 'react'
+import classNames from 'classnames'
+import Th from '../../base/th'
+import { getColumnStyle, SortHeader } from '../../util'
+
+/**
+ * 二级表头组件
+ * 渲染两级表头：
+ * - 第一行：一级表头（有子列的显示一级表头，没有子列的占两行）
+ * - 第二行：二级表头（只有有子列的一级表头才显示）
+ */
+const TwoLevelTHead = ({ headerGroups, firstLevelHeaders, totalWidth }) => {
+  // react-table 的 headerGroups 结构：
+  // - 当 columns 有嵌套结构时：headerGroups[0] 是第一级（分组），headerGroups[1] 是第二级（实际列）
+  // - 当 columns 没有嵌套时：headerGroups 只有一行，就是实际列
+  // 重要：当混合嵌套列和单列时，headerGroups[0] 只包含有 columns 的分组列，不包含单列
+  // 单列只会在 headerGroups[1] 中出现
+
+  const hasNestedHeaders = headerGroups.length > 1
+  const firstLevelGroup = hasNestedHeaders ? headerGroups[0] : null
+  const secondLevelGroup = hasNestedHeaders ? headerGroups[1] : headerGroups[0]
+
+  // 构建第一级表头的渲染信息
+  const firstLevelCells = []
+  let secondLevelIndex = 0 // 在第二级表头中的索引
+
+  firstLevelHeaders.forEach((firstLevelHeader, idx) => {
+    if (firstLevelHeader.hasSubColumns) {
+      // 有子列：从第二级表头中获取对应的列
+      const subColumnCount = firstLevelHeader.subColumnCount
+      const subColumns = secondLevelGroup.headers.slice(
+        secondLevelIndex,
+        secondLevelIndex + subColumnCount
+      )
+
+      // 计算总宽度（所有子列的宽度之和）
+      let totalSubWidth = 0
+      subColumns.forEach(subCol => {
+        const style = getColumnStyle(subCol)
+        const width = parseFloat(style.width) || subCol.totalWidth || 0
+        totalSubWidth += width
+      })
+
+      // 获取对应的第一级分组列对象
+      const groupColumn = firstLevelGroup
+        ? firstLevelGroup.headers.find(col => {
+            // 通过 id 或 Header 匹配
+            return (
+              col.id === firstLevelHeader.id ||
+              (col.columns && col.columns.length === subColumnCount)
+            )
+          }) || firstLevelGroup.headers[idx]
+        : null
+
+      firstLevelCells.push({
+        type: 'group',
+        header: firstLevelHeader,
+        colSpan: subColumnCount,
+        subColumns: subColumns,
+        totalWidth: totalSubWidth,
+        column: groupColumn,
+        secondLevelStartIndex: secondLevelIndex
+      })
+
+      secondLevelIndex += subColumnCount
+    } else {
+      // 没有子列：占两行（rowspan=2）
+      // 重要：当混合嵌套列和单列时，react-table 会将单列同时放在 firstLevelGroup 和 secondLevelGroup 中
+      // 我们需要从 firstLevelGroup 中获取单列的列对象（如果存在），否则从 secondLevelGroup 获取
+      let singleColumn = null
+
+      // 优先从 firstLevelGroup 中查找单列（用于 getHeaderProps 等）
+      if (firstLevelGroup) {
+        singleColumn = firstLevelGroup.headers.find(col => {
+          // 通过 id 或 accessor 匹配
+          const matchId = col.id === firstLevelHeader.id
+          const matchAccessor =
+            col.accessor === firstLevelHeader.accessor ||
+            (typeof col.accessor === 'function' &&
+              typeof firstLevelHeader.accessor === 'function' &&
+              col.accessor.toString() === firstLevelHeader.accessor.toString())
+          return matchId || matchAccessor
+        })
+      }
+
+      // 如果 firstLevelGroup 中没找到，从 secondLevelGroup 获取
+      if (!singleColumn) {
+        singleColumn = secondLevelGroup.headers[secondLevelIndex]
+      }
+      firstLevelCells.push({
+        type: 'single',
+        header: firstLevelHeader,
+        colSpan: 1,
+        rowSpan: 2, // 明确设置为 2，占两行
+        column: singleColumn,
+        secondLevelIndex: secondLevelIndex
+      })
+
+      secondLevelIndex += 1
+    }
+  })
+
+  return (
+    <thead className='gm-table-x-thead gm-table-x-thead-two-level'>
+      {/* 第一级表头行 */}
+      <tr className='gm-table-x-tr gm-table-x-tr-first-level'>
+        {firstLevelCells.map((cell, idx) => {
+          const {
+            column,
+            header,
+            colSpan,
+            rowSpan,
+            type,
+            totalWidth: cellTotalWidth
+          } = cell
+
+          // 对于分组列，使用分组列对象；对于单列，使用单列对象
+          const headerColumn = column || cell.column
+          const hp = headerColumn ? headerColumn.getHeaderProps() : {}
+          const { thClassName, style } = headerColumn || {}
+
+          // 计算样式
+          let cellStyle = {
+            ...hp.style,
+            ...style
+          }
+
+          // 处理固定列（需要先定义，因为在设置宽度时需要用到）
+          // 重要：只有明确设置了 fixed 的列才会被固定
+          // 对于分组列，直接使用 header.fixed（一级表头的原始 fixed 状态）
+          // 对于单列，使用 headerColumn.fixed（react-table 处理后的状态）或 header.fixed
+          // 关键：不要从 headerColumn 推断 fixed 状态，因为 headerColumn 可能是 react-table 处理后的对象
+          const fixed =
+            type === 'group'
+              ? header.fixed // 分组列直接使用 header.fixed，不 fallback 到 headerColumn
+              : headerColumn?.fixed !== undefined
+              ? headerColumn.fixed
+              : header.fixed
+
+          // 如果是分组列，使用 colSpan 时不需要手动设置宽度（由浏览器自动计算）
+          // 但我们需要移除 flex 相关的样式，因为使用 table-cell 时 flex 不起作用
+          if (type === 'group') {
+            // 移除 flex 相关样式，只保留 width 和 maxWidth（如果需要）
+            // 对于 table-layout: fixed，我们需要确保分组列的宽度正确设置
+            // colSpan 会自动处理宽度，但为了确保固定列的宽度不被压缩，我们显式设置宽度
+            const { flex, ...restStyle } = cellStyle
+            cellStyle = restStyle
+
+            // 如果有固定列，显式设置宽度以确保不被压缩
+            if (fixed === 'left' || fixed === 'right') {
+              cellStyle.width = `${cellTotalWidth}px`
+              cellStyle.minWidth = `${cellTotalWidth}px`
+            }
+          } else if (headerColumn) {
+            // 对于单列，也需要移除 flex，使用 width
+            const columnStyle = getColumnStyle(headerColumn)
+            const { flex, ...restColumnStyle } = columnStyle
+            cellStyle = {
+              ...cellStyle,
+              ...restColumnStyle // 只使用 width 和 maxWidth，不使用 flex
+            }
+
+            // 如果有固定列，确保宽度不被压缩
+            if (fixed === 'left' || fixed === 'right') {
+              const width = restColumnStyle.width
+              if (width) {
+                cellStyle.minWidth = width
+              }
+            }
+          }
+          // 只有当 fixed 明确为 'left' 或 'right' 时才设置 left/right 和添加 fixed 类
+          // 这样确保只有明确设置了 fixed 的列才会被固定
+          if (fixed === 'left') {
+            // 对于分组列，使用第一个子列的 totalLeft
+            if (
+              type === 'group' &&
+              cell.subColumns &&
+              cell.subColumns.length > 0
+            ) {
+              cellStyle.left = cell.subColumns[0].totalLeft
+            } else if (headerColumn) {
+              cellStyle.left = headerColumn.totalLeft
+            }
+          } else if (fixed === 'right') {
+            // 对于分组列，使用最后一个子列的位置
+            if (
+              type === 'group' &&
+              cell.subColumns &&
+              cell.subColumns.length > 0
+            ) {
+              const lastSubCol = cell.subColumns[cell.subColumns.length - 1]
+              cellStyle.right =
+                totalWidth - lastSubCol.totalLeft - lastSubCol.totalWidth
+            } else if (headerColumn) {
+              cellStyle.right =
+                totalWidth - headerColumn.totalLeft - headerColumn.totalWidth
+            }
+          }
+          // 注意：如果 fixed 是 undefined 或其他值，不应该设置 left/right，也不应该添加 fixed 类
+
+          // 确保我们的 colSpan 和 rowSpan 优先级最高，不会被 hp 中的值覆盖
+          const { colSpan: hpColSpan, rowSpan: hpRowSpan, ...restHp } = hp || {}
+
+          // 确保 rowSpan 和 colSpan 是数字类型（不是字符串）
+          const finalRowSpan =
+            rowSpan !== undefined
+              ? Number(rowSpan)
+              : hpRowSpan !== undefined
+              ? Number(hpRowSpan)
+              : undefined
+          const finalColSpan =
+            colSpan !== undefined
+              ? Number(colSpan)
+              : hpColSpan !== undefined
+              ? Number(hpColSpan)
+              : undefined
+
+          const thProps = {
+            ...restHp,
+            ...(finalColSpan !== undefined && { colSpan: finalColSpan }),
+            ...(finalRowSpan !== undefined && { rowSpan: finalRowSpan }), // 只有定义了才添加
+            className: classNames(
+              'gm-table-x-th',
+              'gm-table-x-th-first-level',
+              hp?.className,
+              thClassName,
+              {
+                'gm-table-x-fixed-left': fixed === 'left',
+                'gm-table-x-fixed-right': fixed === 'right'
+              }
+            ),
+            style: cellStyle
+          }
+
+          return (
+            <th key={idx} {...thProps}>
+              {typeof header.Header === 'function' ? (
+                <header.Header />
+              ) : (
+                header.Header
+              )}
+              {headerColumn?.canSort && (
+                <SortHeader
+                  {...headerColumn.getSortByToggleProps()}
+                  type={
+                    headerColumn.isSorted
+                      ? headerColumn.isSortedDesc
+                        ? 'desc'
+                        : 'asc'
+                      : null
+                  }
+                />
+              )}
+            </th>
+          )
+        })}
+      </tr>
+
+      {/* 第二级表头行（只有有子列的情况才显示） */}
+      {hasNestedHeaders && secondLevelGroup && (
+        <tr className='gm-table-x-tr gm-table-x-tr-second-level'>
+          {secondLevelGroup.headers.map((column, idx) => {
+            // 找到这个列对应的第一级表头
+            const correspondingFirstLevel = firstLevelCells.find(cell => {
+              if (cell.type === 'single') {
+                return cell.secondLevelIndex === idx
+              } else if (cell.type === 'group') {
+                return (
+                  idx >= cell.secondLevelStartIndex &&
+                  idx < cell.secondLevelStartIndex + cell.colSpan
+                )
+              }
+              return false
+            })
+
+            // 如果是单列（rowspan=2），这一行不渲染（已经被第一行占用）
+            if (
+              correspondingFirstLevel &&
+              correspondingFirstLevel.type === 'single'
+            ) {
+              return null
+            }
+
+            // 为第二级表头添加特殊类名，以便在 CSS 中覆盖样式
+            // 重要：二级表头的 fixed 状态应该从对应的一级表头继承
+            // 只有当对应的一级表头设置了 fixed 时，二级表头才应该固定
+            // 注意：column.fixed 已经在 transformColumnsForTwoLevel 中根据一级表头的 fixed 状态设置了
+            // 所以我们直接使用 column.fixed 即可，不需要再次从 firstLevelHeader 继承
+            return (
+              <Th
+                key={idx}
+                column={{
+                  ...column,
+                  // column.fixed 已经在 transformColumnsForTwoLevel 中正确设置
+                  thClassName: classNames(
+                    column.thClassName,
+                    'gm-table-x-th-second-level'
+                  )
+                }}
+                totalWidth={totalWidth}
+              />
+            )
+          })}
+        </tr>
+      )}
+    </thead>
+  )
+}
+
+TwoLevelTHead.propTypes = {
+  headerGroups: PropTypes.array.isRequired,
+  firstLevelHeaders: PropTypes.array.isRequired,
+  totalWidth: PropTypes.number.isRequired
+}
+
+export default React.memo(TwoLevelTHead)

package/src/hoc/two_level_header_table_x/transform_helper.js

@@ -0,0 +1,125 @@
+import {
+  TABLE_X_SELECT_ID,
+  TABLE_X_DIY_ID,
+  TABLE_X_EXPAND_ID
+} from '../../util'
+
+/**
+ * 检查一级表头下的子列 fixed 状态是否一致
+ */
+function validateSubColumnsFixed(column) {
+  if (!column.subColumns || column.subColumns.length === 0) {
+    return { valid: true }
+  }
+
+  const subColumns = column.subColumns
+  const fixedStates = subColumns.map(subCol => {
+    return subCol.fixed !== undefined ? subCol.fixed : column.fixed
+  })
+
+  const firstFixed = fixedStates[0]
+  const allSame = fixedStates.every(fixed => fixed === firstFixed)
+
+  if (!allSame) {
+    return {
+      valid: false,
+      error:
+        `一级表头 "${column.Header || column.id}" 下的子列 fixed 状态不一致。` +
+        `为了避免滚动时表头宽度错位，请确保同一一级表头下的所有子列要么全部固定，要么全部不固定。`
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * 将带有 subColumns 的 columns 转换为 react-table 可以理解的嵌套结构
+ * 输入：[{ Header: '菜品信息', subColumns: [...] }]
+ * 输出：[{ Header: '菜品信息', columns: [...] }] (react-table 格式)
+ */
+export function transformColumnsForTwoLevel(columns) {
+  const transformedColumns = []
+  const firstLevelHeaders = []
+  const specialColumnIds = [
+    TABLE_X_SELECT_ID,
+    TABLE_X_DIY_ID,
+    TABLE_X_EXPAND_ID
+  ]
+
+  columns.forEach((column, index) => {
+    // 特殊列（由其他 HOC 添加）直接添加，不进行转换
+    if (specialColumnIds.includes(column.id)) {
+      transformedColumns.push(column)
+      firstLevelHeaders.push({
+        ...column,
+        hasSubColumns: false,
+        subColumnCount: 1,
+        isSpecialColumn: true
+      })
+      return
+    }
+
+    if (column.subColumns && column.subColumns.length > 0) {
+      // 过滤可见的子列
+      const visibleSubCols = column.subColumns.filter(
+        subCol => subCol.show !== false
+      )
+
+      // 如果所有子列都被隐藏，跳过这个一级表头
+      if (visibleSubCols.length === 0) {
+        return
+      }
+
+      // 验证 fixed 状态（使用可见的子列）
+      const validation = validateSubColumnsFixed({
+        ...column,
+        subColumns: visibleSubCols
+      })
+      if (!validation.valid) {
+        console.error(
+          `[TwoLevelTableX] 配置错误 (第 ${index + 1} 个列):`,
+          validation.error
+        )
+        if (process.env.NODE_ENV === 'development') {
+          throw new Error(validation.error)
+        }
+      }
+
+      firstLevelHeaders.push({
+        ...column,
+        hasSubColumns: true,
+        subColumnCount: visibleSubCols.length // 使用可见子列的数量
+      })
+
+      // 确定统一的 fixed 状态（使用可见的子列）
+      const unifiedFixed =
+        visibleSubCols[0]?.fixed !== undefined
+          ? visibleSubCols[0].fixed
+          : column.fixed !== undefined
+          ? column.fixed
+          : undefined
+
+      // 转换为 react-table 的嵌套结构（只使用可见的子列）
+      transformedColumns.push({
+        Header: column.Header,
+        id: column.id || `group_${transformedColumns.length}`,
+        fixed: unifiedFixed,
+        columns: visibleSubCols.map(subCol => ({
+          ...subCol,
+          fixed: subCol.fixed !== undefined ? subCol.fixed : unifiedFixed
+        }))
+      })
+    } else {
+      // 没有 subColumns，直接添加（会占两行）
+      firstLevelHeaders.push({
+        ...column,
+        hasSubColumns: false,
+        subColumnCount: 1
+      })
+
+      transformedColumns.push(column)
+    }
+  })
+
+  return { transformedColumns, firstLevelHeaders }
+}

package/src/hoc/two_level_header_table_x.js

@@ -0,0 +1,38 @@
+import React, { useMemo } from 'react'
+import PropTypes from 'prop-types'
+import { flattenColumnsForSelectAndDiy } from './two_level_header_table_x/flatten_helper'
+
+/**
+ * 两级表头 HOC
+ * 功能：将带 subColumns 的 columns 扁平化，传递给内部 Component 处理
+ *
+ * 使用方式：
+ * const TwoLevelTable = twoLevelHeaderTableXHOC(
+ *   selectTableXHOC(
+ *     diyTableXHOC(TwoLevelTableX)
+ *   )
+ * )
+ *
+ * 注意：内部 Component（TwoLevelTableX）只需要接收 columns prop（已扁平化，包含 parentKey、parentHeader、parentFixed）
+ */
+function twoLevelHeaderTableXHOC(Component) {
+  const TwoLevelHeaderTableXWrapper = props => {
+    const { columns: originalColumns, ...rest } = props
+
+    // 扁平化 columns（用于 select 和 diy 处理，每个 subColumn 会添加 parentKey、parentHeader、parentFixed）
+    const flattenedColumns = useMemo(() => {
+      return flattenColumnsForSelectAndDiy(originalColumns)
+    }, [originalColumns])
+
+    // 传递给内部 Component
+    return <Component {...rest} columns={flattenedColumns} />
+  }
+
+  TwoLevelHeaderTableXWrapper.propTypes = {
+    columns: PropTypes.array.isRequired
+  }
+
+  return TwoLevelHeaderTableXWrapper
+}
+
+export default twoLevelHeaderTableXHOC

package/src/index.js

@@ -7,6 +7,8 @@ import sortableTableXHOC from './hoc/sortable_table_x'
 import subTableXHOC from './hoc/sub_table_x'
 import editTableXHOC from './hoc/edit_table_x'
 import diyTableXHOC from './hoc/diy_table_x'
+import twoLevelHeaderTableXHOC from './hoc/two_level_header_table_x'
+import TwoLevelTableX from './hoc/two_level_header_table_x/table_x'
 
 import {
   TABLE_X,
@@ -42,6 +44,8 @@ const TableXUtil = {
 export {
   TableXUtil,
   TableX,
+  TwoLevelTableX,
+  twoLevelHeaderTableXHOC,
   TableXVirtualized,
   selectTableXHOC,
   expandTableXHOC,

package/src/index.less

@@ -19,6 +19,35 @@
     transform: translateZ(0);
     display: block; // 覆盖table 默认display
 
+    // 当有两级表头时，表格需要使用表格布局来支持 rowspan
+    &.gm-table-x-table-two-level {
+      display: table !important; // 使用表格布局以支持 rowspan
+      // 固定列的宽度保护
+      .gm-table-x-th,
+      .gm-table-x-td {
+        &.gm-table-x-fixed-left,
+        &.gm-table-x-fixed-right {
+          box-sizing: border-box;
+        }
+      }
+
+      .gm-table-x-tbody {
+        display: table-row-group !important;
+        .gm-table-x-tr {
+          display: table-row !important;
+          .gm-table-x-td {
+            display: table-cell !important;
+            // 移除 flex 相关样式
+            flex: none !important;
+            flex-grow: unset !important;
+            flex-shrink: unset !important;
+            flex-basis: unset !important;
+            box-sizing: border-box;
+          }
+        }
+      }
+    }
+
     .gm-table-x-tr {
       display: flex;
       min-height: 60px;
@@ -80,6 +109,68 @@
       }
     }
 
+    // 二级表头样式
+    // 注意：为了支持 rowspan，二级表头需要使用原生的表格布局模型
+    .gm-table-x-thead-two-level {
+      display: table-header-group !important;
+
+      .gm-table-x-tr-first-level {
+        display: table-row !important;
+
+        .gm-table-x-th-first-level {
+          // 第一级表头样式
+          display: table-cell !important;
+          border: 1px solid #d8dee7 !important;
+          border-bottom: 2px solid #d8dee7 !important;
+          vertical-align: middle;
+          text-align: center;
+          padding: 8px;
+          flex: none !important;
+          // 确保固定列有背景色，这样边框才能正确显示
+          background: @gm-table-x-header-bg !important;
+          // 固定列样式：和普通表格保持一致
+          &.gm-table-x-fixed-left {
+            background: @gm-table-x-header-bg !important;
+            border-right: 1px solid @gm-table-x-border-color !important;
+          }
+
+          &.gm-table-x-fixed-right {
+            background: @gm-table-x-header-bg !important;
+            border-left: 1px solid @gm-table-x-border-color !important;
+          }
+        }
+      }
+
+      .gm-table-x-tr-second-level {
+        display: table-row !important;
+        .gm-table-x-th-second-level {
+          // 第二级表头样式
+          display: table-cell !important;
+          border: 1px solid #d8dee7 !important;
+          border-top: none !important;
+          vertical-align: middle;
+          text-align: center;
+          padding: 8px;
+          flex: none !important;
+          flex-grow: unset !important;
+          flex-shrink: unset !important;
+          flex-basis: unset !important;
+          box-sizing: border-box;
+          // 确保固定列有背景色，这样边框才能正确显示
+          background: @gm-table-x-header-bg !important;
+          // 固定列样式：和普通表格保持一致
+          &.gm-table-x-fixed-left {
+            background: @gm-table-x-header-bg !important;
+            border-right: 1px solid @gm-table-x-border-color !important;
+          }
+          &.gm-table-x-fixed-right {
+            background: @gm-table-x-header-bg !important;
+            border-left: 1px solid @gm-table-x-border-color !important;
+          }
+        }
+      }
+    }
+
     .gm-table-x-tbody {
       display: block; // 覆盖tbody 默认display
 
@@ -432,7 +523,7 @@
     }
   }
 
-  .gm-react-table-x-diy-modal-content{
+  .gm-react-table-x-diy-modal-content {
     border-top: 1px solid @gm-table-x-border-color;
     border-bottom: 1px solid @gm-table-x-border-color;
   }