GrapeCity Documents 服务端文档组件库 - 历史版本

重要信息：GrapeCity Documents 组件包更名为 GcDocs

为了更好的持续改进产品以及服务中国用户，从 V7.0 开始 GrapeCity Documents 正式更名为 GcDocs，这个更名会延伸至 GcDocs 套件下的所有 API 组件。

• GcDocs.Excel Java (GcExcel Java) (之前为 GrapeCity Documents For Excel, Java (GcExcel Java))
• GcDocs.Excel .Net (GcExcel .Net) (之前为 GrapeCity Documents For Excel, .Net (GcExcel .Net))
• GcDocs.PDF (GcPdf) (之前为 GrapeCity Documents For PDF, Java (GcPdf))
• GcDocs.Word (GcWord) (之前为 GrapeCity Documents For Word, .Net (GcWord))

同时，您可以在 Maven 和 Nuget 上找到全新的 GcDocs 组件产品。

GcExcel Java : https://central.sonatype.com/artifact/com.grapecitysoft.documents/gcexcel/overview

GcExcel .Net : https://www.nuget.org/packages/GcDocs.Excel

GcPdf : https://www.nuget.org/packages/GcDocs.Pdf

GcWord : https://www.nuget.org/packages/GcDocs.Word

为了方便，您对已有的工程进行升级，我们也提供了迁移工具。您可以在 GcDocs 各产品试用下载包中看到该工具。

• GcExcel Java 下载地址
• GcExcel .Net 下载地址
• GcPdf 下载地址
• GcWord 下载地址

对于旧的包（Grapecity Dcouments 组件），您仍然可以从下面的 Maven 或者 Nuget 页面访问获取，或者您可以联系我们。

• GrapeCity Documents For Excel, Java (GcExcel Java)
• GrapeCity Documents For Excel, .Net (GcExcel .Net)
• GrapeCity Documents For PDF, Java (GcPdf)
• GrapeCity Documents For Word, .Net (GcWord)

需要强调的是 GcDocs 仅仅是包名字的修改，组件内所有的命名空间，类型名等并未更名，对于您已有的代码，无需做任何修改。

下面让我们开始了解 V7.0 的新功能。

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

增加异步自定义函数

Excel 支持使用异步编程技术的自定义函数进行异步计算。假设您有一个场景，需要从外部源获取数据或执行耗时的计算。传统的同步函数会阻止 Excel 的响应，直到计算完成，导致用户界面的延迟。使用异步计算，您可以通过在耗时的任务进行时允许其他操作继续来提高响应性。

在 GcExcel 中，您可以通过继承 AsyncCustomFunction 类来注册异步自定义函数。此外，CalcError 类型引入了'Busy'枚举，表示单元格当前正在计算异步公式。这个 GcExcel 中的增强功能使用户在自定义函数中利用异步计算，在涉及复杂计算的情况下提供灵活性和效率。

GcExcel 模板增强

保持图片比例

在很多场景中，我们需要保持图片的比例，例如（国旗，照片等）为了防止比例因单元格的大小而改变，使得它们看起来失真。在 v7 版本中，GcExcel 模板中引入了新的属性，即 image.keepaspect 或 image.ka。当设置为 true 时，其可确保图像的比例，从而允许其适合单元格大小，而不管其高度或宽度如何。

示例：以下代码将国旗的比例设置为 True，来让国旗以正常比例显示

    
SQL
{{ds.BikeSeries.CountryImage(image=true,image.keepaspect=true)}}
    

在分页模式下重复形状和图片

GcExcel 模板一直提供对分页模式的支持，可以对报表中的工作表进行分页。这个功能在每个工作表具有一致布局但数据不同的报表中特别有用，比如发票、进展报告和医学检测报告。在这些报表中，通常需要重复使用形状和图像，包括标志或图形，以及数据。在 v7 版本中，GcExcel 模板引入了增强的支持，可以在处理 Excel 模板时重复使用带有数据的形状和图像。这个增强功能确保更动态地处理形状和图像，为报表生成过程增加了灵活性。

形状或图像将根据起始位置的左上单元格的父级进行重复。

例如：在下面的快照中，图像根据 D12 的父级单元格 B12 重复 10 行（CP=10）。

导出 Html 支持 Inline CSS

GcExcel 支持将 Excel 电子表格导出为 HTML，并且提供了包含单独的 CSS 文件作为一个整体的灵活性。但值得注意的是，在将内容导出 HTML 通过电子邮件共享时，或集成到内容管理系统(CMS)中的情况下，CSS 样式需要内嵌至 HTML 标签内。

在最新的更新中，GcExcel 引入了一项新功能，可以在导出 HTML 时，将 CSS 样式存储在标签内（内联样式）。与此功能相配套，GcExcel 引入了 HtmlSaveOptions.CssExportType 枚举，提供三个值来将 Excel 文件以不同的 CSS 选项导出为 HTML：

External：将 CSS 导出到单独的文件中。
Internal：将 CSS 与 style 标签一起导出到 HTML 中。
Inline：将 CSS 与 HTML 元素内的 style 属性一起导出。

示例：以下代码将 Excel 工作簿导出为具有 CssExportType.Inline 选项的 HTML。请注意，样式标签嵌入在 HTML 文件中。

页面设置起始页码支持“自动”

在打印 Excel 表时，用户可以在页面设置对话框中使用'FirstPageNumber'属性来给页面加上页码。如果要使用默认的页码系统，可以将该属性设置为'Auto'。

为了解决编程场景中的需求，GcExcel 引入了 IPageSetup.IsAutoFirstPageNumber 属性，便于在打印时检索和修改第一页的页码是否设置为'Auto'。默认值为 true；但是，如果 IPageSetup.FirstPageNumber 属性已经明确设置，那么 IPageSetup.IsAutoFirstPageNumber 属性将变为 false，并需要重新设置。

示例：以下代码片段演示了如何为已将 FirstPageNumber 设置为 3 的工作表将IPageSetup.IsAutoFirstPageNumber 属性设置为 true。这样在打印时第一页的页码将自动确定，即使之前已经设置为特定值。

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

var fileStream = GetResourceStream("xlsx\\ConfigIsAutoFirstPageNumber.xlsx");
workbook.Open(fileStream);
IWorksheet worksheet = workbook.Worksheets[0];

worksheet.PageSetup.CenterFooter = "&P";

//Set auto page number, original first page number is 3.
worksheet.PageSetup.IsAutoFirstPageNumber = true;
        
// Save to an excel file
workbook.Save("SetIsAutoFirstPageNumber.xlsx");
    

改善选项按钮的分组策略

选项按钮的分组功能现在全面增强，您现在可以通过分组框将选项按钮进行分组，其分组策略与 MS Excel 更加一致。分组框中的选项按钮是独立运行的，这样可以确保不同分组的选项按钮组不会互相影响。您可以通过以下场景了解分组策略：

分组逻辑：
- GcExcel 将根据选项按钮和分组框的范围来判断从属关系。
- 如果选项按钮完全包含在分组框中，则选项按钮的 GroupBox 属性将被设置为第一个匹配的分组框。
- 如果没有匹配的分组框，选项按钮将默认属于工作表组。

分组行为：
- 当两个或多个选项按钮共享同一个分组框时，它们将形成一个单选按钮组。
- 在一组内，只有一个选项按钮可以被选择。

共享 LinkedCell 属性：
- 同一组中的选项按钮现在共享 LinkedCell 属性。
- 因此，为组中的一个选项按钮定义的 LinkedCell 会传播到同一组中的其他选项按钮。

这些增强功能简化了分组框中选项按钮控件的管理和行为，提高了操作的灵活性和一致性。

增强趋势图的格式设置

在图表中绘制数据时，直观地表示潜在趋势通常至关重要。Excel 中的趋势线是分析数据和根据现有趋势预测未来值的宝贵工具。GcExcel 一直支持使用 ITrendline 接口向图表添加趋势线方程，特别是通过 ITrendline.DisplayEquation 和 ITrendline.DisplayRSquared 属性。

在 v7 版本中，GcExcel 向 ITrendline 接口引入了格式化属性，以增强趋势线的视觉效果。ITrendline 接口中添加了一个新属性 DataLabel，允许用户访问与趋势线关联的数据标签。此功能使用户能够利用 IDataLabel 接口中的字体、格式、数字格式、角度、方向和自动图文集等属性来格式化趋势线方程标签。

此外，v7 版本还提供了 ITrendline.Delete 方法，该方法可以删除趋势线方程标签。值得注意的是，趋势线方程现在支持导出为 PDF、HTML 和图像，从而确保各种格式之间的一致性。这些增强功能有助于在 GcExcel 中以更全面、更具视觉吸引力的方式表示趋势线数据。

示例：在下面的快照中，使用 IDataLabel 接口的新属性格式化趋势线方程。

新增单元格默认值功能

