自定义XML部件

GcExcel Java 支持通过自定义XML部件，将自定义XML数据存储到工作簿中。自定义XML部件包含一段XML有效负载，该数据独立于工作表数据，可供处理该工作簿的应用程序或宏进行访问。

你可以借助自定义XML部件，在应用程序与Microsoft Excel之间传输XML数据。例如：应用程序可在XLSM工作簿下载前向其中写入XML数据；当用户编辑工作簿、宏更新XML数据后，应用程序能够重新打开上传后的工作簿，并读取更新后的数据。

CustomXMLParts

调用Workbook类的getCustomXmlParts方法，即可获取ICustomXmlPartCollection集合。集合内每一个ICustomXmlPart对象都拥有自动生成的唯一标识ID，同时以字节数组形式承载XML数据。

添加自定义XML部件

调用ICustomXmlPartCollection接口的add方法添加自定义XML部件。GcExcel会为每个部件生成唯一ID。通过setData方法，可将XML有效负载以字节数组形式进行赋值。

下方示例向工作簿中添加客户与订单XML数据。

// 创建工作簿
Workbook workbook = new Workbook();
ICustomXmlPartCollection customXmlParts = workbook.getCustomXmlParts();
// 添加客户XML数据
ICustomXmlPart customerPart = customXmlParts.add();
customerPart.setData("<customer><name>Grace Green</name><region>West</region></customer>".getBytes(StandardCharsets.UTF_8));
// 添加订单XML数据
ICustomXmlPart orderPart = customXmlParts.add();
orderPart.setData("<order><number>SO-1001</number><total>1680</total></order>".getBytes(StandardCharsets.UTF_8));
// 保存工作簿
workbook.save("AddCustomXmlParts.xlsx");

getId方法为只读方法。生成的ID会随工作簿一同保存，工作簿保存并重新打开后仍然有效。

注意： GcExcel不会对写入自定义XML部件的数据做合法性校验。保存工作簿前，请确保数据为合法XML格式。无效的XML内容可能导致Microsoft Excel无法打开生成的文件。

获取并更新自定义XML部件

你可以根据部件ID或者从零开始的索引获取自定义XML部件。如果需要在重新打开工作簿后定位同一个部件，使用ID查找会更加合适。

以下示例演示如何获取并更新自定义XML部件：

Workbook workbook = new Workbook();
ICustomXmlPartCollection customXmlParts = workbook.getCustomXmlParts();
// 添加自定义XML部件
ICustomXmlPart customerPart = customXmlParts.add();
customerPart.setData("<customer><name>Grace Green</name><region>West</region></customer>".getBytes(StandardCharsets.UTF_8));
String customerPartId = customerPart.getId();
// 通过ID获取部件
ICustomXmlPart partById = customXmlParts.get(customerPartId);
// 通过索引获取第一个部件
ICustomXmlPart firstPart = customXmlParts.get(0);
// 更新XML数据
partById.setData("<customer><name>Grace Green</name><region>East</region></customer>".getBytes(StandardCharsets.UTF_8));
// 保存工作簿
workbook.save("UpdateCustomXmlParts.xlsx");

若找不到指定ID，按ID检索将返回null；若传入的索引超出有效范围，按索引检索会抛出ArgumentOutOfRangeException异常。

setData方法返回的字节数组是存储数据的副本。直接修改返回的数组无法更新自定义XML部件；需要将修改后的数组重新传入setData方法，才能完成部件数据更新。

删除自定义XML部件

ICustomXmlPartCollection接口实现了IEnumerable<ICustomXmlPart>，你可以遍历集合查看或修改其中的部件。

调用remove方法，可根据部件ID或从零开始的索引删除部件。

下面示例遍历集合，并分别通过ID和索引删除自定义XML部件：

Workbook workbook = new Workbook();
ICustomXmlPartCollection customXmlParts = workbook.getCustomXmlParts();
ICustomXmlPart customerPart = customXmlParts.add();
customerPart.setData("<customer><name>Grace Green</name></customer>".getBytes(StandardCharsets.UTF_8));
ICustomXmlPart orderPart = customXmlParts.add();
orderPart.setData("<order><number>SO-1001</number></order>".getBytes(StandardCharsets.UTF_8));
// 遍历所有自定义XML部件
for (ICustomXmlPart customXmlPart: customXmlParts) {
    String id = customXmlPart.getId();
    byte[] data = customXmlPart.getData();
}
// 通过ID删除部件
customXmlParts.remove(customerPart.getId());
// 如果集合内还有部件，则通过索引删除剩余的第一个部件
if (customXmlParts.getCount() > 0) {
    customXmlParts.remove(0);
}
// 保存工作簿
workbook.save("RemoveCustomXmlParts.xlsx");

如果传入的ID或索引无法匹配到任何现存部件，remove方法不会对集合执行任何改动。