导入和导出.xlsx文档

本节概述了GcExcel .NET如何处理电子表格文档（.xlsx文件）。

当你使用GcExcel .NET创建工作簿并保存时，会自动将其导出到外部位置或文件夹。在GcExcel .NET中打开或加载文件时，你可以选择导入目标电子表格的整个模型，还是仅导入数据。GcExcel .NET提供了 Workbook.Open 方法，用于使用各种导入标志打开文件，这些标志可通过 XlsxOpenOptions 类的 XlsxOpenOptions.ImportFlags 属性进行访问。同样，要将工作簿导出为.xlsx文件，可以使用 Workbook.Save 方法，并使用GcExcel提供的各种保存选项来指定要跳过和导出的内容。这些选项如下：

Class name		Property Name	Description
Import Options	XlsxOpenOptions	XlsxOpenOptions.DoNotAutoFitAfterOpened	指定在打开Excel文件时是否自动调整行高。
		XlsxOpenOptions.DoNotRecalculateAfterOpened	指定在Excel文件打开后是否重新计算公式值。
		XlsxOpenOptions.ImportFlags	提供各种标志以导入工作表的各个方面。
		XlsxOpenOptions.DigitalSignatureOnly	指示是否以仅数字签名模式打开工作簿。在仅数字签名模式下，除非调用ISignature.Delete，否则现有签名将被保留。但在此模式下，您只能对现有签名行进行签名、添加不可见签名、移除已签名签名行的数字签名或移除不可见签名。其他更改将被丢弃。修改数字签名后，您需要保存工作簿以提交更改。若要以仅数字签名模式打开工作簿，则为True。否则，使用正常模式。默认值为false。
		XlsxOpenOptions.Password	The password for the xlsx file.
	OpenOptionsBase	OpenOptionsBase.FileFormat	表示工作簿的打开格式。
Export Options	XlsxSaveOptions	XlsxSaveOptions.IgnoreFormulas	将GcExcel工作表的公式单元格导出为Excel中的值单元格。
		XlsxSaveOptions.ExcludeUnusedStyles	导出文件时，排除未使用的样式。
		XlsxSaveOptions.ExcludeUnusedNames	导出文件时，排除未使用的名称。
		XlsxSaveOptions.ExcludeEmptyRegionCells	排除空单元格，即位于已使用范围之外、具有样式但不包含数据的单元格。
		XlsxSaveOptions.IsCompactMode	指示是否以紧凑模式保存工作簿。默认值为 false。
		XlsxSaveOptions.Password	这个xlsx文件的密码。
		XlsxSaveOptions.IncludeAutoMergedCells	指示是否包含自动合并的单元格。默认值为 false。
		XlsxSaveOptions.IncludeBindingSource	指示在保存文件时是否包含绑定源。默认值为true。
		XlsxSaveOptions.ExportSharedFormula	指定在保存工作簿时是否导出共享公式。默认值为true。
	SaveOptionsBase	SaveOptionsBase.FileFormat	表示工作簿的保存格式。

要从文件名导入和导出.xlsx文档，请参考以下示例代码：

// 创建一个新的工作簿。
Workbook workbook = new Workbook();

// 打开xlsx文件。
workbook.Open(Path.Combine("Resource", "Basic sales report1.xlsx"), OpenFileFormat.Xlsx);

// 将工作簿另存为xlsx文件。
workbook.Save("Exported.xlsx", SaveFileFormat.Xlsx);

要从文件流导入和导出.xlsx文档，请参考以下示例代码：

// 创建一个新的文件流以打开文件。
using FileStream openFile = new FileStream(Path.Combine("Resource", "Basic sales report1.xlsx"), FileMode.OpenOrCreate, FileAccess.Read);

// 创建一个新的工作簿。
var streamworkbook = new GrapeCity.Documents.Excel.Workbook();

// 打开xlsx文件。
streamworkbook.Open(openFile, OpenFileFormat.Xlsx);