用户现在可以选择为单元格建立默认值。如果未指定常规值，则将显示默认值并将其包含在计算中。GcExcel 添加 IRange.DefaultValue 属性来获取或设置单元格的默认值。

示例：以下代码为单元格区域 C4:C8 添加默认值（公式），同时在单元格 C6 和 C8 的添加公式。C9 单元格在计算公式时，基于 C4、C5 和 C7 的默认值进行计算。

PDF 导出支持平滑线图表

为了追求视觉上吸引人的表现和对图表数据的全面理解，GcExcel 现在支持平滑的图表线，同时也支持导出 PDF。

以下图表类型受益于此功能：

• 折线图
• 散点图
• 组合图

支持在 PDF 中生成交互式表单

GcExcel 的最新更新引入了一项强大的功能，允许用户在导出为 PDF 时直接使用 GcExcel API 创建交互式表单。GcExcel 添加了新属性 PdfSaveOptions.FormFields。当设置为 true 时，此属性允许将 Excel 表单控件导出为 PDF 表单控件，同时将 Excel 文件导出为 PDF。某些表单控件的相应属性映射到其各自的 PDF 表单控件属性。

要详细了解映射的属性和限制并进一步探索此功能，请查看下面快照后提供的资源。这一增强功能增强了 GcExcel 的多功能性，为用户提供了更全面的选项来无缝创建和管理交互式表单。

PDF 导出支持漏斗图

GcExcel 现在还将支持漏斗图将 Excel 文件导出为 PDF。因此，您现在可以将漏斗图添加到 Excel 并直接将文件保存为 PDF。

    
C#
// 创建一个漏斗图
IShape shape = worksheet.Shapes.AddChart(ChartType.Funnel, 10, 150, 300, 200);
shape.Chart.SeriesCollection.Add(worksheet.Range["A1:B7"]);

// 设置漏斗图的样式
shape.Chart.ChartTitle.Text = "Funnel Chart";
foreach (var s in shape.Chart.SeriesCollection)
{
    s.DataLabels.Font.Color.RGB = Color.White;
}
        
// 保存为PDF
workbook.Save("FunnelChartPdf.pdf");
    

CSV 导出支持指定列包含“引号”

在某些情况下，导出 CSV 时，需要给特定的列使用“引号”（转义字符）。采取此预防措施是为了防止导出到 CSV 时出现任何潜在的数据误报。GcExcel 添加了新属性 CsvSaveOptions.QuoteColumns 来指定需要转义字符的特定列。可以在属性中指定列的索引。GcExcel 会根据该属性中指定列，使用 CsvSaveOptions.CellSeparator 指定的符号来为这些列添加转义字符。

当 CsvSaveOptions.QuoteColumns 不为 null 时； 只有指定列中的数据才会用转义字符引起来，而其他列中的数据则不加转义字符。请务必注意，如果值包含特殊字符（例如引号或分隔符），则无论如何都会将其括在转义字符中。

示例：在以下示例中，CsvSaveOptions.QuoteColumns 属性定义导出到 CSV 之前需要转义字符的列。

增强 与 SpreadJS 兼容

GcExcel 新增了对 SpreadJS 功能的支持，增强了与客户端 SpreadJS 产品的兼容性。请注意，这些附加功能仅适用于 SpreadJS，并且与 Microsoft Excel 不兼容。

• 对 cell.altText 属性的支持
• 对 IRange.DefaultValue 的支持
• 支持遮罩样式
• 支持受保护工作表中的密码

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

新的插入符注释

在 GcPDF 中引入了插入符注释，这是一种用于审阅 PDF 文档的强大工具。

CaretAnnotation 类使得以编程方式精确指出缺失的内容或必要的更改成为可能。如果你需要以编程方式在文档的多个位置添加插入符注释，那么这将特别有用。

示例：以下代码展示如何查找特定文本，并在该文本之后添加一个插入符注释。

    
C#
using (FileStream fs = new FileStream(@"Wetlands.pdf", FileMode.Open, FileAccess.Read))
{
        GcPdfDocument doc = new GcPdfDocument();
        doc.Load(fs);

        var page = doc.Pages[0];
        var tm = page.GetTextMap();
        // insert the CaretAnnotation after "The Importance" text
        tm.FindText(new FindTextParams("The Importance", false, true), (fp_) =>
        {
                // r - bounds of the found text
                var r = fp_.Bounds[0].ToRect();
                // create the CaretAnnotation and add it to the page
                CaretAnnotation ca = new CaretAnnotation();
                ca.Page = page;
                // in this code annotation size is hardcoded, you can make a code
                // which will adjust size of the annotation depending on height of the found text fragment
                ca.Rect = new System.Drawing.RectangleF(r.Right - 4, r.Bottom - 8, 8, 8);
         });

         doc.Save(@"doc.pdf");
}
    

自定义时间戳

在某些情况下，由于安全原因，服务可能无法连接并从客户端返回所需的时间戳。在这些情况下，可能需要一个定制的时间戳服务向客户端发送一个有效的时间戳令牌。

然后客户端利用时间戳令牌对 PDF 文件进行签名，以确保符合各种 PAdES B-T/B-LT/B-LTA 等级的要求。简而言之，要求是在使用 PDF API 对 PDF 文档进行签名时定制时间戳令牌的生成。现在您可以在 GcPdf v7 中通过使用新的 ITimeStampGenerator 接口实现相同的功能，该接口使用户能够通过将其分配给 SignatureProperties 和 TimeStampProperties 类的 TimeStamp 属性来轻松生成个性化的时间戳令牌。

示例：以下代码将展示生成带有定制时间戳令牌的签名。

      
C#
// generate the signature with time-stamp token
X509Certificate2 crt = new X509Certificate2(@"User.pfx", "**");
using (FileStream fs = new FileStream(@"EmployeeTimeSheet.pdf", FileMode.Open))
{
        GcPdfDocument doc = new GcPdfDocument();
        doc.Load(fs);

        SignatureProperties sp = new SignatureProperties();
        sp.SignatureBuilder = new Pkcs7SignatureBuilder()
        {
                    CertificateChain = new X509Certificate2[] { crt },
        };
        sp.TimeStamp = new TimeStampGenerator()
        {
              ServerUrl = @"http://ts.ssl.com",
        };
        sp.SignatureField = doc.AcroForm.Fields[0];
        doc.Sign(sp, "signed.pdf");
}
    

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

图片效果

在不断发展的文档创建领域中，动态和视觉吸引力的内容需求至关重要。为了满足对多功能和可定制文档元素的需求，GcWord v7 推出了一套强大的功能，允许用户对图片应用各种不同的特效。这一拓展不仅增强了文档的视觉吸引力，还简化了通过代码整合 Microsoft Word 支持的图片特效的过程。使用这些特效，您可以对图片进行以下的编程操作：

• 调整图片的亮度和对比度
• 使用预设色彩重新着色
• 修改图像颜色
• 设置透明色
• 在图片上叠加特定的颜色色调
• 还有更多其他功能...

以下是新引入的 API：

• RecolorType 枚举 - 指定图像颜色变化的类型。
• ImageEffectType 枚举 - 指定图像特效的类型。
• UserColor 类 - 表示扩展颜色。
• WebVideoProperties 类 - 表示向用户显示在线视频的属性。
• ImageEffect 类 - 表示图像特效的基类。
• AlphaBiLevel 类 - 表示Alpha双级效果。
• AlphaCeiling 类 - 表示Alpha天花板效果。
• AlphaFloor 类 - 表示Alpha地板效果。
• AlphaInverse 类 - 表示Alpha反转效果。
• AlphaModulation 类 - 表示Alpha调制固定效果。
• AlphaModulationComplex 类 - 表示Alpha调制复杂效果。
• AlphaReplace 类 - 表示Alpha替换效果。
• BiLevel 类 - 表示双级（黑/白）效果。
• ColorChange 类 - 表示颜色改变效果。
• ColorReplacement 类 - 表示纯色替换效果。
• Duotone 类 - 表示双色调效果。
• Grayscale 类 - 表示灰度效果。
• HslEffect 类 - 表示色相/饱和度/亮度效果。
• Luminance 类 - 表示亮度效果。
• Tint 类 - 表示着色效果。
• ImageEffectList 类 - 表示图像特效列表。
• EmbeddedImageData 类 - 表示嵌入式图像数据。
• PicturePreset 枚举 - 添加图片，略微逆时针旋转的图片，并带有白色边框。
• 对以下 API 进行的新添加和更改：

  - ImageData 类
  - Blur 类
  - FillOverlay 类

在下面的示例中，将一个图像添加到 Word 文档中，并使用 GcWord API 的 Picture.ImageData.RecolorType 枚举将其重新着色为灰度。

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

支持SpreadJS的.sjs文件格式

在 GcExcel 的 V6.0 Update 2 版本中，增加了对 SpreadJS .sjs 文件格式的支持。通过导出为 .sjs 格式，可以实现更短的导出时间和更小的文件尺寸。现在，您可以将 xlsx、xlsm、csv、ssjson 等格式的文件导出为 .sjs 格式，以更高效地处理数据。

