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

1、EXCEL 工作簿大小优化

Excel 文件可能经常包含未使用的格式、定义的名称或空区域单元格。这些单元格最初可能具有数据和格式，但随着时间的推移不再使用，数据被删除但格式保留。工作簿中存在大量此类单元格会导致性能下降并增加工作簿的大小。

使用 GcExcel，您现在可以排除此类单元格并在保存工作簿的同时减小工作簿的大小。

GcExcel 在 XLSXSaveOptions() 类中提供了新选项，以使用 Workbook.Save(..) 方法优化您的工作簿。

引入了三个新选项：

• XlsxSaveOptions.ExcludeUnusedStyles{ get; set; } - 指示是否排除用户定义但从未使用过的单元格样式。 默认值为 false
• XlsxSaveOptions.ExcludeUnusedNames{ get; set; } - 指示是否排除用户定义但从未使用过的定义名称。 默认值为 false
• XlsxSaveOptions.ExcludeEmptyRegionCells{ get; set; } - 指示是否排除所用数据范围之外的任何空单元格（没有数据或只有样式的单元格）

下面的代码排除了工作簿中任何未使用的样式、名称或空区域单元格，从而减小了工作簿的大小。

                                    
//create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();
Stream fileStream = this.GetResourceStream("xlsx\File needs to be optimized.xlsx");
workbook.Open(fileStream);

XlsxSaveOptions options = new XlsxSaveOptions {
    ExcludeEmptyRegionCells = true,
    ExcludeUnusedStyles = true,
    ExcludeUnusedNames = true
};

using (MemoryStream outputStream = new MemoryStream()) {
    workbook.Save(outputStream, options);
    outputStream.Position = 0;
    workbook.Open(outputStream, OpenFileFormat.Xlsx);
}

// Save to an excel file
workbook.Save("OptionsToOptimizeFileSize.xlsx");
                                    
                                

2、JDK8 是GcExcel(for Java) 最低支持的版本

由于 JDK 6 和 JDK 7 已经结束，GcExcel 将不再支持 JDK 6 和 7，现在将从 v6 版本开始面向 JDK 8。 GcExcel 现在也不再需要将 GcExcel 扩展包添加到项目中。

3、GcExcel 模板增强功能

分页电子表格报告新的增强功能

在上一个版本中，GcExcel 模板引入了“TemplateOptions.PaginationMode”和 CountPerPage 属性 (CP) 来管理工作簿分页到单独的工作表中，工作表布局中的行数固定。

在 v6 中，引入了一个新的 API 来完成额外的布局。借助分页模板功能，您可以使用新 API 创建以下类型的布局：

在分页电子表格中为页面或组配置页眉/页脚

添加了新的 API: RepeatType、NoRepeatAction 和 RepeatWithGroup 以重复组内的单元格值或为每个页面配置页面/组页眉/页脚。

• RepeatType 属性确定在设置 RepeatWithGroup 属性时如何在组内重复单元格值
• NoRepeatAction 属性决定了普通内容不显示在当前页面时如何设置删除方式
• RepeatWithGroup 属性指定模板中与生成的报告中的组重复的单元格引用

在以下快照中，RepeatType 设置为患者和标本信息的 FirstPage，RepeatWithGroup 设置为 D3，这意味着页眉范围 A6:I18 为 D3 中设置的每个新患者 ID 重复。

组的页码和页数

在固定行布局中，引入了新属性 - PageNumber 用于设置当前页的页码，PageCount 用于设置当前组的页数。 这将有助于指示组的当前页码和组中的总页数。 这两个属性可以使用语法定义 - PageNumber(string cell) 和 PageCount(string cell)。 在下面的布局中，患者 ID P001 的信息被分页为四页，并且可以显示当前页码。

根据页面大小对电子表格进行分页

到目前为止，您一直在根据 CountPerPage (CP) 属性对工作表进行分页，该属性在工作表布局中生成固定数量的行并分页到多个工作表中。 但是，可以根据页面大小对报表进行分页，页面大小由 Excel 中的页面设置设置决定。 在这种情况下，如果 CP 属性未设置或设置为*，则 TemplateOptions.PaginationMode 为 true。 该报告将根据页面大小分页到多个工作表中。

