第二章——jXLS Area（区域）

1    介绍

Area是jXLS中的一个主要概念。本质上，Area表明Excel文件中须要转换的一个矩形区域。每一个Area有一组与之关联的转换命令和一组嵌套子区域。每一个子区域也是一个Area，有本身的一组命令和嵌套子区域。顶层的Area没有父区域（没有嵌套在任意其它Area中）。

2    构建Area的方式

jXLS使用AreaBuilder接口构建Area，jXLS提供了两个实现类：XmlAreaBuilder和XlsCommentAreaBuilder。

XmlAreaBuilder是基于XML配置文件构建Area，XlsCommentAreaBuilder是基于Excel模板中的单元格注释构建Area。默认，jXLS使用XlsCommentAreaBuilder构建Area。能够经过JxlsHelper.setAreaBuilder()方法切换构建Area的方式。其实，这两种构建方式都是基于解析各自的配置使用Java API构建Area，所以，有三种构建Area的方式：

• Java API
• Excel标记
• XML配置

2.1    使用Java API构建Area（推荐）

Area的实现类为XlsArea，XlsArea有如下构造函数：

public XlsArea(AreaRef areaRef, Transformer transformer);

public XlsArea(String areaRef, Transformer transformer);

public XlsArea(CellRef startCell, CellRef endCell, Transformer transformer);

public XlsArea(CellRef startCellRef, Size size, List<CommandData> commandDataList, Transformer transformer);

public XlsArea(CellRef startCellRef, Size size);

public XlsArea(CellRef startCellRef, Size size, Transformer transformer);

为了构建顶级Area，必须提供一个Transformer实例，所以，Area可使用该Transformer进行转换。你必须使用字符串做为单元格范围或建立一个CellRef单元格引用对象定义一个单元格区域，并设置区域Size。下面是一段构造一组嵌套模板XlsArea和命令的代码：

// 建立Transformer实例
// ...
// 建立顶级区域
XlsArea xlsArea = new XlsArea("Sheet1!A1:G15", transformer);
// 建立'department'区域
XlsArea departmentArea = new XlsArea("Sheet1!A2:G13", transformer);
// 建立'EachCommand'迭代departments
EachCommand departmentEachCommand = new EachCommand("department", "departments", departmentArea);
// 建立'employee'区域
XlsArea employeeArea = new XlsArea("Sheet1!A9:F9", transformer);
// 为'IfCommand'建立区域
XlsArea ifArea = new XlsArea("Sheet1!A18:F18", transformer);
// 使用指定区域建立'if'命令
IfCommand ifCommand = new IfCommand("employee.payment <= 2000", ifArea, new XlsArea("Sheet1!A9:F9", transformer));
// 添加'if'命令实例到employee区域
employeeArea.addCommand(new AreaRef("Sheet1!A9:F9"), ifCommand);
// 建立employee 'each'命令，添加到department区域
Command employeeEachCommand = new EachCommand( "employee", "department.staff", employeeArea);
departmentArea.addCommand(new AreaRef("Sheet1!A9:F9"), employeeEachCommand);
// 添加department 'each'命令到顶级区域
xlsArea.addCommand(new AreaRef("Sheet1!A2:F12"), departmentEachCommand);

2.2    使用Excel标记构建Area

你能够在Excel模板中使用特定标记构建Area。标记放置在区域中的第一个单元格的Excel注释中。注释内容以下所示：

jx:area(lastCell = "<AREA_LAST_CELL>")

<AREA_LAST_CELL>定义区域的最后一个单元格引用。该标记定义一个顶级区域从标记注释所在单元格开始，结束于<AREA_LAST_CELL>。

接下来，让咱们看看第一章的员工模板：

单元格A1的注释中定义了一个区域：

jx:area(lastCell="E3")

所以，咱们有一个区域覆盖单元格范围A1:E3。为了解析标记并建立XlsArea对象，咱们应该使用XlsCommentAreaBuilder类：

// 获取模板输入流
InputStream is = ObjectCollectionDemo.class.getResourceAsStream("模板.xls");
// 建立POI Workbook
Workbook workbook = WorkbookFactory.create(is);
// 使用POI Workbook建立PoiTransformer
PoiTransformer transformer = PoiTransformer.createTransformer(workbook);
// 建立XlsCommentAreaBuilder实例
AreaBuilder areaBuilder = new XlsCommentAreaBuilder(transformer);
// 使用AreaBuilder构造一个Area列表
List<Area> xlsAreaList = areaBuilder.build();
// 获取主Area
Area xlsArea = xlsAreaList.get(0);

如下2行代码的主要工做是构建区域：

AreaBuilder areaBuilder = new XlsCommentAreaBuilder(transformer);
List<Area> xlsAreaList = areaBuilder.build();

首先，你经过实例化XlsCommentAreaBuilder构建一个AreaBuilder实例。第二步，调用areaBuilder.build()方法从模板构造一个Area对象列表。在得到顶级区域列表以后，可使用它们进行Excel转换。

其实，第一章中使用的jXLS API的JxlsHelper类使用XlsCommentAreaBuilder做为默认AreaBuilder实现，因此咱们直接在Excel模板中编写注释，jXLS天然会为咱们建立区域。

2.3    使用XML配置构建Area

第一步，建立XML配置文件定义Area。

<xls>
    <area ref="Sheet1!A1:E3">
        <each items="employees" var="employee" ref="Sheet1!A1:E3">
            <area ref="Sheet1!A1:E3"/>
        </each>
    </area>
</xls>

根元素是xls。而后列出大量顶级area。

这里只有一个顶级区域A1:E3在Sheet1 Sheet中。

<area ref="Sheet1!A1:E3">

在area中，咱们定义了相关的命令元素。此处，咱们使用each xml元素定义了each命令。使用ref属性关联每一个命令相关的区域。

<each items="employees" var="employee" ref="Sheet1!A1:E3">

在each命令中有一个嵌套区域参数：

<area ref="Sheet1!A1:E3"/>