fix: preserve blank rows when importing Excel files

common/changes/@visactor/vtable-plugins/fix-issue-5227-excel-leading-blank-row_2026-07-15-09-34.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: preserve blank rows when importing excel files (GitHub #5227)",
+      "type": "patch",
+      "packageName": "@visactor/vtable-plugins"
+    }
+  ],
+  "packageName": "@visactor/vtable-plugins",
+  "email": "biukam.w@gmail.com"
+}

packages/vtable-plugins/__tests__/excel-import/excel.test.ts

@@ -0,0 +1,22 @@
+import ExcelJS from 'exceljs';
+import { parseWorksheetToSheetData } from '../../src/excel-import/excel';
+
+describe('Excel worksheet import', () => {
+  test('preserves data after a blank first row', async () => {
+    const workbook = new ExcelJS.Workbook();
+    const worksheet = workbook.addWorksheet('Sheet1');
+    worksheet.getCell('A2').value = 'Name';
+    worksheet.getCell('B2').value = 'Age';
+    worksheet.getCell('A3').value = 'Alice';
+    worksheet.getCell('B3').value = 30;
+
+    const result = await parseWorksheetToSheetData(worksheet, 0);
+
+    expect(result.rowCount).toBe(3);
+    expect(result.data).toEqual([
+      [null, null],
+      ['Name', 'Age'],
+      ['Alice', 30]
+    ]);
+  });
+});

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

@@ -150,9 +150,16 @@ export async function parseWorksheetToSheetData(
   const sheetTitle = worksheet.name || `Sheet${sheetIndex + 1}`;
   const sheetKey = `sheet_${Date.now()}_${sheetIndex}`;
 
-  // 获取实际数据范围
-  const rowCount = worksheet.actualRowCount || 0;
-  const columnCount = worksheet.actualColumnCount || 0;
+  // 获取实际数据范围。actualRowCount/actualColumnCount 只统计非空行列的数量，
+  // 当数据前面或中间存在空白行列时，不能作为最后一个数据单元格的索引。
+  let rowCount = 0;
+  let columnCount = 0;
+  worksheet.eachRow((row, rowNumber) => {
+    rowCount = Math.max(rowCount, rowNumber);
+    row.eachCell((_cell, colNumber) => {
+      columnCount = Math.max(columnCount, colNumber);
+    });
+  });
 
   if (rowCount === 0 || columnCount === 0) {
     // 空 sheet，但仍需要解析合并单元格信息（可能只有合并单元格没有数据）