增强了Workbook类上的open和save方法，支持.sjs文件，当加载或保存.sjs文件时，可以通过OpenFileFormat和SaveFileFormat，来选择Sjs枚举项。

因为对.sjs文件格式的支持，则可以满足以下功能：

• 快速将Excel文件转换为.sjs格式
• 以更小的占用空间保存文件
• 从.sjs文件中压缩的JSON文件生成单个JSON字符串
• 使各种可用选项自定义SpreadJS.sjs文件的打开和保存

新添加两个类，SjsOpenOptions和SjsSaveOptions。在导入/导出.sjs文件时，可以通过这两个类来定制包含/排除特定的功能。

以下代码加载 SpreadJS 的 .sjs 文件，并通过使用 SjsOpenOptions 排除公式和样式，然后使用 GcExcel 打开并保存该文件。

    
// 创建一个新的工作簿
Workbook workbook = new Workbook();
InputStream stream = this.getResourceStream("sjs\\LoanDetails.sjs");

// .sjs 文件格式的 OpenOptions
SjsOpenOptions openOptions = new SjsOpenOptions();
openOptions.setIncludeFormulas(false);
openOptions.setIncludeStyles(false);

// GcExcel 支持使用 OpenOptions 打开 .sjs 文件格式
workbook.open(stream, openOptions);
    
// 保存为 .sjs 文件
workbook.save("OpenSjsWithOpenOptions.sjs");
    

形状文本的对齐选项

GcExcel在ITextRange接口中添加了新的TextAlignment属性，用于获取或设置形状中文本范围或段落的对齐方式。该属性可以给文本设置对齐方式，如左对齐、右对齐、居中、分散和两端对齐。在需要按照UI设计规则或按照数据格式对齐文本（例如将文本左对齐或将数字右对齐）的场景中非常有帮助。

以下代码将形状中多个段落的对齐方式设置为居中和左对齐：

    
IShape shape = worksheet.Shapes.AddShape(AutoShapeType.RoundedRectangle, (double)10, (double)10, (double)320, (double)150);
shape.TextFrame.TextRange.TextAlignment = TextAlignmentAnchor.Left;
shape.TextFrame.TextRange.Font.Name = "Calibri";
shape.TextFrame.TextRange.Font.Size = 16;
shape.TextFrame.TextRange.Font.Color.RGB = Color.Black;
shape.TextFrame.TextRange.Font.Underline = TextUnderlineType.None;

shape.TextFrame.TextRange.Paragraphs.Add("Quarterly Results");
shape.TextFrame.TextRange.Paragraphs[0].TextAlignment = TextAlignmentAnchor.Center;
shape.TextFrame.TextRange.Paragraphs[0].Font.Size = 28;
shape.TextFrame.TextRange.Paragraphs[0].Font.Underline = TextUnderlineType.Single;
shape.TextFrame.TextRange.Paragraphs.Add("");

shape.TextFrame.TextRange.Paragraphs.Add("Business Domain: E-Commerce");
shape.TextFrame.TextRange.Paragraphs[2].TextAlignment = TextAlignmentAnchor.Left;

shape.TextFrame.TextRange.Paragraphs.Add("Quarter: Q4");
shape.TextFrame.TextRange.Paragraphs[3].TextAlignment = TextAlignmentAnchor.Left;
    

在形状和图表中设置垂直文本方向

在某些文档中，希望将文本方向设置为垂直方向。GcExcel在形状和图表的API中添加了Direction属性：

• IShape.TextFrame.Direction：用于形状的文本方向
• ITickLabels.Direction：用于图表轴上刻度标签的文本方向
• IChartTitle.Direction 或 IChartTitle.TextFrame.Direction：用于图表标题的文本方向
• IAxisTitle.Direction 或 IAxisTitle.TextFrame.Direction：用于坐标轴标题的文本方向
• IDataLabels.Direction：用于指定系列数据标签的文本方向
• IDataLabel.Direction 或 IDataLabel.TextFrame.Direction：用于图表数据点上数据标签的文本方向

Direction属性接受TextDirection枚举选项，可设置文本在以下方向上的方向：

• TextDirection.Horizontal：表示文本水平显示
• TextDirection.Vertical：表示文本垂直显示
• TextDirection.Rotate90：表示文本将旋转90度
• TextDirection.Rotate270：表示文本将旋转270度
• TextDirection.Stacked：表示文本将堆叠显示，读取顺序从左到右
• TextDirection.StackedRtl：表示文本将堆叠显示，读取顺序从右到左

以下代码将文本的TextDirection设置为Stacked方向：

    
var shape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["C2:F12"]);
shape.TextFrame.TextRange.Add("欢迎来到葡萄城");

//将文本方向设置为堆叠，并且文本的阅读顺序从左到右。
shape.TextFrame.Direction = TextDirection.Stacked;
    

支持双面打印 仅适用于.NET版本

有时候我们需要在一页的两面打印一个包含长工作表的工作簿。GcExcel .NET提供了PrintOutOptions类中的Duplex枚举来启用/禁用页面上的双面打印。该枚举有四个选项，用户可以根据需要选择打印工作簿的方式：

• Duplex.Default 表示打印机的默认双面打印设置
• Duplex.Simplex 表示单面打印
• Duplex.Vertical 表示双面垂直打印
• Duplex.Horizontal 表示双面水平打印

以下代码将以双面垂直打印方式打印三份工作簿副本：

// 创建打印选项。
PrintOutOptions options = new PrintOutOptions();
// 设置打印的打印机名称为 "Printer"。
options.ActivePrinter = "Printer";
// 打印3份副本。
options.Copies = 3;
// 设置双面垂直打印。
options.Duplex = System.Drawing.Printing.Duplex.Vertical;
// 使用 "Printer" 打印此工作簿。
workbook.PrintOut(options);

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

对PDF打开和保存时的增强

在新的V6.0 Update 2版本中，GcPdf在处理由其他软件生成的现有PDF文档方面进行了改进，并提供了以下优势：

1、GcPdf现在可以加载和保存可能不严格符合PDF规范的PDF文档

2、GcPdf将保留嵌入在PDF文档中的任何非PDF规范的自定义数据

3、加载PDF文档的平均速度得到了改善

这些改进使得GcPdf能够更好地处理各种PDF文档，即使这些文档不是完全符合PDF规范或包含一些非标准的数据。同时，加载PDF文档的速度也得到了提升。

在不指定密码的情况下处理受密码保护的文件

GcPdf现在允许在不指定密码的情况下处理受密码保护的文件。在加载受密码保护的文件后，您现在可以执行以下操作而无需指定密码：

读取/写入不基于PDF字符串对象的属性，例如：

• 您可以获取/设置CheckBoxField或RadioButtonField的值
• 获取某个文档的特定统计信息，例如获取页面数、注释数等
• 获取或更改文档元数据，因为元数据通常未加密
• 更改某些类型字段的值：CheckBoxField、RadioButtonField；可以更改TextBoxField、CombTextField的值，但有一些限制

如果可以在不使用PDF字符串的情况下定义新对象，您可以添加新对象。例如，您可以向一个页面或所有页面添加一个SquareAnnotation。

新增了DecryptionOptions类来表示解密选项。当加载加密的PDF时，您可以将其作为（可选）参数传递给GcPdfDocument.Load()方法。通过将DecryptionOptions.ThrowExceptionIfInvalidPassword设置为false（默认为true），以允许加载受密码保护的PDF而无需指定其密码。另一个相关的标志是DecryptionOptions.ThrowExceptionIfUnsupportedSecurityOptions，默认情况下也为true。将其设置为false可以允许GcPdf加载具有未知或损坏的安全处理程序的文档。

以下代码示例展示了如何向受密码保护的PDF添加注释，而无需指定密码：

    
using var fs = File.OpenRead("financial-report.pdf");
var doc = new GcPdfDocument();
doc.Load(fs, new DecryptionOptions() { ThrowExceptionIfInvalidPassword = false, ThrowExceptionIfUnsupportedSecurityOptions = false });
// 获取第一页的尺寸：
var page = doc.Pages[0];
var pageSize = page.Size;
// 添加一个方形注释：
SquareAnnotation sa = new SquareAnnotation();
sa.Page = page;
sa.Rect = new RectangleF(10, 10, pageSize.Width 20, pageSize.Height 20);
sa.Color = Color.Red;
doc.Save("AnnotationAdded.pdf");
    

操作底层PDF对象的API（GrapeCity.Documents.Pdf.Spec和GrapeCity.Documents.Pdf.Wrappers命名空间）

在这个版本中，GcPdf介绍了一个新的API，允许熟悉PDF规范的开发人员直接访问PDF底层对象，这些对象是构成PDF文档的基本组成部分。其中包括：