// 创建一个新的文件流以保存文件。
using FileStream saveFile = new FileStream("Exported-Stream.xlsx", FileMode.OpenOrCreate, FileAccess.ReadWrite);

// 将工作簿另存为xlsx文件。
streamworkbook.Save(saveFile, SaveFileFormat.Xlsx);

另一种常见场景是，你可能只需要从电子表格或单元格区域导入数据。为处理这类场景，GcExcel .NET提供了 ImportData 方法，以便从外部工作表或单元格区域高效加载数据。有关仅导入数据的更多信息，请参阅下面的 “仅导入数据” 部分。

仅导入数据

若要仅从指定的工作表或单元格区域导入数据，GcExcel .NET 提供了 Workbook.ImportData 方法，该方法可直接打开工作表并为你获取数据。在只需要数据而无需处理其他对象模型的场景中，此方法很有用。ImportData 方法使用文件名或文件流以及源名称作为主要参数。你可以指定工作表、表或区域的名称作为数据来源。若要获取文件或文件流中使用的工作表和表的名称， Workbook 类提供了 Workbook.GetNames 方法，该方法返回可能的源名称数组。

//create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

// Open an excel file.
var fileStream = GetResourceStream("xlsx\\AgingReport.xlsx");

// Get the possible import names in the file.
// The names[0] and names[1] are sheet names: "Aging Report", "Invoices".
// The names[2] and names[3] are table names: "'Aging Report'!tblAging", "Invoices!tblInvoices".
var names = GrapeCity.Documents.Excel.Workbook.GetNames(fileStream);

// Import the data of a table "'Aging Report'!tblAging" from the fileStream.
var data = GrapeCity.Documents.Excel.Workbook.ImportData(fileStream, names[2]);

// Assign the data to current workbook.
workbook.Worksheets[0].Range[0, 0, data.GetLength(0), data.GetLength(1)].Value = data;
        
// Save to an excel file
workbook.Save("importdatafortable.xlsx");

在处理包含多个工作表或大量公式的大文件时，你可以使用 ImportData 方法来优化加载性能，因为它仅读取数据。该方法还提供了重载，即便你的文件包含大量数据，你也可以指定目标单元格范围，仅读取特定部分。

限制

使用 ImportData 方法时不会考虑公式，因为在这种情况下计算引擎不起作用。因此，单元格值会设置为 null。如果公式在文件中有缓存值，GcExcel 会返回该值。
如果工作表名称包含字符 !，例如 “Sheet!1”，则无法通过调用 ImportData(worksheetName) 解析工作表名称，此函数将返回 null。

注意：在 v5 版本中，ImportData 方法的参数名称已从 worksheetName 更改为 sourceName。如果使用早期版本的用户在调用 ImportData 方法时，其代码使用了参数名称 “worksheetName”，这将导致一个不兼容的变更。有关详细信息，请参阅发行说明。

控制绑定数据导出

限制

使用 ImportData 方法时不会考虑公式，因为在这种情况下计算引擎不起作用。因此，单元格值会设置为 null。如果公式在文件中有缓存值，GcExcel 会返回该值。
如果工作表名称包含字符 !，例如 “Sheet!1”，则无法通过调用 ImportData(worksheetName) 解析工作表名称，此函数将返回 null。

注意：在 v5 版本中，ImportData 方法的参数名称已从 worksheetName 更改为 sourceName。如果使用早期版本的用户在调用 ImportData 方法时，其代码使用了参数名称 “worksheetName”，这将导致一个不兼容的变更。有关详细信息，请参阅发行说明。

// Create a new workbook.
var workbook = new Workbook();

