MailMerge

MailMerge class

代表邮件合并功能。

要了解更多信息，请访问邮件合并和报告文档文章。

public class MailMerge

特性

姓名描述
CleanupOptions { get; set; }获取或设置一组标志，指定在邮件合并期间应删除哪些项目。
CleanupParagraphsWithPunctuationMarks { get; set; }获取或设置一个值，指示带有标点符号的段落是否被视为空 ，并且如果RemoveEmptyParagraphs指定了选项。
FieldMergingCallback { get; set; }当文档中遇到邮件合并字段时，在邮件合并期间发生。
MailMergeCallback { get; set; }允许在邮件合并期间处理特定事件。
MappedDataFields { get; }返回代表邮件合并操作的映射数据字段的集合。
MergeDuplicateRegions { get; set; }获取或设置一个值，该值指示在执行针对数据源的区域邮件合并时，是否应合并所有具有数据源名称的文档邮件合并区域 ，还是仅合并第一个。
MergeWholeDocument { get; set; }获取或设置一个值，该值指示在执行带有区域的邮件合并时是否更新整个文档中的字段。
PreserveUnusedTags { get; set; }获取或设置一个值，指示是否应保留未使用的“胡子”标签。
RegionEndTag { get; set; }获取或设置邮件合并区域结束标签。
RegionStartTag { get; set; }获取或设置邮件合并区域开始标记。
RestartListsAtEachSection { get; set; }获取或设置一个值，指示执行邮件合并后列表是否在每个部分重新启动。
RetainFirstSectionStart { get; set; }获取或设置一个值，指示SectionStart第一个文档部分及其后续数据源行的副本 在邮件合并期间保留或根据 MS Word 行为进行更新。
TrimWhitespaces { get; set; }获取或设置一个值，指示是否从邮件合并值中删除尾随和前导空格。
UnconditionalMergeFieldsAndRegions { get; set; }获取或设置一个值，该值指示合并字段和合并区域是否合并，而不管父 IF 字段的条件如何。
UseNonMergeFields { get; set; }当真的，指定除了 MERGEFIELD 字段之外，邮件合并还会执行到一些其他类型的字段中，并且还会执行到“{{fieldName}}”标签中。
UseWholeParagraphAsRegion { get; set; }获取或设置一个值，指示整个段落是否表开始或者桌尾field 或之间的特定范围表开始和桌尾字段应包含在邮件合并区域中。

方法

姓名描述
DeleteFields()从文档中删除邮件合并相关字段。
Execute(DataRow)从数据行进入文档。
Execute(DataTable)将 DataTable 中的邮件合并到文档中。
Execute(DataView)从数据视图进入文档。
Execute(IDataReader)执行邮件合并数据读取器进入文档。
Execute(IMailMergeDataSource)从自定义数据源执行邮件合并。
Execute(string[], object[])对单个记录执行邮件合并操作。
ExecuteADO(object)执行从 ADO Recordset 对象到文档的邮件合并。
ExecuteWithRegions(DataSet)从数据集到带有邮件合并区域的文档中。
ExecuteWithRegions(DataTable)从数据表放入带有邮件合并区域的文档中。
ExecuteWithRegions(DataView)从数据视图放入带有邮件合并区域的文档中。
ExecuteWithRegions(IMailMergeDataSource)使用邮件合并区域从自定义数据源执行邮件合并。
ExecuteWithRegions(IMailMergeDataSourceRoot)使用邮件合并区域从自定义数据源执行邮件合并。
ExecuteWithRegions(IDataReader, string)执行邮件合并数据读取器放入带有邮件合并区域的文档中。
ExecuteWithRegionsADO(object, string)使用邮件合并区域执行从 ADO Recordset 对象到文档的邮件合并。
GetFieldNames()返回文档中可用的邮件合并字段名称集合。
GetFieldNamesForRegion(string)返回该区域可用的邮件合并字段名称集合。
GetFieldNamesForRegion(string, int)返回该区域可用的邮件合并字段名称集合。
GetRegionsByName(string)返回具有指定名称的邮件合并区域集合。
GetRegionsHierarchy()返回文档中可用的区域（带有字段）的完整层次结构。

评论

要使邮件合并操作正常运行，文档应包含 Word MERGEFIELD 和 NEXT 字段（可选）。在邮件合并操作期间，文档中的合并字段将被数据源中的值替换。

使用邮件合并有两种不同的方式：使用邮件合并区域和不使用邮件合并区域。

最简单的邮件合并不需要区域，它与 Word 中 mailmerge 的工作方式非常相似。使用执行合并来自 some 数据源的信息的方法，例如数据表，数据集，数据视图，数据读取器 或对象数组到您的文档中。 MailMerge对象处理数据源的所有记录，并为每个记录复制并附加 整个文档的内容。

请注意，当MailMerge对象遇到 NEXT 字段，它将选择数据源中的下一个 record 并继续合并而不复制任何内容。

使用ExecuteWithRegions以及其他重载，用于将信息合并到已定义邮件合并区域的 a 文档中。您可以使用 数据集，数据表，数据视图或者数据读取器 作为此操作的数据源。

如果您想动态扩展 文档中的部分内容，则需要使用邮件合并区域。如果没有邮件合并区域，整个文档将针对 数据源的每条记录重复显示。

例子

展示如何使用 DataTable 中的数据执行邮件合并。

public void ExecuteDataTable()
{
    DataTable table = new DataTable("Test");
    table.Columns.Add("CustomerName");
    table.Columns.Add("Address");
    table.Rows.Add(new object[] { "Thomas Hardy", "120 Hanover Sq., London" });
    table.Rows.Add(new object[] { "Paolo Accorti", "Via Monte Bianco 34, Torino" });

    // 以下是使用 DataTable 作为邮件合并数据源的两种方法。
    // 1 - 使用整个表进行邮件合并，为表中的每一行创建一个输出邮件合并文档：
    Document doc = CreateSourceDocExecuteDataTable();

    doc.MailMerge.Execute(table);

    doc.Save(ArtifactsDir + "MailMerge.ExecuteDataTable.WholeTable.docx");

    // 2 - 使用表的一行创建一个输出邮件合并文档：
    doc = CreateSourceDocExecuteDataTable();

    doc.MailMerge.Execute(table.Rows[1]);

    doc.Save(ArtifactsDir + "MailMerge.ExecuteDataTable.OneRow.docx");
}

/// <summary>
/// 创建邮件合并源文档。
/// </summary>
private static Document CreateSourceDocExecuteDataTable()
{
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    builder.InsertField(" MERGEFIELD CustomerName ");
    builder.InsertParagraph();
    builder.InsertField(" MERGEFIELD Address ");

    return doc;
}

也可以看看

ImageFieldMergingArgs Class MailMergeCleanupOptions Enum