• PDF数组，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfArray、PdfArrayObject、IPdfArray、IPdfArrayExt以及GrapeCity.Documents.Pdf.Wrappers命名空间的PdfArrayWrapper
• PDF布尔值，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfBool、PdfBoolObject、IPdfBool和IPdfBoolExt
• PDF字典，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfDict、PdfDictObject、IPdfDict、IPdfDictExt以及GrapeCity.Documents.Pdf.Wrappers命名空间的PdfDictWrapper
• PDF名称，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfName、PdfNameObject、IPdfName和IPdfNameExt
• PDF空值，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfNull、PdfNullObject、IPdfNull和IPdfNullExt
• PDF数字，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfNumber、PdfNumberObject、IPdfNumber和IPdfNumberExt
• PDF引用，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfRef、PdfRefObject、IPdfRef和IPdfRefExt
• PDF流，参见GrapeCity.Documents.Pdf.Spec命名空间的PdfStreamObjectBase
• PDF字符串，参见GrapeCity.Documents.Pdf.Spec命名空间的类型PdfString、PdfStringObject、IPdfString和IPdfStringExt

这些新的API可以用来访问PDF制作者有时会添加但在PDF规范中没有描述的自定义属性。例如，DocumentInfo对象是一个PDF字典。PDF规范列出了可能存在于该字典中的属性（Creator、Author等），但在许多实际的PDF文件中，DocumentInfo字典包含了PDF规范中不存在的“SourceModified”属性。GrapeCity.Documents.Pdf.Spec命名空间中的类型现在允许开发人员访问/编辑这样的自定义项。

请参阅GcPdf参考文档以获取有关GrapeCity.Documents.Pdf.Spec和GrapeCity.Documents.Pdf.Wrappers命名空间的更多信息。

示例：获取图像属性

使用上述新的API，现在可以使用从流中检索的图像处理由图像扫描仪创建的许多PDF（其中大多数每页只包含一个JPEG或G4 TIFF图像）。 GcPdf包括新的PdfImageInfo类，它是PdfDictWrapper对象的派生类。该类包含许多方法，允许获取底层PDF流对象的属性/数据。此添加将检索流图像并直接解压缩或处理图像。

您可以检索以下图像属性：

• 直接检索每个页面上每个图像的流（使用GetImages()检索）
• 检索上述图像流的压缩格式（Filter）
• 检索上述图像流的黑白信息（Decode或BlackIs1）
• 检索可识别上述图像流颜色的信息（ColorSpace或BitsPerComponent）
• 检索每个掩码的流和每个信息（ImageMask）
• 等等……

以下代码从PDF流中检索图像属性：

    
using (FileStream fs = new FileStream(@"..\..\..\06-1.pdf", FileMode.Open, FileAccess.Read, FileShare.Read))
{
      GcPdfDocument doc = new GcPdfDocument();
      doc.Load(fs);
      var imgs = doc.GetImages();
      // 获取PDF中第一张图像的信息（我们知道有一张图像，因此为简单起见，没有进行索引检查）：
                
      PdfImage pi = (PdfImage) imgs[0].Image; // 注意：这里不需要强制类型转换，PdfImageBase是Image属性的类型。
      Console.WriteLine($"PdfImage object ID: {pi.ObjID}");
      // PdfImage是PdfDictWrapper对象的派生类，它有许多方法可用于获取底层PDF流对象的属性/数据
      using (PdfStreamInfo psi = pi.GetPdfStreamInfo())
      {
            Console.WriteLine($"    Image stream length: {psi.Stream.Length}");
            Console.WriteLine($"        ImageFilterName: {psi.ImageFilterName}");
            Console.WriteLine($"ImageFilterDecodeParams: {psi.ImageFilterDecodeParams}");
            // 打印ImageFilterDecodeParams的内容
            foreach (var kvp in psi.ImageFilterDecodeParams.Dict)
            {
                 Console.WriteLine($"{kvp.Key}: {kvp.Value}");
            }
            // 示例如何获取BlackIs1的值：
            var blackIs1 = psi.ImageFilterDecodeParams.GetBool(PdfName.Std.BlackIs1, null);
            Console.WriteLine($"BlackIs1: {blackIs1}");
       }
      // 打印PdfImage字典的属性
      Console.WriteLine();
      Console.WriteLine("Properties of PdfImage dictionary:");
      foreach (KeyValuePair kvp in pi.PdfDict.Dict)
      {
            Console.WriteLine($"{kvp.Key}: {kvp.Value}");
      } 
      var cs = pi.Get(PdfName.Std.ColorSpace);
      Console.WriteLine($"ColorSpace: {cs.GetType().Name} {cs}");
      var bpc = pi.Get(PdfName.Std.BitsPerComponent);
      Console.WriteLine($"BitsPerComponent: {bpc?.GetType().Name} {bpc}");
}
    

输出显示了获取的所有图像属性。

在TextField中设置格式

GcPdf现在允许用户使用直接的方法（SetPercentFormat、SetNumberFormat、SetDateFormat、SetTimeFormat、SetSpecialFormat方法）以直观的方式给TextField指定日期、时间、数字格式和特殊格式。这些方法已经添加到TextField、CombTextField和ComboBoxField类中。新的方法支持设置与Acrobat中的TextField属性类似的属性。

新增了枚举SpecialFormat、CurrencySymbolStyle、NumberNegativeStyle和NumberSeparatorStyle。这些枚举用作上述方法的参数。

以下代码使用新的方法和参数在TextField上设置数字值。

    
GcPdfDocument doc = new GcPdfDocument();
var p = doc.NewPage();
var g = p.Graphics;
TextField result = new TextField();
result.Widget.Page = p;
result.Widget.Rect = new System.Drawing.RectangleF(100,100,100,100);
result.Widget.Border.Width = 1;
result.SetNumberFormat(2, Field.NumberSeparatorStyle.Dot, Field.NumberNegativeStyle.ShowParentheses, "\u20ac", Field.CurrencySymbolStyle.BeforeNoSpace);
result.Value = "12345.67f";
result.SetNumberValue(12345.67f, 2, Field.NumberSeparatorStyle.Dot, Field.NumberNegativeStyle.None, "$", Field.CurrencySymbolStyle.BeforeNoSpace);
p.Doc.AcroForm.Fields.Add(result);
doc.Save("NumberTextField.pdf");        
    

为GcGraphics绘制布局的辅助类

在最新版本的GcPdf中，添加了新的布局引擎，引入了GrapeCity.Documents.Layout命名空间中的LayoutRect和其他相关类，以基于约束和扁平元素层次结构的布局模型来实现在PDF页面或图像上绘制多个元素而无需计算每个元素相对于其他元素的位置。新的布局引擎提供了灵活性，可以定位和调整元素的大小，从而实现在PDF和图像上绘制复杂的图形布局。

在V6.0 Update 2版本中，GcPdf还在GrapeCity.Documents.Layout.Composition命名空间中添加了额外的类：Surface、Layer、View、Space和Visual类，它们充当布局引擎与绘图表面之间的媒介，使得绘制更复杂的图形、文本和图像更加容易。下面简要介绍这些类的功能：

• Surface是Composition引擎中的主要类。它包含一个LayoutHost（布局引擎的根对象）和一个或多个视图（层）。层由可绘制元素（visuals）和嵌套层组成。Surface类的Render方法调用LayoutHost类的PerformLayout方法来计算表面布局，然后它会在指定的GcGraphics对象上从底部到顶部绘制所有层，包括嵌套层
• 层分为两种类型：Layer类对象和View类对象（派生自Layer对象）。View对象封装了LayoutView对象，它代表具有自己的转换矩阵的单独坐标系统。Layer对象充当轻量级的视图，具有自己的可绘制元素列表、嵌套层和可能的裁剪区域
• 层包含可绘制元素（Visuals）和空间（Spaces）。空间对象表示可能影响其他元素布局但本身不会被绘制的LayoutRect。Visual类继承自Space类。Visual类表示将在目标GcGraphics上绘制的元素

此外，这些类还允许您自定义绘制图形的Z顺序和裁剪。例如，可以从多个可绘制元素组合成一个PDF页面，然后在渲染到文档之前进一步调整这些元素。某些可视元素或层可以隐藏，其他可视元素可以在Z顺序中移动等。

还引入了其他API来实现各种布局。如需了解有关新类和每个类的功能的更多信息，请参阅相关文档。

以下是使用这些API可以实现的一个非常复杂布局的示例：