在这种类型的分页中，添加了新属性 RepeatOutput、KeepTogether 和 AttachTo，它们有助于在每页的最大行数之后插入分页符，而不管组和每个组的小计。 在这种情况下，最大行数取决于纸张大小。

• RepeatOutput 属性指定合并单元格的值是仅出现在报表的第一页还是每一页
• KeepTogether 属性确保单元格及其后代出现在同一页上。 该属性允许您选择是否要将单元格与水平分页或垂直分页保持在一起
• AttachTo 属性允许将单元格模板与另一个单元格绑定，以确保它不会单独出现在页面上。 您可以使用此属性来防止文档中出现孤立的页眉/页脚

下面的示例显示了一个根据页面大小分页的报告。 根据 Excel 的页面设置设置，当行达到工作表中的最大行数时，无论模板组设置如何，报告都会分页到下一个工作表。 在这里，“RepeatOutput”设置在合并的单元格上，我们可以选择在每个工作表上重复或不重复。

保留原始模板或流程特定的模板工作表

到现在为止，您可以将整个工作簿模板处理成一个报告。但是，GcExcel 现在引入了 Workbook.GenerateTemplate() 方法，该方法返回一个新的工作簿实例而不改变原始模板工作簿。

此外，您的工作簿可能有多个模板，您可能只需要处理一个特定的模板工作表。GcExcel 添加了一个条款来处理来自许多模板的特定模板工作表。 您可以将这个特定的模板工作表传递给新的 Workbook.GenerateTemplate() 方法。请参阅下面的代码：

    
IWorkbook workbook = workbook.GenerateReport(new IWorksheet[] { sheet });
    

该方法返回一个新的工作簿实例，仅处理作为参数传递的模板而不更改原始模板。 如果未提供参数，GenerateTemplate() 方法将处理所有工作表。

在以下示例中，仅处理了三个工作表中的特定工作表“PurchaseOrder”。

    
// Add data source
workbook.AddDataSource("dt", salesData);

// Init template global settings
workbook.Names.Add("TemplateOptions.KeepLineSize", "true");

// Process the template and return the specified report
IWorkbook report = workbook.GenerateReport(workbook.Worksheets["PurchaseOrder"]);

// Save the report as xlsx to a stream
report.Save(outputStream);
    

4、获取所选区域的使用范围

GcExcel 在工作表中提供了 UsedRange 属性和 GetUsedRange 方法来获取工作表中所有已使用的范围。 您可能还希望获取选定范围内的已用范围，而不是已用范围的整个工作表。 GcExcel 将 UsedRange 属性和 GetUsedRange 方法添加到 IRange 接口。

以下代码在选定范围内查找使用范围并更改使用范围的单元格背景颜色。

    
// Init data.
IRange range = sheet.Range["B2:D4"];
range.Value = "Unused";

// Select range.
IRange selectedRange = sheet.Range["C3:E5"];
selectedRange.Select();

// Get the used range from selectedRange.
IRange usedRange = selectedRange.UsedRange;
usedRange.Value = "Used";
usedRange.Interior.Color = Color.LightBlue;
    

5、添加具有范围参考或定义名称的形状文本

假设您有大量员工销售数据，并希望使用任何图形图像突出显示当月的总销售额。 您可以将形状与数据绑定公式链接起来，这可以动态地表示所选形状中当月的销售额。 在某些情况下，工作表中的形状可以包含引用范围或定义名称的文本。 此文本可以根据范围内的数据或定义的名称进行更改。 GcExcel 添加 IShape.Formula 属性来设置或删除当前形状的范围引用或定义的名称。 您可以设置 IShape.Formula=”=A1”（到单元格/区域）或 IShape.Formula = “=refname”（到定义的名称）。

下面的代码将公式设置为一个形状，该形状使用一个公式引用单元格 G8：

                                    
// set shape formula to G8
IShape shapeResult = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["B7:D8"]);
shapeResult.Formula = "=G8";
                                    
                                

6、使用直接方法将形状/图片添加到单元格/单元格区域

