feat: mergecell import into vtable-sheet

Author: fangsmile

packages/vtable-plugins/src/excel-import.ts

@@ -22,6 +22,21 @@ export interface SheetData {
   columnCount: number;
   /** 行数 */
   rowCount: number;
+  /** 单元格合并信息 */
+  cellMerge?: Array<{
+    text?: string;
+    range: {
+      start: {
+        col: number;
+        row: number;
+      };
+      end: {
+        col: number;
+        row: number;
+      };
+      isCustom?: boolean;
+    };
+  }>;
 }
 
 // 多 sheet 导入结果类型
@@ -164,6 +179,7 @@ export class ExcelImportPlugin implements pluginsDefinition.IVTablePlugin {
             data: sheetData.data,
             rowCount: Math.max(sheetData.rowCount, 100),
             columnCount: Math.max(sheetData.columnCount, 26),
+            cellMerge: sheetData.cellMerge,
             active: false // 稍后统一激活
           };
 
@@ -286,6 +302,7 @@ export class ExcelImportPlugin implements pluginsDefinition.IVTablePlugin {
             data: sheetData.data,
             rowCount: Math.max(sheetData.rowCount, 100),
             columnCount: Math.max(sheetData.columnCount, 26),
+            cellMerge: sheetData.cellMerge,
             active: false // 稍后统一激活
           };
 
@@ -1084,13 +1101,15 @@ ${recordsStr}
     const columnCount = worksheet.actualColumnCount || 0;
 
     if (rowCount === 0 || columnCount === 0) {
-      // 空 sheet
+      // 空 sheet，但仍需要解析合并单元格信息（可能只有合并单元格没有数据）
+      const cellMerge = this._parseMergedCells(worksheet, []);
       return {
         sheetTitle,
         sheetKey,
         data: [],
         columnCount: 0,
-        rowCount: 0
+        rowCount: 0,
+        ...(cellMerge.length > 0 ? { cellMerge } : {})
       };
     }
 
@@ -1133,15 +1152,193 @@ ${recordsStr}
       data.push(rowData);
     }
 
+    // 解析合并单元格信息
+    const cellMerge = this._parseMergedCells(worksheet, data);
+
     return {
       sheetTitle,
       sheetKey,
       data,
       columnCount,
-      rowCount
+      rowCount,
+      ...(cellMerge.length > 0 ? { cellMerge } : {})
     };
   }
 