请查看用于生成此布局的完整源代码的在线演示：Documents for PDF | Text Flow (C#)

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

对于Office Math函数和转换为MathML的支持

GcWord现在支持在Word文档中创建和编辑Office Math内容。GcWord中的OMath支持包括完整的API，用于处理在科学、数学和通用目的的Word文档中广泛使用的数学符号、公式和方程。以下是OMath支持引入的新API的主要亮点：

• 用于表示GcWord中的Office Math内容的两个主要类是OMathParagraph和OMath。OMathParagraph表示带有Office Math内容的段落，而OMath表示内联的Office Math区域，可以包含在OMathParagraph或常规段落中
• 提供了专门的类（如OMathFunction、OMathEquationArray、OMathRadical等），用于表示OMath区域中的各种数学结构。这些类都是从通用的抽象OMathStruct基类派生而来
• 可以通过新的RangeBase属性（OMathParagraphs、OMaths、OMathStructs、OMathElements和OMathMatrixRows）访问Office Math内容
• 为了方便添加MS Word支持的内置方程，RangeBase、OMathParagraph、OMath和OMathElement类上提供了方便的Add/Insert方法，接受一个OMathBuiltInEquation枚举值，用于识别所需的方程
• 包含一个实用的MathMLConverter类，可以方便地在GcWord的OMath内容和MathML之间进行转换

有关GcWord中OMath支持的详细信息，请参阅Office Math文档。

以下代码使用OMath类和其函数将一个方程添加到Word文件中：

    
var sampleDoc = new GcWordDocument();
var om = sampleDoc.Body.AddParagraph().AddOMathParagraph().AddOMath();
om.AddRun("Γ").Font.Italic = false;
om.AddDelimiter(new string[] { "z" });
om.AddRun("=");
var nary = om.AddNary("", "0", "∞", "∫");
nary.Base.AddSuperscript("t", "z-1");
nary.Base.AddSuperscript("e", "-t");
nary.Base.AddRun("dt");
om.AddRun("=");
var frac = om.AddFraction();
var superscript = frac.Numerator.AddSuperscript("e", "-");
superscript.Superscript.AddRun("γ").Font.Bidi = true;
superscript.Superscript.AddRun("z");
frac.Denominator.AddRun("z");
nary = om.AddNary("", "k=1", "∞", "∏");
superscript = nary.Base.AddSuperscript("", "-1");
var delimiter = superscript.Base.AddDelimiter();
var item = delimiter.Items.Add();
item.AddRun("1+");
item.AddFraction("z", "k", null);
superscript = nary.Base.AddSuperscript("e", "z");
superscript.Superscript.AddRun("/").OMathFormat.IsLiteral = true;
superscript.Superscript.AddRun("k");
om.AddRun(",  γ≈0.577216");
sampleDoc.Save("MathEquation.docx");        
    

新增方法用于向 Word 文档添加内容

到目前为止，在Word文档中添加内容对象有一种或多种方式。例如-可以通过段落创建构造函数调用-doc.Body.Paragraphs.Add（“text”）或使用paragraph.GetRange（）。Runs.Add（...）并在此调用之前创建段落来添加段落的“runs”。然而，使用V6.0 Update 2版本，现在可以直接在段落元素上使用新的'AddRun（...）'方法来创建runs。

类似地，GcWord在Word文档中的每种内容对象上添加了"Add<content object>(..)"方法，这样它们就可以直接添加到其父对象中，使代码更简洁高效。现在，可以使用新的辅助方法将这些对象直接添加到Word文档中的不同节或内容对象中：

• 表格（Table）
• 段落（Paragraph）
• 内容控件（ContentControl）
• 简单域（SimpleField）
• 超链接（Hyperlink）
• 双向覆盖（BidirectionalOverride）
• 数学公式段落（OMathParagraph）
• 数学公式（OMath）
• 运行内容（Run）
• 脚注（Footnote）
• 尾注（EndNote）
• 复杂域（ComplexField）
• 组合形状（GroupShape）
• 形状（Shape）
• 图片（Picture）
• 手写形状（InkShape）

请查看以下代码，该代码使用新方法'AddRun(..)'将一个段落运行添加到一个段落中：

GcWordDocument doc = new GcWordDocument();
            
// 添加一个带有默认格式的段落
var p = doc.Body.AddParagraph("text1");
            
// 在该段落中添加另一段使用“Heading1”样式格式化的文本
// 先前的代码应该是：p.GetRange().Runs.Add("text2", doc.Styles[BuiltInStyleId.Heading1]);
// 现在的代码更简洁，更清晰地表明可以将内容添加到对象中
 p.AddRun("text2", doc.Styles[BuiltInStyleId.Heading1]);
    

在GcWord模板中转义模板标签

如果你想要防止特定的数据模板标签被数据模板引擎处理（即在模板扩展后字面上引用它），请在标签的开头双花括号之前插入一个反斜杠。

以下代码片段展示了如何转义原本会打印数据值的标签：

var dsPoint = new string[] { "2.2", "3.3", "4.4" };
var doc = new GcWordDocument();
doc.Body.Paragraphs.Add(@"\{{dsPoint.value}:todouble():format(0.#%)}");
doc.DataTemplate.DataSources.Add("dsPoint", dsPoint);
doc.DataTemplate.Process(CultureInfo.GetCultureInfo("en-US"));
doc.Save("DocumentWithSingleSlash.docx"); 
    

另外，为了在模板标签之前使用反斜杠而不禁用模板处理，GcWord允许您插入两个或更多反斜杠，取决于需要多少个反斜杠。在处理模板标签时，它会从前面的反斜杠中移除一个反斜杠。

下面的代码向模板语法添加了双斜杠。当处理模板语法时，这将在生成的Word文件中添加一个反斜杠。

    
var dsPoint = new string[] { "2.2", "3.3", "4.4" };
var doc = new GcWordDocument();
doc.Body.Paragraphs.Add(@"\\{{dsPoint.value}:todouble():format(0.#%)}");
doc.DataTemplate.DataSources.Add("dsPoint", dsPoint);
doc.DataTemplate.Process(CultureInfo.GetCultureInfo("en-US"));
doc.Save("DocumentWithDoubleSlash.docx");        
    

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

通过 Copy/Move 系列新接口，更方便的复制和移动 Worksheet

在某些场景下，需要复制或移动一个工作簿中某一个或几个表单（Worksheet），GcExcel(Grapecity Documents for Excel)在新版本中通过增加新的接口，支持试用代码的方式复制或者移动表单，具体接口如下：

复制 API 用于将工作表集合复制到其他位置。

• IWorksheets.Copy(IWorkbook targetWorkbook = null) 用于将工作表集合复制到指定工作簿的末尾。 如果目标工作簿为空，工作表集合将被复制到当前工作簿。
• IWorksheets.CopyBefore(IWorksheet targetSheet) 用于将工作表集合复制到指定工作表之前的位置。 目标工作表可以属于任何工作簿。
• IWorksheets.CopyAfter(IWorksheet targetSheet) 用于将工作表集合复制到指定工作表之后的位置。 目标工作表可以属于任何工作簿。 移动 API 用于将工作表集合移动到其他位置。
• IWorksheets.Move(IWorkbook targetWorkbook = null) 用于将工作表集合移动到指定工作簿的末尾。 如果目标工作簿为空，则工作表集合将移动到当前工作簿。
• IWorksheets.MoveBefore(IWorksheet targetSheet) 用于将工作表集合移动到指定工作表之前的位置。 目标工作表可以属于任何工作簿。
• IWorksheets.MoveAfter(IWorksheet targetSheet) 用于将工作表集合移动到指定工作表之后的位置。 目标工作表可以属于任何工作簿。 注意：
• 不能将当前工作簿的所有工作表移动到另一个工作簿会导致异常。 将所有工作表移动到当前工作簿时，什么都不做。
• 当目标工作簿中存在同名时，工作表将通过添加后缀（x）来重命名。 x 代表同名索引。

示例代码：

导出图片时，通过 ImageSaveOptions 调整输出图像

GcExcel 已经提供了一种使用 ToImage 方法将工作表、任何指定范围和各种形状类型转换为图像的方法。

GcExcel 现在还添加了 ImageSaveOptions 类，提供各种属性以在将工作表、范围或形状导出到图像文件时修改和调整图像。

有以下的选项：

• ScaleX and ScaleY
• Resolution
• BackgroundColor
• ShowRowHeadings
• ShowColumnHeadings
• ShowGridlines
• GridlinesColor
• ShowDrawingObjects
• BlackAndWhite

接口

以下设置用于 IWorksheet、IRange 或 IShape ToImage()。

• 使用 ImageSaveOptions.ScaleX 和 ImageSaveOptions.ScaleY 获取或设置比例。
• 使用 ImageSaveOptions.Resolution 获取或设置 jpeg 文件 dpi，其他图像格式将忽略此属性。
• 使用 ImageSaveOptions.BackgroundColor 获取或设置导出图像的背景颜色。
• 使用 ImageSaveOptions.BlackAndWhite 获取或设置是否导出黑白图像。

以下设置仅用于 IWorksheet 或 IRange ToImage()。

• 使用 ImageSaveOptions.ShowRowHeadings 或 ImageSaveOptions.ShowColumnHeadings 获取或设置是否显示行标题或列标题。
• 使用 ImageSaveOptions.ShowGridlines 获取或设置是否显示网格线。
• 使用 ImageSaveOptions.ShowDrawingObjects 获取或设置是否显示绘图对象（图表、形状和图片）。
• 使用 ImageSaveOptions.GridlineColor 获取或设置网格线颜色。

添加一组支持 ImageSaveOptions 参数的新方法。

• 使用 IWorksheet.ToImage(string imageFile, ImageSaveOptions options) 或 IWorksheet.ToImage(Stream stream, ImageType imageType, ImageSaveOptions options) 使用选项将工作表导出到图像文件。
• 使用 IRange.ToImage(string imageFile, ImageSaveOptions options) 或 IRange.ToImage(Stream stream, ImageType imageType, ImageSaveOptions options) 使用选项将范围导出到图像文件。
• 使用 IShape.ToImage(string fileName, ImageSaveOptions options) 或 IShape.ToImage(Stream stream, ImageType imageType, ImageSaveOptions options) 使用选项将形状导出到图像文件。

代码示例

以下代码设置导出工作表图像的背景颜色并设置网格线颜色

支持直接加载和保存 Xltx 文件

xltx格式文件是Excel提供的模板文件，xltx文件可以用来预设一些样式和数据，我们可以使用模板文件创建具有相同样式和数据的 xlsx 文件。

您现在可以直接在 GcExcel 中加载 Xltx 文件，修改并保存回来。 GcExcel 在 I/O 上支持新的 Xltx 文件格式。

Workbook.open 和 Workbook.save 方法现在接受新的 XltxOpenOptions 和 XltxSaveOptions 类来加载 XLTX 工作簿或将其保存回工作簿。 您可以从文件或文件流加载或保存 Xltx。

以下代码使用 GcExcel 打开和保存 .xltx 文件。

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

新的 ClonePage 方法

在使用 GcPdf API - GcPdfDocument.MergeWithDocument 方法之前可以合并 PDF 文档。 随着 v6.1 版本的发布，还可以在 PDF 文档中克隆页面。 使用新的 PageCollection.ClonePage(..) 方法在特定索引处复制 PDF 的页面，并将其放置在同一 PDF 中的另一个索引处。 您还可以控制是否在克隆页面中包含注释或表单字段。

以下代码可用于克隆页面。 第一个参数指定需要克隆的页面的索引，而下一个参数是克隆页面将插入的目标索引。 这里省略了可选参数cloneAnnotations和cloneFields。 它们默认为 true，因此任何注释和字段也将被克隆。

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

增强了对在聚合函数中使用多个表达式的支持

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

现在可以将表达式用作聚合函数的参数。表达式可以在函数中使用常量、聚合或两个集合。

现在可以进行以下计算 -

• 使用常量 - {{ calc Sum（2 + ds.value）}}
• 在聚合函数中使用聚合 - {{ calc Average（ds.value+Sum（ds.value）/2）}}
• 在函数中使用两个集合 - {{ calc Average（ds.value+ds2.value）}}

请查看以下发票报表，其中发票总和是通过在聚合“总和”函数中使用多个表达式计算的。

添加基于集合的状态函数

GcWord 模板现在支持以下集合状态函数：IsFirst、IsLast、可应用于迭代范围的索引。这些函数返回集合上当前迭代的状态。在 Word 报表中，可以实现如下方案 -

• 仅显示集合的偶数元素。
• 显示元素数和当前元素数。
• 检查单词是集合中的第一个元素还是最后一个元素。
• 在某个位置插入一个单词。 下面的代码在集合的末尾插入一个单词。

var p = doc.Body.Paragraphs.Add("{{if IsLast(ds)}} Employee List {{endif}} {{ds.value}}", doc.Styles[BuiltInStyleId.ListParagraph]);
                        

支持 Word （.docx） 文件中的链接样式

此功能将允许开发人员使用新的 GcWordDocument.Styles.AddLinkedStyle 方法将链接样式应用于 Word 文档中的两个段落或运行。还添加了一个布尔属性 HideLinkedCharacterStyles，可用于隐藏链接的字符样式。

您可以将链接样式应用于以下 API -

• Run.Style - 添加一个运行并为其设置链接样式
• ContentControl.Style - 将链接样式设置为内容控件
• FormattedMark.Style - 将链接样式设置为段落的标记（用于表示段落段落标记的物理位置的字形）
• FindFormatting.Style - 创建查找选项并为其设置链接样式

“以下”将通用链接样式应用于段落和段落的一部分，即运行。请注意，链接的样式反映在 MS Word 的样式列表中。

支持形状和字体中的三维效果

GcWord 现在支持 API 中形状和字体的 3D 效果。

GcWord 的 TextFrameFormat 和 Effects 类已扩展为 ThreeDFormat 和 ThreeDScene 效果。

类在字体或形状上设置三维格式属性。

ThreeDScene 类将 3D 场景效果应用于对象，如照明、摄像机、背景等。

字体、形状、组合形状和图片类具有新的 ApplyEffects Preset 方法，用于设置文本和形状的内置效果。

以下快照显示了文本上的三维格式设置，这些设置反映在生成的 Word 文档中。

以下快照显示了应用于形状的三维格式以及三维旋转设置，这些设置反映在生成的Word文档中。

服务端表格组件 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");

历史版本

查看更多关于 GrapeCity Documents 服务端文档组件库的历史版本。

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

1、添加 Excel 表单控件的新 API

在电子表格中收集和呈现数据的一种方法是通过添加到工作表的表单控件。列表框、复选框和按钮等控件有助于构建工作表并管理其数据。

GcExcel 现在支持 API 以编程方式添加 Excel 表单控件。您可以使用标准表单控件创建 Excel 表单、对其进行自定义、从用户那里收集数据或以编程方式检索表单控件值。此外，如果您的多个 Excel 电子表格包含表单控件，则电子表格可以加载到 GcExcel 对象模型中，并且可以修改表单控件。

GcExcel 引入了 IControlCollection， 它添加了IControl类型的表单控件的所有通用成员 。您可以使用 Worksheet.Controls 添加或访问控件。支持以下控件：

• Button
• DropDown
• CheckBox
• Spinner
• ListBox
• OptionButton
• GroupBox
• Label
• ScrollBar

有了这种支持，您还可以使用以下功能。

每个控件都有自己的一组属性。您可以使用每个控件的特定 API 进行设置。例如，以下代码显示了如何设置特定于按钮控件的属性：

                                    
[code]
var workbook = new GrapeCity.Documents.Excel.Workbook();       
IWorksheet ws = workbook.Worksheets["Sheet1"];
         
var button = ws.Controls.AddButton(50, 30, 120, 40);
button.Text = "Submit";
button.PrintObject = true;
button.HorizontalTextAlignment = HorizontalAlignment.Center;
button.VerticalTextAlignment = VerticalAlignment.Center;
                 
// Save to an excel file
workbook.Save("ButtonsBasicUsage.xlsx");
[/code]
                                    
                                

• 修改表单控件和表单控件值 - 使用 Worksheet.Controls 集合访问控件。 CheckBox、OptionButton、ListBox、DropDown 和 Scrollbar 表单控件的LinkedCell 属性有助于将控件的值绑定到链接单元格，反之亦然。您可以使用 LinkedCell 属性获取控件的值
• 将表单控件用作 Shapes - 一个新选项， FormControl 已添加到 ShapeType 枚举，它可以检查表单控件是否为 Shape 类型。此外，使用<IControl>.ShapeRange 来使用表单控件上的某些形状功能，例如复制控件形状或复制单元格上的形状
• 通过 Excel I/O 和 JSON I/O 使用表单控件
• 导出为 PDF、HTML 和图像（导出为图像）

2、GcExcel 模板增强

分页模板

如果您有一个特定的模板，您希望页面上的行数固定，并且需要在以下工作表上重复相同的布局，您可以选择将工作簿分页到单独的工作表中。GcExcel 模板引入了“ TemplateOptions.PaginationMode”， 这是一个全局布尔属性，当它为真时，可以将工作簿分页到单独的工作表中。同时，如果 false 将遵循模板布局和分页的传统规则。如果为 true，您可以定义新的 CountPerPage 属性 (CP) 用于需要重复数据的单元格。该属性将限制页面上生成的模板单元格的实例（记录）数量。当记录数超过 CP 的值时，会自动创建（或分页）一个新的工作表，其布局与模板相同。“CountPerPage”属性是指工作表上分组记录的计数。

以下快照显示 CP 值为 10，为模板单元设置。FM=O 表示当模板单元展开时，新实例将覆盖下面的单元。

在某些条件下 CountPerPage (CP) 属性将起作用。例如，当 Group (G) 属性设置为 Normal/Merge/Repeat时，记录被分组，count 是指创建的组数。如果 Group (G) 属性设置为 List，则记录不分组，Count 指的是实际记录数。

模板语言的调试模式

现在不再需要打开原始模板文件来检查模板是否正确展开。GcExcel 支持在 TemplateOptions 中定义名称 TemplateOptions.DebugMode 。当 DebugMode 为真时，原始模板工作表将出现在工作表 1 中，紧挨着展开的模板工作表 2。

3、支持图表 - 数据表

图表中的数据表有助于方便地查看/分析数据。在 Excel 中，数据表显示在 Excel 图表下方。这特别有用，因此可以一起分析数据和图表，而不是滚动到工作表或其他工作表中的不同位置以将图表数据与源数据匹配。为了帮助解决这个问题，GcExcel 引入了两个新属性 - IChart.HasDataTable 设置 true 或 false，是否将数据表添加到图表，IChart.DataTable 表示图表的数据表，它可以提供各种选项来设置数据表，如字体、格式、显示图例键等。

代码后快照中的数据表是使用新 API 添加的。数据表的格式可以自定义。看看下面的代码：

                            
[code]
IWorksheet worksheet = workbook.Worksheets[0];
 
// Set data.
worksheet.Range["A1:C3"].Value = new object[,]
{
    {"BUDGET TOTALS", "ESTIMATED", "ACTUAL"},
    {"Income", 63300, 57450},
    {"Expenses", 54500, 49630}
};
 
//Create chart.
GrapeCity.Documents.Excel.Drawing.IShape shape = worksheet.Shapes.AddChart(GrapeCity.Documents.Excel.Drawing.ChartType.ColumnClustered, 250, 0, 350, 250);
shape.Chart.SeriesCollection.Add(worksheet.Range["A1:C3"]);
shape.Chart.ChartTitle.Text = "Estimated vs Actual";
 
//Display the data table.
shape.Chart.HasDataTable = true;
 
//Config the data table.
GrapeCity.Documents.Excel.Drawing.IDataTable datatable = shape.Chart.DataTable;
datatable.Format.Line.Color.ObjectThemeColor = ThemeColor.Accent6;
datatable.Font.Color.ObjectThemeColor = ThemeColor.Accent2;
datatable.Font.Size = 9;
         
// Save to an excel file
workbook.Save("chartdatatable.xlsx");
[/code]
                            
                               

4、在数据透视表中添加计算项

计算项有助于在数据透视表中添加自定义公式，对源数据中不存在的其他项执行自定义计算。GcExcel 引入了以下 API：

• IPivotField.CalculatedItems() 获取CalculatedItems 集合，表示指定数据透视表字段中的所有计算项
• ICalculatedItems.Add(string name, string formula) 创建一个新的计算项
• ICalculatedItems.Remove(string name) 按名称删除计算字段
• IPivotItem.Formula 获取或设置计算项目公式

如果数据透视表单元格中的值受两个或多个计算项的影响，则该值由求解顺序中的最后一个公式确定。使用 GcExcel，您可以使用以下 API 设置求解顺序：

• IPivotFormula 是一个表示内容的对象，并解决了计算项的顺序
• 使用 IPivotTable.IPivotFormulas() 获取 IPivotFormula 集合，该集合表示 指定数据透视表字段中的所有IPivotFormula
• 使用 IPivotFormula.Index{get;set;} 获取或设置当前 PivotFormula的索引

下面的电子表格将国家和产品设置为计算项。'Country' 计算项添加了属于同一大陆的国家/地区的销售额，而 Product Calculated Item 将所有价值为 2500 美元的产品设置为 iPhone13，之后将此类项目的 Visible 设置为 False。

                                    
[code]
ICalculatedItems countryCalcItems = calculatedItemTable.PivotFields["Country"].CalculatedItems();
ICalculatedItems productCalcItems = calculatedItemTable.PivotFields["Product"].CalculatedItems();
 
// add some calculated items
countryCalcItems.Add("Oceania", "=Australia+NewZealand");
countryCalcItems.Add("Europe", "=France+Germany");
countryCalcItems.Add("America", "=Canada");
 
productCalcItems.Add("IPhone 13", "=2500");
 
// hide the duplicate normal item.
IPivotItems countrys = calculatedItemTable.PivotFields["Country"].PivotItems;
countrys["United Kingdom"].Visible = false;
countrys["United States"].Visible = false;
 
IPivotItems products = calculatedItemTable.PivotFields["Product"].PivotItems;
products["IPhone 13"].Visible = false;
calculatedItemSheet.Range["A:I"].AutoFit();
 
calculatedItemSheet.Activate();
         
// Save to an excel file
workbook.Save("Calculateditem.xlsx");
[/code]  
                                    
                                

5、在数据绑定中支持 JSON 作为 DataSource

您现在可以使用 JSON 字符串作为数据源绑定 Excel 电子表格。worksheet.DataSource 现在可以直接绑定到 接受 JSON 字符串作为数据源的JsonDataSource类。以下示例代码从 JSON 文件导入数据并将其绑定到工作表：

                                        
[code]
string jsonStr = "[{\"name\":\"jack\",\"age\":12},{\"name\":\"alice\",\"age\":25}]";
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];
worksheet.DataSource = new JsonDataSource(jsonStr);
worksheet.Range["A1"].BindingPath = "name";
workbook.Save("DataSource.xlsx");
[/code]
                                        
                                