为了简化将 IShape 添加到范围的过程，提供了一系列直接方法来将 IShape 添加到范围而无需获取其坐标。 GcExcel 向 IShape 接口添加了五个新方法：

• AddPicture() - 根据当前工作表指定范围内的现有文件创建图片
• AddShape() - 返回表示当前工作表指定范围内的新自选图形的对象
• AddChart() - 在当前工作表的指定范围内创建图表
• AddConnector() - 在当前工作表的指定范围内创建一个连接器
• AddCameraPicture() - 在当前工作表上创建从参考范围到目标范围的图片

以下代码将图片与连接器一起直接添加到范围：

                                        
var workbook = new GrapeCity.Documents.Excel.Workbook();
IWorksheet worksheet = workbook.Worksheets[0];

// Place the same picture to two range
System.IO.Stream stream = this.GetResourceStream("puffins.jpg");
IShape smallPicture = worksheet.Shapes.AddPicture(stream, ImageType.JPG, worksheet.Range["B2:B4"]);
IShape bigPicture = worksheet.Shapes.AddPicture(stream, ImageType.JPG, worksheet.Range["D4:F12"]);

worksheet.Shapes.AddConnector(ConnectorType.Straight, worksheet.Range["C2:F3"]);
worksheet.Shapes.AddConnector(ConnectorType.Straight, worksheet.Range["B5:C12"]);

// Save to an excel file
workbook.Save("AddPictureToRange.xlsx");
                                        
                                

7、支持新的 Lambda 函数，包括帮助函数

如果您的工作表包含复杂的计算，您必须详细了解它们。 这可能容易出错并且难以维护。 为什么不只添加一次复杂的计算，给它一个简单的名字，然后在你的工作表中重复使用它呢？ GcExcel 支持以编程方式添加 LAMBDA 函数。 它有助于将流程抽象为函数并创建自定义、可重用的函数，并使用熟悉的名称调用它们。 语法很简单。 只需将函数添加到 Workbook 的 Names 集合中即可。

=LAMBDA([参数 1, 参数 2, …,] 计算)

上面的语法添加了一个 LAMBDA 函数，其中包含要传递给该函数的参数，例如单元格引用、字符串或数字。 您最多可以输入 253 个参数。 此参数是可选的。 另一个参数是作为函数结果执行和返回的公式。

下面的代码在 workbook.Names 集合中将 LAMBDA 函数命名为“CountWords”。 LAMBDA 函数执行长时间计算以计算文本中的单词数。 该函数被赋予了一个简单的名称，‘CountWords’，它可以在工作表中多次重复使用，而不是重复冗长的计算函数。

    
workbook.Names.Add("CountWords", "=LAMBDA(text,IF(LEN(TRIM(text))=0,0,LEN(TRIM(text))-LEN(SUBSTITUTE(TRIM(text),\" \",\"\"))+1))");
    

GcExcel 中的 LAMBDA 函数支持包括对七个新的 Helper 函数的支持，这些函数有助于 LAMBDA 函数处理数组：

• BYROW
• BYCOL
• SCAN
• REDUCE
• MAP
• MAKEARRAY
• ISOMITTED

8、新的文本和数组操作 Excel 函数

GcExcel 现在支持以下函数集：

文本操作函数

以前，为了提取文本的一部分，您必须使用多个函数。 例如，要从文本中提取名字，比如单元格中的“Mark Taylor”，您必须使用 FIND 或 SEARCH 函数来查找列表中第一个空格的位置，然后使用 LEFT、MID 或 RIGHT 结合 LEN 来提取数据。 但是，新的文本操作函数有助于提取或组合各种文本片段，并使用单个函数将结果溢出到其他单元格。 支持以下新的文本操作功能。

• TEXTSPLIT
• TEXTBEFORE
• TEXTAFTER