+  /**
+   * 解析 Excel 合并单元格信息
+   * @param worksheet ExcelJS worksheet 对象
+   * @param data 已解析的数据数组
+   * @returns 合并单元格信息数组
+   */
+  private _parseMergedCells(
+    worksheet: ExcelJS.Worksheet,
+    data: unknown[][]
+  ): Array<{
+    text?: string;
+    range: {
+      start: { col: number; row: number };
+      end: { col: number; row: number };
+      isCustom?: boolean;
+    };
+  }> {
+    const cellMerge: Array<{
+      text?: string;
+      range: {
+        start: { col: number; row: number };
+        end: { col: number; row: number };
+        isCustom?: boolean;
+      };
+    }> = [];
+
+    try {
+      // ExcelJS 中合并单元格信息存储在 worksheet.model.merges 中
+      // 格式: { 'A1': { tl: 'A1', br: 'B2' }, ... }
+      // 注意：ExcelJS 的类型定义可能不完整，使用 unknown 进行类型转换
+      const worksheetAny = worksheet as unknown as {
+        model?: { merges?: Record<string, unknown> };
+        _merges?: Record<string, unknown>;
+      };
+      const merges: Record<string, unknown> =
+        (worksheetAny.model?.merges as Record<string, unknown>) ||
+        (worksheetAny._merges as Record<string, unknown>) ||
+        {};
+
+      for (const [masterCell, range] of Object.entries(merges)) {
+        try {
+          let startCol: number;
+          let startRow: number;
+          let endCol: number;
+          let endRow: number;
+
+          // 检查 range 的类型
+          if (typeof range === 'string') {
+            // range 是地址范围字符串，如 'A1:B3'
+            const rangeMatch = range.match(/^([A-Z]+\d+):([A-Z]+\d+)$/i);
+            if (!rangeMatch) {
+              continue;
+            }
+
+            const startAddr = this._parseCellAddress(rangeMatch[1]);
+            const endAddr = this._parseCellAddress(rangeMatch[2]);
+            if (!startAddr || !endAddr) {
+              continue;
+            }
+
+            startCol = startAddr.col;
+            startRow = startAddr.row;
+            endCol = endAddr.col;
+            endRow = endAddr.row;
+          } else if (typeof range === 'object' && range !== null) {
+            // range 是对象格式
+            const rangeObj = range as {
+              tl?: string;
+              br?: string;
+              top?: number;
+              left?: number;
+              bottom?: number;
+              right?: number;
+            };
+
+            if (rangeObj.tl && rangeObj.br) {
+              // 使用地址字符串格式 (如 'A1', 'B2')
+              const startAddr = this._parseCellAddress(rangeObj.tl);
+              const endAddr = this._parseCellAddress(rangeObj.br);
+              if (!startAddr || !endAddr) {
+                continue;
+              }
+
+              startCol = startAddr.col;
+              startRow = startAddr.row;
+              endCol = endAddr.col;
+              endRow = endAddr.row;
+            } else if (
+              typeof rangeObj.top === 'number' &&
+              typeof rangeObj.left === 'number' &&
+              typeof rangeObj.bottom === 'number' &&
+              typeof rangeObj.right === 'number'
+            ) {
+              // 使用行列索引格式（ExcelJS 内部格式，1-based）
+              startRow = rangeObj.top - 1; // 转换为 0-based
+              startCol = rangeObj.left - 1; // 转换为 0-based
+              endRow = rangeObj.bottom - 1; // 转换为 0-based
+              endCol = rangeObj.right - 1; // 转换为 0-based
+            } else {
+              continue;
+            }
+          } else {
+            continue;
+          }
+
+          // 获取合并单元格的文本内容（从主单元格）
+          let text: string | undefined;
+          if (startRow >= 0 && startRow < data.length && startCol >= 0 && startCol < data[startRow].length) {
+            const cellValue = data[startRow][startCol];
+            if (cellValue !== null && cellValue !== undefined) {
+              text = String(cellValue);
+            }
+          }
+
+          cellMerge.push({
+            text,
+            range: {
+              start: {
+                col: startCol,
+                row: startRow
+              },
+              end: {
+                col: endCol,
+                row: endRow
+              },
+              isCustom: true
+            }
+          });
+        } catch (error) {
+          console.warn(`解析合并单元格 ${masterCell} 时出错:`, error);
+          // 继续处理其他合并单元格
+        }
+      }
+    } catch (error) {
+      console.warn('解析合并单元格信息时出错:', error);
+    }
+
+    return cellMerge;
+  }
+
+  /**
+   * 解析单元格地址（如 'A1'）为行列索引（0-based）
+   * @param address 单元格地址字符串
+   * @returns 行列索引对象，解析失败返回 null
+   */
+  private _parseCellAddress(address: string): { col: number; row: number } | null {
+    try {
+      // 匹配格式：列字母 + 行号，如 'A1', 'B2', 'AA10'
+      const match = address.match(/^([A-Z]+)(\d+)$/i);
+      if (!match) {
+        return null;
+      }
+
+      const colLetters = match[1].toUpperCase();
+      const rowNumber = parseInt(match[2], 10);
+
+      // 转换列字母为索引 (A=0, B=1, ..., Z=25, AA=26, etc.)
+      // Excel 列是 26 进制，但特殊的是没有 0，A=1, Z=26, AA=27
+      let col = 0;
+      for (let i = 0; i < colLetters.length; i++) {
+        col = col * 26 + (colLetters.charCodeAt(i) - 64); // 'A' = 65, 所以 -64 得到 1
+      }
+      col = col - 1; // 转换为 0-based (A=1->0, B=2->1, ..., AA=27->26)
+
+      // 行号转换为 0-based（Excel 使用 1-based）
+      const row = rowNumber - 1;
+
+      return { col, row };
+    } catch (error) {
+      console.warn(`解析单元格地址 "${address}" 时出错:`, error);
+      return null;
+    }
+  }
+
   /**
    * 静态方法：从 Excel 文件导入多个 sheet
    * @param file Excel 文件

packages/vtable-sheet/src/components/vtable-sheet.ts

@@ -464,6 +464,7 @@ export default class VTableSheet {
           data: sheetData.data as any,
           rowCount: Math.max(sheetData.rowCount, 100), // 至少 100 行
           columnCount: Math.max(sheetData.columnCount, 10), // 至少 10 列
+          cellMerge: sheetData.cellMerge,
           active: false
         };