6、自定义函数中的 IsVolatile 属性支持

使用自定义函数时，GcExcel 将具有相同名称和参数的公式缓存存储在同一列中。这使得相同的公式在同一列中只计算一次。 GcExcel 在定义自定义函数时支持 IsVolatile布尔属性。该属性将控制在使用自定义函数时是否使用缓存。

以下示例演示如何创建自定义函数以生成 GUID。要每次生成唯一的 GUID，自定义函数不应使用缓存。因此，示例代码将 IsVolatile 属性设置为 true ，以便在每次调用时生成一个新的 GUID。

                                    
[code]
//create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();
 
GrapeCity.Documents.Excel.Workbook.AddCustomFunction(new GeneralID());
 
IWorksheet worksheet = workbook.Worksheets[0];
worksheet.Range["A1"].Formula = "GeneralID()";
var valueA1Before = worksheet.Range["A1"].Value;
worksheet.Range["A2"].Formula = "GeneralID()";
// A1's value has changed.
var valueA1After = worksheet.Range["A1"].Value;
 
/* Implementation of GeneralID
 
public class GeneralID : CustomFunction
{
    public GeneralID() : base("GeneralID", FunctionValueType.Object)
    {
        this.IsVolatile = true;
    }
 
    public override object Evaluate(object[] arguments, ICalcContext context)
    {
        return Guid.NewGuid().ToString("N");
    }
}
 
*/
[/code]
                                    
                                

