GrapeCity Documents V7.0 Update1 新特性

服务端表格组件 GrapeCity Documents for Excel 更新说明

改进的模板语言，性能更佳

在我们最近的努力中，我们承担了重构 GcExcel 模板的任务，主要着重于提升性能和稳定性。我们的目标是满足更广泛的用户需求和使用场景，确保用户拥有流畅高效的体验。最近的改进包括：

• 对于缺少的数据源，将视为Null
• 启用固定布局功能，使其在分页和非分页模式下无缝运行
• 增强模板处理功能，支持图片和形状
• 提升了在处理具有合并单元格的模板时的性能
• 确保从旧模板设计中无缝继续功能，而不引入任何破坏性变化

欢迎查看我们的演示以获得更佳的体验。

Help .NET| Help Java| Demo .NET| Demo Java

自定义排序顺序和多列排序

GcExcel 模板长期以来一直支持使用语法定义模板单元格中的排序方向来对模板数据进行排序。但实际上场景中，需要根据其他单元格的值对单元格进行排序，且进一步需求使用多个单元格值对数据进行排序的能力。为了满足这种需求，GcExcel 扩展了语法，使其能够同时包含多个排序条件，而不是使用不同的排序条件多次进行模板填充。

支持的多种情况包括：

• 根据其他列的顺序对当前列进行排序
• 根据多个其他列的顺序对当前列进行排序
• 自定义排序顺序

以下示例中，将按日期（列C）升序排序列A中的数据，然后按销售额（列D）降序排序。

在下面的资源中详细阅读增强的排序语法和支持的场景。

Help .NET| Help Java| Demo .NET| Demo Java

取消执行中的 ProcessTemplate 方法

在某些情况下，由于数据量大或者对基本原因不明确，导致 ProcessTemplate 方法的执行时间延长，展示填充的数据会有延迟。因此，如果有一种方法可以中断 processTemplate 方法并恢复到未填充数据模板的初始状态，以便用户选择限制数据源的数量并重新处理模板将会很有用。

GcExcel 现在支持通过调用带有 CancellationToken 参数的 Workbook.ProcessTemplate(CancellationToken) 重载来中断 processTemplate 方法。您可以通过以下三种方式中断模板处理：

• 使用 CancellationTokenSource.Cancel 立即请求取消
• 使用 CancellationTokenSource.CancelAfter 在指定延迟时间后请求取消
• 使用 CancellationTokenSource.Dispose (.NET) 或 close (Java) 释放资源

当取消成功时（ProcessTemplate 执行中且通过CancellationTokenSource请求取消），Workbook.ProcessTemplate 方法将抛出 OperationCanceledException（.NET System 类的情况）或 CancellationException（Java Platform SE 8 的情况）。

在处理异常时，workbook 对象处于一个中间状态（数据可能仅填充了一部分）。此时，需要决定是否继续使用该 workbook 对象。如果希望使用模板填充前的 workbook，则需要在模板填充前，对workbook进行备份，在操作取消后进行还原。 以下代码在当前线程中使用 workbook 并在另一个线程中取消：

                                
C#
using (CancellationTokenSource cancellation = new CancellationTokenSource())
{
    void cancelHandler(object sender, ConsoleCancelEventArgs e)
    {
        // Exit process gracefully
        e.Cancel = true;
        cancellation.Cancel();
    };
    Console.CancelKeyPress += cancelHandler;
    cancellation.CancelAfter(TimeSpan.FromSeconds(10));
    Console.WriteLine("Start ProcessTemplate.");
    try
    {
        workbook.ProcessTemplate(cancellation.Token);
        Console.WriteLine("ProcessTemplate finished.");
    }
    catch (OperationCanceledException ex) when (ex.CancellationToken == cancellation.Token)
    {
        Console.WriteLine("ProcessTemplate was canceled.");
    }
}
                                
                            

欢迎查看以下资源来了解更多关于该功能的内容。

Help .NET| Help Java| Demo .NET| Demo Java