// Define a JSON data source.
var dataSource = "{ \"ds\":" +
                 "[\n" +
                 "   {\"Area\": \"North America\",\"City\": \"Chicago\",\"Category\": \"Consumer Electronics\",\"Name\": \"Bose 785593-0050\",\"Revenue\": 92800},\n" +
                 "   {\"Area\": \"North America\",\"City\": \"New York\",\"Category\": \"Consumer Electronics\",\"Name\": \"Bose 785593-0050\",\"Revenue\": 92800},\n" +
                 "   {\"Area\": \"South America\",\"City\": \"Santiago\",\"Category\": \"Consumer Electronics\",\"Name\": \"Bose 785593-0050\",\"Revenue\": 19550},\n" +
                 "   {\"Area\": \"Europe\",\"City\": \"Berlin\",\"Category\": \"Consumer Electronics\",\"Name\": \"Sony WH-1000XM4\",\"Revenue\": 30000},\n" +
                 "   {\"Area\": \"Asia\",\"City\": \"Tokyo\",\"Category\": \"Consumer Electronics\",\"Name\": \"Sony WH-1000XM4\",\"Revenue\": 45000},\n" +
                 "   {\"Area\": \"North America\",\"City\": \"Los Angeles\",\"Category\": \"Consumer Electronics\",\"Name\": \"Apple AirPods\",\"Revenue\": 60000},\n" +
                 "   {\"Area\": \"Europe\",\"City\": \"Paris\",\"Category\": \"Consumer Electronics\",\"Name\": \"Apple AirPods\",\"Revenue\": 55000},\n" +
                 "   {\"Area\": \"Asia\",\"City\": \"Seoul\",\"Category\": \"Consumer Electronics\",\"Name\": \"Samsung Galaxy Buds\",\"Revenue\": 40000},\n" +
                 "   {\"Area\": \"South America\",\"City\": \"Buenos Aires\",\"Category\": \"Consumer Electronics\",\"Name\": \"Samsung Galaxy Buds\",\"Revenue\": 35000},\n" +
                 "   {\"Area\": \"North America\",\"City\": \"Toronto\",\"Category\": \"Consumer Electronics\",\"Name\": \"Bose 785593-0050\",\"Revenue\": 50000}\n" +
                 " ]" +
                 "}";

// Add data source to worksheet.
var dataSourceSheet = workbook.Worksheets.Add();
dataSourceSheet.Name = "DataSource";
var table = dataSourceSheet.Tables.Add(dataSourceSheet.Range["A1:E4"], true);

// Set binding path.
table.BindingPath = "ds";
table.Columns[0].DataField = "Area";
table.Columns[1].DataField = "City";
table.Columns[2].DataField = "Category";
table.Columns[3].DataField = "Name";
table.Columns[4].DataField = "Revenue";

// Set data source.
dataSourceSheet.DataSource = new JsonDataSource(dataSource);

// Create pivot table sheet.
var pivotSheet = workbook.Worksheets[0];
pivotSheet.Name = "PivotSheet";

// Create pivot table.
var pivotCache = workbook.PivotCaches.Create(table);
var pivotTable = pivotSheet.PivotTables.Add(pivotCache, pivotSheet.Range["A1"], "pivottable1");

// Configure pivot table fields.
var fieldArea = pivotTable.PivotFields["Area"];
fieldArea.Orientation = PivotFieldOrientation.RowField;
var fieldCity = pivotTable.PivotFields["City"];
fieldCity.Orientation = PivotFieldOrientation.RowField;
var fieldName = pivotTable.PivotFields["Name"];
fieldName.Orientation = PivotFieldOrientation.ColumnField;
var fieldRevenue = pivotTable.PivotFields["Revenue"];
fieldRevenue.Orientation = PivotFieldOrientation.DataField;
pivotSheet.UsedRange.AutoFit();
pivotTable.ColumnGrand = false;
pivotTable.RowGrand = false;
pivotTable.Refresh();

var saveOptions = new XlsxSaveOptions();

// Set IncludeBindingSource property to false to exclude the binding source from being exported.
saveOptions.IncludeBindingSource = false;

// Save the workbook.
workbook.Save("IncludeBindingSourceOption.xlsx", saveOptions);

注意：在数据绑定更改表的大小后，IncludeBindingSource 属性不会将表恢复到其原始大小。此属性仅控制是否导出数据。

共享公式导出选项