7、获得准确的范围边界

GcExcel .NET 添加了新的 CellInfo.GetAccurateRangeBoundary(..) 方法，该方法返回比 RectangleF 更准确的范围边界值。

以下代码获取范围的准确范围边界并在该确切位置添加形状。

                                    
[code]
// Get the absolute location and size of the Range["G1"] in the worksheet.
IRange range = worksheet.Range["F1:G1"];
RectangleF rect = GrapeCity.Documents.Excel.CellInfo.GetAccurateRangeBoundary(range);
// Add the image to the Range["G1"]
System.IO.Stream stream = this.GetResourceStream("logo.png");
worksheet.Shapes.AddPictureInPixel(stream, GrapeCity.Documents.Excel.Drawing.ImageType.PNG, rect.X, rect.Y, rect.Width, rect.Height);
         
// Save to an excel file
workbook.Save("getrangeboundary.xlsx");
[/code]
                                    
                                

8、电子表格中的 SVG 图像支持

GcExcel 添加了 IShapes.AddPicureInPixel(..) 方法以添加 SVG 格式的图像。另外，ToImage(..) 方法支持导出为 SVG 图片的如下：

• 使用 IRange.ToImage(string filename) 方法将范围导出为 SVG 图片
• 使用 ISheet.ToImage(string filename) 方法将工作表导出为 SVG 图片
• 使用 IShape.ToImage(string filename) 方法将形状导出为 SVG 图片

GcExcel 还将在以下情况下支持带有 SVG 图像的电子表格：

• 无损导入导出excel文件
• JSON 输入/输出
• 导出为 PDF/HTML/图像文件

注意：要在 Java 中使用带有 GcExcel API 的 SVG 图像，扩展包 batik (1.14) 和 gcexcel-extension-5.2.0.jar 应该包含在项目中。

9、新的 Excel 函数

LET 函数

在您的电子表格中，您可能使用了多个可能很复杂的公式。LET 函数将用户友好的名称应用于范围/单元格或计算，并有助于提高公式计算性能。重复计算的冗长公式只能计算一次，并且可以用易于理解的名称存储结果。此名称可以在 LET 函数中进一步使用，只计算一次，稍后再使用结果。您不再需要记住引用的底层逻辑。GcExcel 将此 LET 函数添加到其 支持的 Functions列表中。如果多个工作表重复重复计算，您可以更新这些公式以使用 LET 函数。下面给出了对电子表格进行这种改进的一个示例。

在上面的示例中，LET 函数通过使用 LET 函数并将 VLOOKUP 的输出定义为 'name' 和 'points' 变量并在公式中重新使用它们，将 VLOOKUP 的计算次数从 4 次减少到 2 次。

