工作簿的基本用法

概述

Excel 中，工作簿是最基本的对象，工作簿可以包含一个或多个工作表。在 GcExcel 中，操作 Excel 文件也需要从创建工作簿开始。

基础用法

创建工作簿

在 GcExcel 中，可以使用 Workbook类创建工作簿的实例。

默认情况下，工作簿包含一个默认名称为Sheet1的空工作表，该工作表在创建工作簿类的新实例时立即创建。

请参阅以下示例代码以使用GcExcel Java创建工作簿。

Workbook workbook = new Workbook();

要向工作簿中添加更多工作表，请参阅本文档中的使用工作表。

创建工作簿后，您可以打开工作簿以合并修改，将更改保存回工作簿，并使用密码对其进行保护，以确保安全性。

打开工作簿

基本用法

您可以通过调用工作簿类的 Open 方法来打开现有的电子表格文件 (Excel 或 SpreadJS 文件)。

示例代码如下：

Workbook workbook = new Workbook();
workbook.open("OpenWorkbook.xlsx");

GcExcel 支持的文件格式如下：

.xlsx
.xlsm
.xltx
.csv
.json
.ssjson
.sjs

type=warning
请注意，如果打开不受支持的文件格式时会引发异常。

打开选项

在某些情况下，例如打开大 Excel 文件时，仅期望读取数据，或者公式。因此，为了满足这类需求，GcExcel 提供了打开选项，例如：XlsxOpenOptions

通过 OpenOptions 您可以设置以下属性：

打开选项	描述
Import Flags	NoFlag=0 Data=1 Formulas=2	默认仅读取工作表中的数据只读取工作表中的数据、公式、定义名称和表。表格公式中包含表格。
setDoNotRecalculateAfterOpened	导入后是否自动计算公式。默认值为 false
setDoNotAutofitAfterOpened	加载文件后，是否自动调整行高度。默认值为 false

打开选项

描述

Import Flags

NoFlag=0

Data=1

Formulas=2

默认

仅读取工作表中的数据

只读取工作表中的数据、公式、定义名称和表。表格公式中包含表格。

setDoNotRecalculateAfterOpened

导入后是否自动计算公式。默认值为 false

setDoNotAutofitAfterOpened

加载文件后，是否自动调整行高度。默认值为 false

请参阅以下示例代码。

// Opening a workbook
workbook.open("OpenWorkbook.xlsx");
        
// Opening a workbook with Import options
        
// Import only data from .xlsx document
XlsxOpenOptions options = new XlsxOpenOptions();
options.setImportFlags(EnumSet.of(ImportFlags.Data));
workbook.open("OpenWorkbookWithOptions.xlsx", options);
        
// Don't recalculate after opened.
options.setDoNotRecalculateAfterOpened(true);

//Don't autofit row height
options.setDoNotAutoFitAfterOpened(true);

注意： 在打开工作簿时，您可以使用工作簿类的 isEncryptedFile 方法检查它是否受密码保护。如果工作簿受到密码保护，则需要在每次打开工作簿时提供密码。
当在GcExcel Java中打开密码保护的 Excel 文件(版本2013或更高)时，将抛出非法的密钥大小异常。这是因为 Java 编译器默认支持128位密钥，不支持256位密钥(Excel 2013或更高版本使用256位密钥)。在这样的场景中，用户可以应用JCE unlimited strength策略文件来解决这个问题。

打开 JSON 文件时，也支持 DeserializationOptions。

请参阅以下示例代码以打开带选项和不带选项的 JSON 文件。

//create a new workbook
Workbook workbook = new Workbook();
        
// Import JSON without options
workbook.open("spread_js_exported.json");

// Import JSON with options
DeserializationOptions options = new DeserializationOptions();
options.setIgnoreStyle(true);
workbook.open("spread_js_exported.json", options);

保存工作簿

通过调用工作簿类的save方法，可以保存在现有工作簿中所做的更改。

请参考以下示例代码保存工作簿。

// Saving an excel file (.xlsx document)
workbook.save("SaveExcel.xlsx");
        
// Saving an excel file with saveFileFormat
workbook.save("SaveExcelWithFormat.xlsx", SaveFileFormat.Xlsx);
        
// Saving an excel file while setting password
XlsxSaveOptions options = new XlsxSaveOptions();
options.setPassword("123456");
workbook.save("SaveExcelWithPassword.xlsx", options);

有时工作簿可能包含许多未使用的样式、未使用的定义名称或应用了样式的空单元格，这会增加文件大小。XlsxSaveOptions 类为您提供了保存 .xlsx 文件并忽略上述项目的选项，以便您可以优化文件大小。当类的 ExcludeEmptyRegionCells 方法设置为 true 时，可以排除所用数据范围之外的空单元格。同样，通过将 ExcludeUnusedNames 和 ExcludeUnusedStyles 方法设置为 true，可以在导出时排除工作簿中未使用的名称和样式。该类还提供 IgnoreFormula 方法，该方法允许您保存 .xlsx 文件时忽略公式，仅保存公式计算您的值。如果您不需要工作簿的扩展功能，您甚至可以在设置 IsCompactMode 属性之后以压缩模式保存工作簿。

下面的示例代码显示了如何使用各种选项保存工作簿：

// Create a new workbook
Workbook workbook = new Workbook();
InputStream fileStream = getResourceStream("xlsx/file needs to be optimized.xlsx");
workbook.open(fileStream);

XlsxSaveOptions options = new XlsxSaveOptions();
options.setExcludeEmptyRegionCells(true);
options.setExcludeUnusedStyles(true);
options.setExcludeUnusedNames(true);

workbook.save(outputStream, options);

GcExcel 支持保存的格式如下：

.xlsx
.xlsm
.xltx
.csv
.html
.pdf
.json
.ssjson
.sjs

如需查看详情，请查看优化文件大小的选项演示。