以下代码使用 TEXTBEFORE 函数查找句子中单词之前的文本：

    
sheetOfTEXTBEFORE.Range["A3"].Value = "Little red Riding Hood's red hood";
sheetOfTEXTBEFORE.Range["A4"].Value = "Formulas";
sheetOfTEXTBEFORE.Range["A4"].Font.Bold = true;
sheetOfTEXTBEFORE.Range["B4"].Value = "Results";
sheetOfTEXTBEFORE.Range["B4"].Font.Bold = true;
sheetOfTEXTBEFORE.Range["B5"].Formula2 = "=TEXTBEFORE(A2,\"Red\")";
sheetOfTEXTBEFORE.Range["A5"].Formula = "=FORMULATEXT(B5)";
sheetOfTEXTBEFORE.Range["B6"].Formula2 = "=TEXTBEFORE(A3,\"red\",2)";
sheetOfTEXTBEFORE.Range["A6"].Formula = "=FORMULATEXT(B6)";
sheetOfTEXTBEFORE.Range["B7"].Formula2 = "=TEXTBEFORE(A3,\"red\",-2)";
sheetOfTEXTBEFORE.Range["A7"].Formula = "=FORMULATEXT(B7)";
sheetOfTEXTBEFORE.Range["B8"].Formula2 = "=TEXTBEFORE(A3,\"Red\")";
sheetOfTEXTBEFORE.Range["A8"].Formula = "=FORMULATEXT(B8)";
sheetOfTEXTBEFORE.Range["B9"].Formula2 = "=TEXTBEFORE(A3,\"Red\",,1)";
sheetOfTEXTBEFORE.Range["A9"].Formula = "=FORMULATEXT(B9)";
sheetOfTEXTBEFORE.Range["B10"].Formula2 = "=TEXTBEFORE(A3,\"Riding\")";
sheetOfTEXTBEFORE.Range["A10"].Formula = "=FORMULATEXT(B10)";
    

数组操作函数

数组操作函数将有助于合并和调整范围并溢出公式的范围。如果您的工作表有动态数组公式，这些新函数将使您的电子表格更具吸引力，并支持动态数组的高级和优化操作。添加了以下新功能：

HSTACK、VSTACK、TOROW、TOCOL、WRAPROWS、WRAPCOLS、TAKE、DROP、CHOOSEROWS、CHOOSECOLS 和 EXPAND

以下代码将数组的数据转换为一行：

    
sheetOfTOROW.Range["A7"].Value = "Result";
sheetOfTOROW.Range["A7"].Font.Bold = true;
sheetOfTOROW.Range["A8"].Formula2 = "=TOROW(A2:D4)";
    

9、范围交集、并集和偏移

GcExcel 一直支持 API 来查找两个范围的交集/联合/偏移量。在 v6 中，我们通过引入直接方法简化了这个操作：

• IRange.Intersect(IRange range2) 或 IRange.Intersect(params IRange[] ranges) 获取当前范围与一个或多个范围参数的交集
• IRange.Union(IRange range2) 或 IRange.Union(params IRange[] ranges) 获取当前范围和一个或多个范围参数的并集
• IRange.Offset(int rowOffset, int columnOffset) 获取当前范围的偏移量

下面的代码执行两个范围的交集和并集，分别为相交范围和并集范围设置内部颜色：

    
// Set the intersection of two range value and style.
var intersectRange = worksheet.Range["A2:E6"].Intersect(worksheet.Range["C4:G8"]);
intersectRange.Interior.Color = Color.FromArgb(56, 93, 171);

var firstUnionRange = worksheet.Range["A11:D13"];
firstUnionRange.Merge();
firstUnionRange.Interior.Color = Color.FromArgb(56, 93, 171);
firstUnionRange.HorizontalAlignment = HorizontalAlignment.Center;
firstUnionRange.VerticalAlignment = VerticalAlignment.Center;

var secondUnionRange = worksheet.Range["D14:G16"];
secondUnionRange.Merge();
secondUnionRange.Interior.Color = Color.FromArgb(145, 167, 214);
secondUnionRange.HorizontalAlignment = HorizontalAlignment.Center;
secondUnionRange.VerticalAlignment = VerticalAlignment.Center;
// Set the union of two range value and font style.
var unionRange = worksheet.Range["A11:D13"].Union(worksheet.Range["D14:G16"]);
    

10、控制自动调整的选项