CalculationMode 选项

此功能专门为 SpreadJS 用户设计，他们在后端使用 GcExcel 生成大量的 Excel 文件。有些情况下，用户希望避免自动计算以减少打开工作表所需的时间。此外，在某些场景中，用户只想导出特定的工作表而不是整个工作簿。值得注意的是，Excel 文件可能包含跨工作表的公式，用户希望在导出过程中这些公式保持未计算状态。因此，用户正在寻找一个选项来启用/禁用手动计算，以更好地控制这些方面。

为了解决这个问题，GcExcel 引入了 Workbook.Options.Formulas.CalculationMode 属性。该属性允许在工作表上设置公式的计算模式，从而在打开工作表时控制公式的计算。该属性支持以下枚举值：

• Automatic：自动
• Semiautomatic：除模拟运算表外，自动重算
• Manual：手动

该属性在 Excel I/O、SpreadJS I/O 和 SSJSON I/O 中受支持。

以下代码演示了将计算模式更改为 Manual，其中在 MS Excel 中打开导出的 XLSX 文件时不会自动计算公式。

                                
C#
IWorksheet worksheet = workbook.Worksheets[0];
worksheet.Range["A1:F7"].Value = data;
worksheet.Range["A:F"].ColumnWidth = 15;

//add table.
worksheet.Tables.Add(worksheet.Range["A1:F7"], true);

//show totals
worksheet.Tables[0].ShowTotals = true;
worksheet.Tables[0].Columns[4].TotalsCalculation = TotalsCalculation.Average;
worksheet.Tables[0].Columns[5].TotalsCalculation = TotalsCalculation.Average;

var comment = worksheet.Range["F8"].AddComment("Please press F9 to calculate the formula.");
comment.Visible = true;

//set calculation mode to manual
workbook.Options.Formulas.CalculationMode = CalculationMode.Manual;
        
// Save to an excel file
workbook.Save("CalculationOptions.xlsx");
                                
                            

Help .NET| Help Java| Demo .NET| Demo Java

以流（stream）的方式为导出任务注册自定义字体 - 仅 GcExcel Java 支持

此前，GcExcel Java 提供了 Workbook.FontsFolderPath 接口，允许用户指定保存所需字体文件的目录。需要注意的是，FontsFolderPath 必须表示一个绝对磁盘路径。然而，某些环境存在限制，阻止用户直接在磁盘上存储字体。在这种情况下，用户只能提供字体流。例如，当用户将其应用程序部署为 Java 中的 war 包时，字体被打包在 war 包中。因此，在这些情况下，GcExcel 必须提供一个能够适应字体流的接口。

在 GcExcel 的 Workbook 类中，已经加入了 Workbook.FontProvider 字段，以便用户通过字体流提供字体，用于自适应、PDF 导出和图像导出等任务。用户可以实现 IFontProvider 接口及其方法， getFontFilePaths 和 getFont，来实现注册字体。

getFontFilePaths 方法用于检索所有字体文件路径。另一方面，getFont 方法负责返回与给定字体文件路径对应的字体流。当用户使用 FontProvider 类时，GcExcel 将专门在字体流中搜索字体路径。如果没有实现 FontProvider ，GcExcel 将默认搜索 FontsFolderPath 中的字体。

以下示例展示了如何通过字体流设置字体：

                                
Java
// Create a new workbook.
Workbook workbook = new Workbook();
IWorksheet sheet = workbook.getWorksheets().get(0);

// Set style of the font.
sheet.getRange("A1").setValue("Sheet1");
sheet.getRange("A1").getFont().setName("Arial");
sheet.getRange("A1").getFont().setColor(Color.GetRed());
sheet.getRange("A1").getInterior().setColor(Color.GetGreen());