下面的代码展示了如何在代码中设置函数：

                                    
[code]
ws.Range["$F$9"].Formula2 = "=LET(name,VLOOKUP($G$5,$B$5:$D$16,2,0),points,VLOOKUP($G$5,$B$5:$D$16,3,0),"Ho, "&name&", you have "&points&" points. "IF(points>300, "Great job, "&name&"!",""))
[/code]
                                    
                                

10、GetPivotData 公式支持溢出数据

在上一个版本中，GcExcel 引入了 GETPIVOTDATA(...) 函数和新的 IRange.GenerateGetPivotDataFunction(IRange destination = null) 方法来为不同的工作表生成 GETPIVOTDATA 函数。

在 v5.2 中，我们扩展了此函数的功能，以支持类似于动态数组公式的溢出数据。该语法现在支持数组项和引用 - “ =GETPIVOTDATA(data_field, pivot_table, [field1, item1, field2, item2], ...)”。 因此，在下面的示例中，使用 GcExcel 在其中一个单元格中设置的 GETPIVOTDATA 函数将两个城市一起放入数组 {'New York', 'Boston'} 中，以便从数据透视表中一次性查找数据该函数的先前实现。

11、使用 InvalidFormulaException 中的其他详细信息更好地调试

为了向客户提供更多信息以解决电子表格中的错误，GcExcel 在 InvalidFormulaException中添加了更多信息。异常现在将包括单元格的位置和公式文本以跟踪错误。因此，如果您遇到此异常，您将获得更多信息来解决电子表格中的问题。

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

1、GcWord 报告模板增强功能

模板标签的扩展语法检查

GcWord 现在包括模板处理时的模板标签语法检查。将扫描候选模板标签，并检查结构。如果发现任何错误，将引发异常，并提供有关问题的详细信息。

在下面的示例中，解析段落中指定的日期格式。格式中指定的字符被扫描并在异常中报告。

                                    
[code]
var coll = new[] { DateTime.Parse("2022/02/12"), DateTime.Parse("1011/03/04") };
  
var doc = new GcWordDocument();
doc.DataTemplate.DataSources.Add("ds", coll);
doc.Body.Paragraphs.Add(@"{{ds.value}:format(yyyy:MM:dd)}");         
  
doc.DataTemplate.Process();
  
//result
GrapeCity.Documents.Word.InvalidTemplateFormatException:
'Template key {{ds.value}:format(yyyy:MM:dd)} have non-escaped service char in the formatter param at position 23.
Chars '(',')',':','{','}' should be escaped.'
[/code]
                                    
                                

添加特定于数据源的文化

使用 GcWord 模板，您现在可以将特定文化添加到添加到模板中的特定数据源。doc.DataTemplate.DataSources.Add(..) 方法中提供了新的区域性参数 。如果设置了此参数，则所有带有来自数据源的标签的文化特定转换都将使用提供的文化。

以下代码为不同的数据源添加了不同的文化：

支持 Decimal、DateTime 和 DateTimeOffset 作为原始类型

GcWord 模板 在模板中允许原始类型（如整数或浮点数）并使用“值”标签访问它们。也可以通过这种方式使用Decimal、DateTime和 DateTimeOffset类型 。

以下代码演示了对 DateTime 和 DateTimeOffset 类型的支持，同时添加到数据源以及使用 value 标记对其进行访问以设置 Date/DateTime 格式：

                                    
[code]
var doc = new GcWordDocument();
// The data source (Napoleon's first italian company battle dates from Wikipedia):
doc.DataTemplate.DataSources.Add("dsItalianBattles", new DateTime[]
{
     //first stage
     DateTime.Parse("1796/04/12"),
     DateTime.Parse("1796/04/14"),
     DateTime.Parse("1796/04/15"),
     DateTime.Parse("1796/04/19"),
     DateTime.Parse("1796/04/22"),
 
     //second stage
     DateTime.Parse("1796/05/10"),
     DateTime.Parse("1796/09/4"),
     DateTime.Parse("1796/10/15"),
     DateTime.Parse("1796/12/14"),
});
 
// The data source (world wide wars start dates):
doc.DataTemplate.DataSources.Add("dsWW", new DateTimeOffset[]
{               
 
     DateTimeOffset.Parse("28/07/1914"),
     DateTimeOffset.Parse("01/09/1939"),               
 
});
 
// Add a list template so that the data is formatted as a list:
var myListTemplate = doc.ListTemplates.Add(BuiltInListTemplateId.BulletDefault, "myListTemplate");
 
//DateTime list
doc.Body.Paragraphs.Add("Napoleon's first italian company battles dates:", doc.Styles[BuiltInStyleId.Heading1]);
// Add a list of battles dates:
var p = doc.Body.Paragraphs.Add("{{#dsItalianBattles}}{{dsItalianBattles.value}:format(yyyy-MM-dd)}{{/dsItalianBattles}}", doc.Styles[BuiltInStyleId.ListParagraph]);
p.ListFormat.Template = myListTemplate;
 
//DateTimeOffset list
doc.Body.Paragraphs.Add("World wars start dates:", doc.Styles[BuiltInStyleId.Heading1]);
p = doc.Body.Paragraphs.Add("{{#dsWW}}{{dsWW.value}:format(yyyy\\:MM\\:dd)}{{/dsWW}}", doc.Styles[BuiltInStyleId.ListParagraph]);
p.ListFormat.Template = myListTemplate;
[/code]
                                    
                                

对文本和形状应用阴影效果

您现在可以使用新的 API 在 MS Word 中自定义内容的外观，以便在形状和文本 Word .docx 文件中应用阴影效果。新的 Effects 属性被添加到 Font、Shape、Picture、GroupShape、CanvasShape、ShapeStyle 和 FormatSсheme 类中。阴影效果分为四类：

• ShadowBase 是所有影子类的基础抽象类
• ShadowPreset 和 InnerShadow 基于 ShadowBase 类
• OuterShadow 基于 InnerShadow 类
• TextEffects 类用于对 Font 类应用效果，仅包含 OuterShadow 阴影类型，而 ShapeEffects 是基于 TextEffects 类，并具有额外 的InnerShadow 和 ShadowPreset 阴影类型

以下快照显示了 应用于“Treadstone”文本 的外阴影效果和使用 GcWord API 应用于形状的 BuiltInShadowId.ProspectiveLowerLeft 枚举。

您可以将自定义阴影和内置阴影应用于文本和形状。请注意，目前 PDF/图像导出不支持阴影。

2、示例：将 markdown (.md) 文档导入 Word（并转换为 PDF/图像）

现在将您的 Markdown 文档导入 GcWord 并将它们转换为 .docx 文件。 GcWord 示例浏览器 现在实现了一个带有完整源代码的新示例，用于将 Markdown .md 文件转换为 .docx 文件和 PDF。转换由 GcWordWeb.Samples.MarkdownToWordRenderer.WordRenderer 类完成，使用 Markdig 包（BSD 2-Clause license）解析 .md 文件，并使用 GcWord OM 从中创建 MS Word 文档。WordRenderer C# 源代码包含在示例中。MarkdownToWordRenderer 源位于示例 zip 的 Samples/Markdown/Renderer 子目录中。

3、GcWordLayout

PdfOutputSettings 现在包括 PdfOutputSettings.SecurityHandler属性，可在将 Word .docx 文件转换为 PDF 导出时 访问其他与安全相关的功能（例如，密码、限制复制等）。看看下面的演示。

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

1、替换/删除 PDF 文档中的文本

您现在不仅可以使用常见的搜索选项（如整个单词、区分大小写和正则表达式（之前已支持））在 PDF 文档中搜索文本，还可以使用新的 API 替换或删除找到的文本实例 - ITextMap.ReplaceText(... ) 或 ITextMap.DeleteText(...) 方法。这在有多个 PDF 文档需要更新的情况下很有用。它提供了以编程方式更新和替换每个文件中某些信息的能力，从而为用户和程序员节省了时间和精力。

新方法也适用于 RTL 和垂直文本。替换文本时，新文本可以具有相同或不同（指定）的字体/字体大小。

删除文本可以在两个 DeleteTextMode 选项中完成。

标准：在这种模式下，文本在删除后的位置会移动。

PreserveSpace：在该模式下，被删除文本的位置会保留一个空格，之后的文本不会移动。

以下代码使用标准选项在 PDF 文档中查找文本“湿地”并删除文本：

    
[code]
// delete word "wetlands" from the document
using (FileStream fs = new FileStream(@"Wetlands.pdf", FileMode.Open, FileAccess.Read, FileShare.Read))
{
 
    GcPdfDocument doc = new GcPdfDocument();
    doc.Load(fs);
    FindTextParams ftp = new FindTextParams("wetlands", true, false);
    doc.DeleteText(ftp, DeleteTextMode.Standard);
    doc.Save("wetlands_deleted_doc.pdf");
 
}
[/code]