GcExcel 已经支持在打开 Excel 文件时自动调整行/列。但是，在 v6 中，API 添加了一个新选项来控制此行为。

GcExcel 现在支持 XlsxOpenOptions.DoNotAutoFitAfterOpened 属性来获取/设置是否在打开文件后自动调整行高。 默认值为false。

11、SpreadJS 功能支持

GcExcel 添加了新的选项来支持额外的 SpreadJS 特性：

• 在 JSON I/O 中支持“RowColumnStates”
• 支持跨工作簿公式 - JSON I/O 中的 'externalReference'
• 支持将浮动物体（floatingObject）和图片形状写成JSON文件中的形状
• 支持 JSON I/O 中的“allSheetsListVisible”字段

服务端 PDF 组件 GrapeCity Documents for PDF 更新说明

1、支持所有注释的外观流（Appearance Streams）

为了在所有查看器中以相同的显示呈现注释，外观流与注释相关联——这些是 PDF 规范的可选设置部分。GcPdf 现在支持它支持的所有注释的外观流，从而在任何查看器中以完全相同的外观呈现注释。 请注意 - 在此版本中，GcPdf 无法为富文本生成正确的外观流。

此外，在 v6 版本中，GcPdf 添加了 GcPdfDocument.BuildRichTextAppearanceStreams 布尔属性，该属性为具有富文本的注释生成内容流。 该属性默认为false，因此不会生成富文本的内容流，支持富文本的查看器可以像以前一样渲染这些注释。 如果设置为 true，GcPdf 将使用纯文本生成内容流，这样富文本将丢失，但注释在所有查看器中看起来都是一样的。 在下面的快照中，此属性设置为 false，因此可以正确显示带有富文本的自由文本注释。 注释的外观与 Acrobat 中呈现的外观相同。

服务端 Word 组件 GrapeCity Documents for Word 更新说明

1、GcWord 报告模板增强功能

有条件地显示/隐藏多个数据块

GcWord 报告模板添加了新的“if/else/endif”语句来定义一次显示/隐藏整个块或多个块的条件。 定义的条件是一组与算术或逻辑运算相结合的模板值操作数。 考虑以下示例，它显示来自具有单个 if/endif 条件的咨询协议文档的保留信息（如果 payRetainer=1 则显示保留信息），而不是之前使用 hbi 语句隐藏特定块。

将计算添加到 Word 模板

您现在可以使用新的“calc”模板功能将计算添加到 GcWord 报告模板，该功能允许您在类似 VBA 的表达式中使用模板数据字段和文字。 Calc 表达式支持算术、逻辑和其他常用运算符、文本和数据聚合函数等。

一些有效的“calc”表达式示例包括：

• {{ Calc 2 2 + 4 }}
• {{ Calc ds.UnitPrice ds.Quantity }}
• {{ Calc Sum(ds.Price)}}
• {{ Calc Max(ds.Price)}}

此外，calc 和新的条件构造可以一起使用，从而在 if 下启用复杂条件，例如：

{{ if useLimit and Sum(ds.score) > limit }} passed {{ else }} failed {{ endif }}

考虑以下示例，其中发票报告使用 calc 表达式添加报告中所有项目的总价。

2、支持形状和字体效果

反射效果

GcWord 添加了一个具有详细属性的 Reflection 类，以在形状或文本上应用反射效果。效果看起来像形状或文本上的水效果。您可以使用 ApplyBuiltInReflection 方法通过 TextEffects、ShapeEffects 或 FormatScheme 类为反射效果设置自定义属性，该方法可以在文本或绘图对象上设置 9 种内置反射效果中的一种。另外，你也可以直接通过Shape.Effects.Reflection属性给形状设置反射效果。

以下代码在标题上添加了“HalfTouching”反射效果：

    
GcWordDocument doc = new GcWordDocument();
var style = doc.Styles.Add("My Style", StyleType.Paragraph);
style.Font.Size = 48;
// apply top half touching reflection effect to the text
style.Font.Effects.ApplyBuiltInReflection(BuiltInReflectionId.HalfTouching);
doc.Body.Paragraphs.Add("Wetlands", style);
doc.Save("font-reflection-sample.docx");
    

