Apache POI 讀取 Excel 行數與列數：HSSF/XSSF 双格式支援完整範例

Apache POI 是 Java 操作 Microsoft Office 文件的事實標準庫。本文聚焦於獲取 Excel 行數與列數的核心 API，涵蓋舊版 .xls (HSSF) 與新版 .xlsx (XSSF) 兩種格式，並釐清常見誤區。

核心 API 對照表

完整可執行範例

import org.apache.poi.hssf.usermodel.HSSFWorkbook;
import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import java.io.FileInputStream;
import java.io.IOException;

public class ExcelDimensionReader {

  public static void main(String[] args) throws IOException {
    String filePath = "E:/WEIAN.xlsx"; // 或 .xls
    try (FileInputStream fis = new FileInputStream(filePath);
         Workbook wb = WorkbookFactory.create(fis)) { // 自動識別格式

      Sheet sheet = wb.getSheetAt(0); // 第一個工作表
      
      // 1. 總行數 (最後一行索引 + 1)
      int lastRowNum = sheet.getLastRowNum();
      int totalRows = lastRowNum + 1; // 因為 0-based
      System.out.println("最後一行索引: " + lastRowNum);
      System.out.println("總行數 (含標題): " + totalRows);

      // 2. 物理行數 (非空行)
      int physicalRows = sheet.getPhysicalNumberOfRows();
      System.out.println("物理行數 (非空): " + physicalRows);

      // 3. 總列數：以第一行(標題行)為準
      Row headerRow = sheet.getRow(0);
      if (headerRow != null) {
        int totalCols = headerRow.getLastCellNum(); // 最後一格索引+1
        int physicalCols = headerRow.getPhysicalNumberOfCells();
        System.out.println("總列數 (含空格): " + totalCols);
        System.out.println("物理列數 (非空): " + physicalCols);
      }

      // 4. 遍歷示範：讀取第 5 行第 4 格
      Row row4 = sheet.getRow(4); // 索引 4 = 第 5 行
      if (row4 != null) {
        Cell cell = row4.getCell(3); // 索引 3 = 第 4 格
        if (cell != null) {
          System.out.println("第5行第4格原值: " + cell.toString());
          // 寫入示範
          cell.setCellValue("測試稅務人稱號");
        }
      }
    }
  }
}

常見誤區與最佳實踐

1. getLastRowNum() ≠ 行數：回傳的是「最後一行的索引」，實際行數需 +1。
2. 空行/空格不計入 PhysicalNumber：若模板有合併儲存格或刻意留空，getPhysicalNumberOfRows/Cells 會偏少，建議以 getLastRowNum/CellNum 為主。
3. 使用 WorkbookFactory.create()：自動偵測 .xls/.xlsx，避免手動判斷實例化 HSSFWorkbook/XSSFWorkbook。
4. 大檔案記憶體：超過 10MB 建議改用 SXSSFWorkbook (流式寫入) 或 XSSFReader (SAX 解析讀取)。
5. 關閉資源：Workbook 實作 Closeable，請用 try-with-resources 確保釋放。

Maven 依賴 (POI 5.2+)

<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi</artifactId>
  <version>5.3.0</version>
</dependency>
<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi-ooxml</artifactId>
  <version>5.3.0</version>
</dependency>

總結

掌握 getLastRowNum()、getLastCellNum() 兩個核心方法，配合 WorkbookFactory 自動適配格式，即能準確獲取 Excel 維度。注意區分「邏輯總數」與「物理非空數」，並針對大檔採用流式 API，即可穩健應對各類報表讀寫需求。