POI 關於單元格名字獲得單元格內容的中文文檔Named Ranges and Named Cells

因爲有個需求是根據自定義的單元格名字去獲得單元格內容，網上翻了半天也沒有找到有人寫過比較完善的，所以只好看令人頭疼的官方文檔自己寫了。

http://poi.apache.org/components/spreadsheet/quick-guide.html#NamedRanges
先來翻譯一下官方文檔，這裏就直接翻成驢脣不對馬嘴的中文的內容了

Named Ranges and Named Cells

命名範圍和命名單元格

Named Range is a way to refer to a group of cells by a name. Named Cell is a degenerate case of Named Range in that the ‘group of cells’ contains exactly one cell. You can create as well as refer to cells in a workbook by their named range. When working with Named Ranges, the classes
org.apache.poi.ss.util.CellReference and org.apache.poi.ss.util.AreaReference are used.

命名範圍是一種通過名稱引用一組單元格的方法。命名單元格是命名範圍的一種退化情況，因爲“單元組”只包含一個單元格。您可以根據指定的範圍在工作簿中創建並引用單元格。在處理命名範圍時，使用類org.apache.poi.ss.util.CellReference 和org.apache.poi.ss.util.AreaReference

Note: Using relative values like ‘A1:B1’ can lead to unexpected moving of the cell that the name points to when working with the workbook in Microsoft Excel, usually using absolute references like ‘$A$1:$B$1’ avoids this, see also this discussion.

注意:在使用Microsoft Excel的工作簿時，使用’A1:B1’這樣的相對值可能導致名稱所指向的單元格發生意外移動，通常使用’$A$1:$B$1’這樣的絕對引用可以避免這種情況，請參閱本討論。

Creating Named Range / Named Cell

創建命名範圍/命名單元格

// setup code 設置代碼
String sname = "TestSheet", cname = "TestName", cvalue = "TestVal";
Workbook wb = new HSSFWorkbook();
Sheet sheet = wb.createSheet(sname);
sheet.createRow(0).createCell(0).setCellValue(cvalue);
// 1. create named range for a single cell using areareference 使用areareference爲單個單元格創建命名範圍
Name namedCell = wb.createName();
namedCell.setNameName(cname + "1");
String reference = sname+"!$A$1:$A$1"; // area reference
namedCell.setRefersToFormula(reference);
// 2. create named range for a single cell using cellreference 使用cellreference爲單個單元格創建命名範圍
Name namedCel2 = wb.createName();
namedCel2.setNameName(cname + "2");
reference = sname+"!$A$1"; // cell reference
namedCel2.setRefersToFormula(reference);
// 3. create named range for an area using AreaReference 使用AreaReference爲一個區域創建命名範圍
Name namedCel3 = wb.createName();
namedCel3.setNameName(cname + "3");
reference = sname+"!$A$1:$C$5"; // area reference
namedCel3.setRefersToFormula(reference);
// 4. create named formula 創建名爲公式
Name namedCel4 = wb.createName();
namedCel4.setNameName("my_sum");
namedCel4.setRefersToFormula("SUM(" + sname + "!$I$2:$I$6)");

Reading from Named Range / Named Cell

從命名範圍/命名單元格讀取數據

// setup code
String cname = "TestName";
Workbook wb = getMyWorkbook(); // retrieve workbook 檢索工作簿
// retrieve the named range 檢索指定的範圍
int namedCellIdx = wb.getNameIndex(cellName);
Name aNamedCell = wb.getNameAt(namedCellIdx);
// retrieve the cell at the named range and test its contents 在指定的範圍檢索單元格並測試其內容
AreaReference aref = new AreaReference(aNamedCell.getRefersToFormula());
CellReference[] crefs = aref.getAllReferencedCells();
for (int i=0; i<crefs.length; i++) {
    Sheet s = wb.getSheet(crefs[i].getSheetName());
    Row r = sheet.getRow(crefs[i].getRow());
    Cell c = r.getCell(crefs[i].getCol());
    // extract the cell contents based on cell type etc.根據單元類型等提取單元內容。
}

Reading from non-contiguous Named Ranges

從非連續的命名範圍中讀取

// Setup code
String cname = "TestName";
Workbook wb = getMyWorkbook(); // retrieve workbook 檢索工作簿
// Retrieve the named range 檢索指定的範圍
// Will be something like "$C$10,$D$12:$D$14";大概是“$C$10，$D$12:$D$14”;
int namedCellIdx = wb.getNameIndex(cellName);
Name aNamedCell = wb.getNameAt(namedCellIdx);
// Retrieve the cell at the named range and test its contents 在指定的範圍檢索單元格並測試其內容
// Will get back one AreaReference for C10,會爲C10拿回一個區域嗎  and 和
//  another for D12 to D14  D12到D14的另一個
AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getRefersToFormula());
for (int i=0; i<arefs.length; i++) {
    // Only get the corners of the Area 只得到區域的角落
    // (use arefs[i].getAllReferencedCells() to get all cells) (使用arefs[i].getAllReferencedCells()獲取所有單元格)
    CellReference[] crefs = arefs[i].getCells();
    for (int j=0; j<crefs.length; j++) {
        // Check it turns into real stuff
        Sheet s = wb.getSheet(crefs[j].getSheetName());
        Row r = s.getRow(crefs[j].getRow());
        Cell c = r.getCell(crefs[j].getCol());
        // Do something with this corner cell
    }
}

Note, when a cell is deleted, Excel does not delete the attached named range. As result, workbook can contain named ranges that point to cells that no longer exist. You should check the validity of a reference before constructing AreaReference

注意，當一個單元格被刪除時，Excel不會刪除附加的命名範圍。因此，工作簿可以包含指向不再存在的單元格的已命名範圍。在構造一個引用之前，你應該檢查引用的有效性

if(name.isDeleted()){
  //named range points to a deleted cell. 已命名的範圍指向已刪除的單元格。
} else {
  AreaReference ref = new AreaReference(name.getRefersToFormula());
}