// Implement FontProvider.
Workbook.FontProvider = new IFontProvider() {
    @Override
    public List getFontFilePaths() {
        return new ArrayList<>(Arrays.asList(
                "fonts\\arial.ttf",
                "fonts\\arialbd.ttf",
                "fonts\\ariali.ttf"
        ));
    }

    @Override
    public InputStream getFont(String fontFilePath) {
        return getClass().getClassLoader().getResourceAsStream(fontFilePath);
    }
};
// Save the workbook.
workbook.save("FontStreaming.pdf", SaveFileFormat.Pdf);
                                
                            

Help Java| Demo Java

在跨工作簿公式中支持表格引用

在大型和复杂的 Excel 文件中，通常公式会引用其他工作簿中的数据，无论是内部还是外部。传统的方法会通过复制的方式，将数据整理到同一个工作簿中。但一种更有效的方法是直接使用跨工作簿公式引用外部工作簿中的数据。因此为了增强该场景下的易用性，在 v7.1 版本中，GcExcel 支持在跨工作簿公式中使用表格引用。

                                
Plain Text
workbook.Worksheets[0].Range["B1"].Formula = "=SUM('[Sales.xlsx]'!Table1[Sales])";
                                
                            

Help .NET| Help Java

忽略范围内的错误

为了能让用户在导出Excel时，不显示单元格中左上角的绿色三角，GcExcel 在 IRange 接口中引入了 IgnoredError 属性以及 IgnoredErrorType 枚举，允许用户在 Excel 中有选择地忽略诸如无效的公式结果、以文本形式存储的数字、相邻单元格中不一致的公式等错误。

                                
C#
worksheet.Range["A8:F11"].IgnoredError = IgnoredErrorType.All;
                                
                            

Help .NET| Help Java| Demo .NET| Demo Java

在 Excel 文件中导出条形码为图片

在保存 Excel 文件时，您可以选择保留包含从 SpreadJS 或 GcExcel 生成的条形码。GcExcel 添加了 Workbook.ConvertBarcodeToPicture(ImageType) 方法，在保存为Excel之前，使用该方法可以将条形码转换为图像，并应用于所有工作表，以便在 Excel 文件中无缝存储，消除了出现 "#Ref" 值的情况。在没有显式指定 ImageType 参数的情况下，默认设置为 SVG 图像类型。

Help .NET| Help Java| Demo .NET| Demo Java

搜索带有标签的单元格

GcExcel 提供有 Tag 属性，该属性可与 SpreadJS 配合使用。该属性可以包含指定类型的数据并将其附加在单元格，行，列或者工作表上。此外，您可以使用 SSJSON 导入/导出带有简单数据的标签。在 v7.1 版本中，GcExcel 引入了 SpecialCellType.Tags 和 IRange.SpecialCells(SpecialCellType.Tags) 重载，便于对指定范围内带有标签的单元格进行识别。

以下代码用于查找带有标签的单元格并将它们设置为红色：

                                
C#
IRange allTagCells = worksheet.UsedRange.SpecialCells(SpecialCellType.Tags);
allTagCells.Font.Color = Color.Blue;

foreach (var area in allTagCells.Areas)
{
    for (int i = 0; i < area.Cells.Count; i++)
    {

        if (area.Cells[i] != null && area.Cells[i].Tag is string && int.Parse(area.Cells[i].Tag as string) % 10 == 0)
        {
            area.Cells[i].Interior.Color = Color.Red;
        }
    }
}
                                
                            

Help .NET| Help Java| Demo .NET| Demo Java

SpreadJS 兼容特性

GcExcel 整合了额外的 SpreadJS 特性，提升了与客户端端的 SpreadJS 产品的兼容性。需要强调的是，这些新特性仅与 SpreadJS 配合使用，不兼容 Microsoft Excel。

• 获取并设置单元格背景图片 - Help .NET | Help Java | Demo .NET | Demo Java
• 支持 GanttSheet 的无损 .sjs/ssjson 输入/输出 - Demo .NET | Demo Java
• 支持 ReportSheet 的无损 .sjs/ssjson 输入/输出 - Demo .NET | Demo Java