发光效果

此效果在形状区域或文本之外添加了模糊的颜色边界。您可以直接使用 shape.Effects.Glow 属性设置发光效果，或使用 TextEffects、ShapeEffects 类的 ApplyBuiltInGlow 方法为文本或绘图对象设置 24 种内置发光效果中的一种。

以下代码直接使用 ApplyBuiltInGlow 方法添加发光效果：

var style = doc.Styles.Add("My Style", StyleType.Paragraph);
style.Font.Size = 48;
style.ParagraphFormat.Alignment = ParagraphAlignment.Center;
// apply 5 point accent 2 glow effect to the text
style.Font.Effects.ApplyBuiltInGlow(BuiltInGlowId.Radius5Accent2);
doc.Body.Paragraphs.Add("Wetlands", style);
doc.Save("Article.docx");
    

模糊效果

为了使 Word 文档内容中使用的某些形状脱颖而出，GcWord 添加了添加模糊效果的功能。 ShapeEffects 类扩展了新的 Blur 类。 您还可以使用 Shape 的 FormatScheme 类设置模糊效果。

以下代码使用 shape.Effects.Blur 类的直接方法对 Shape 设置模糊效果。

Shape shape = run.GetRange().Shapes.Add(100, 100, GeometryType.Star4);
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.RGB = Color.Yellow;
shape.Line.Width = 4;
shape.Line.Fill.SolidFill.RGB = Color.Red;
// apply 7 point blur effect to the shape
shape.Effects.Blur.Radius = 7f;
    

软边效果

GcWord 添加了另一种方法，可以在 Word 文档中以编程方式为形状添加艺术效果。ShapeEffects 类已使用 SoftEdge 类进行了扩展。软边缘效果是形状边缘的微妙模糊。 它可以通过 SoftEdge.Radius 值应用。软边效果可以直接通过 Shape 类或 FormatScheme 类的 Shape.Effects 类应用。

下面的代码通过形状样式属性将软边效果应用于形状。

Shape shape = run.GetRange().Shapes.Add(100, 100, GeometryType.Star7);
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.RGB = Color.Yellow;
shape.Line.Width = 8;
shape.Line.Fill.SolidFill.RGB = Color.Red;
// apply 5 point soft edge effect to the style
var fmtEffect = doc.Theme.FormatScheme.Effects.Add();
shape.Style.Effects.ThemeEffects = fmtEffect;

填充叠加效果

填充叠加层可用于为对象指定额外的填充并将两种填充混合在一起。 GcWord 添加了可以应用于形状的填充叠加效果。ShapeEffects 类已使用 FillOverlay 效果类进行了扩展。此外，还可以通过 FormatScheme 类使用固定、占位符或图案颜色使用来应用效果。

以下代码将一个形状的图案填充叠加层应用到另一个形状上。

GcWordDocument doc = new GcWordDocument();
Paragraph p = doc.Body.Paragraphs.Add();
Run run = p.GetRange().Runs.Add();
Shape shape = run.GetRange().Shapes.Add();
shape.Fill.Type = FillType.Solid;
shape.Fill.SolidFill.ThemeColor = ThemeColorId.Accent1;

// apply pattern fill overlay with another color to mix with the main fill
var fmtEffect = doc.Theme.FormatScheme.Effects.Add();
var overlay = fmtEffect.FillOverlay;
overlay.BlendMode = BlendMode.Multiply;

var foFill = overlay.Fill;
foFill.Type = FillType.Pattern;
foFill.PatternFill.Type = PatternFillType.DashedHorizontal;
foFill.PatternFill.ForeColor.ThemeColor = ThemeColorId.None;
foFill.PatternFill.BackColor.ThemeColor = ThemeColorId.Accent6;

shape.Style.Effects.PlaceholderColor.ThemeColor = ThemeColorId.Accent3;
shape.Style.Effects.PlaceholderColor.Transparency = 0.6f;

shape.Style.Effects.ThemeEffects = fmtEffect;
doc.Save(@"shape-filloverlay-style-pattern-mixed-sample.docx");