在导出为.xlsx文件时，GcExcel .NET默认启用共享公式功能，这与Microsoft Excel类似，目的是减小文件大小。如果您需要将导出的文件与不支持共享公式的第三方库配合使用，可以通过将 ExportSharedFormula 属性设置为false来禁用此功能。请注意，禁用共享公式会增加导出的.xlsx文件的大小。

以下示例展示了在导出.xlsx文件时如何禁用共享公式：

// 创建一个新工作簿。
var workbook = new Workbook();
var sheet = workbook.ActiveSheet;

// 为B1:B5区域设置公式。
sheet.Range["B1:B5"].Formula = "IF(A1>100,SUM(A1:A5)*AVERAGE(A1:A5),MAX(A1:A5)-MIN(A1:A5))";

// 禁用共享公式。
var saveOptions = new XlsxSaveOptions();
saveOptions.ExportSharedFormula = false;

// 保存Excel文件。
workbook.Save("NoSharedFormula.xlsx", saveOptions);

在Office Open XML (OOXML) .xlsx文件中，根据 ExportSharedFormula 设置为true或false，公式将以共享公式或独立公式的形式存储，如下表所示：

启用共享公式

<sheetData>
    <row r="1">
        <c r="B1">
            <f t="shared" si="0" ref="B1:B5">IF(A1&gt;100,SUM(A1:A5)*AVERAGE(A1:A5),MAX(A1:A5)-MIN(A1:A5))</f>
        </c>
    </row>
    <row r="2">
        <c r="B2">
            <f t="shared" si="0"/>
        </c>
    </row>
    <row r="3">
        <c r="B3">
            <f t="shared" si="0"/>
        </c>
    </row>
    <row r="4">
        <c r="B4">
            <f t="shared" si="0"/>
        </c>
    </row>
    <row r="5">
        <c r="B5">
            <f t="shared" si="0"/>
        </c>
    </row>
</sheetData>

禁用共享公式

<sheetData>
    <row r="1">
        <c r="B1">
            <f>IF(A1&gt;100,SUM(A1:A5)*AVERAGE(A1:A5),MAX(A1:A5)-MIN(A1:A5))</f>
        </c>
    </row>
    <row r="2">
        <c r="B2">
            <f>IF(A2&gt;100,SUM(A2:A6)*AVERAGE(A2:A6),MAX(A2:A6)-MIN(A2:A6))</f>
        </c>
    </row>
    <row r="3">
        <c r="B3">
            <f>IF(A3&gt;100,SUM(A3:A7)*AVERAGE(A3:A7),MAX(A3:A7)-MIN(A3:A7))</f>
        </c>
    </row>
    <row r="4">
        <c r="B4">
            <f>IF(A4&gt;100,SUM(A4:A8)*AVERAGE(A4:A8),MAX(A4:A8)-MIN(A4:A8))</f>
        </c>
    </row>
    <row r="5">
        <c r="B5">
            <f>IF(A5&gt;100,SUM(A5:A9)*AVERAGE(A5:A9),MAX(A5:A9)-MIN(A5:A9))</f>
        </c>
    </row>
</sheetData>

当前限制

GcExcel .NET不支持导入xls文件。
GcExcel .NET不支持将xlsx文件导出为XPS格式。
GcExcel .NET不支持以下功能。如果您导入包含这些功能的xlsx文件，然后再次导出，这些功能将不会保留在导出的xlsx文件中。
- 导致对象丢失的功能
  - SmartArt
  - 3D模型
  - 墨迹
  - 股票/货币/地理（数据类型）
  - 作为单元格数据类型的复选框
- 导致对象外观改变的功能
  - 在工作簿中应用了效果的形状
  - 用于假设分析的数据表
- 可能导致导出文件损坏的功能
  - 地图图表
- 导致内部数据丢失的功能
  - 添加到数据模型中的数据
  - 通过XML导入的数据
- 导致云集成丢失的功能
  - 与“表单”功能使用的调查问卷表单的集成
  - 与通过“自动化”选项卡添加的脚本的集成