邮件合并

邮件合并

本指南展示了如何在 Aspose.Words FOSS for .NET 中使用邮件合并字段代码和邮件合并配置数据，以及合并执行的边界所在。Aspose.Words FOSS for .NET 能识别并更新 Word 邮件合并字段代码 — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF，并且 SKIPIF — 作为其字段评估引擎的一部分，并且可以读取邮件合并配置数据（MailMergeSettings）持久化在文档内部。运行实际的合并以外部数据源生成填充后的输出文档 — 这 MailMerge.Execute() 工作流源自商业产品 — 是 not 在本版本中实现；没有 MailMerge 在当前的 API 表面不存在执行类。

MERGEFIELD — 读取和修改合并占位符

FieldMergeField 实现了 MERGEFIELD 字段。FieldName 和 FieldNameNoPrefix 返回字段绑定的底层数据源列名，TextBefore/TextAfter 保存环绕合并值的字面文本，IsMapped/IsVerticalFormatting 报告合并字段映射和布局标志。与所有字段类型一样，它支持 GetFieldCode()、Update()、Unlink() 和 Remove()。

ADDRESSBLOCK 和 GREETINGLINE

FieldAddressBlock 实现了 ADDRESSBLOCK 字段，FormatAddressOnCountryOrRegion、IncludeCountryOrRegionName、ExcludedCountryOrRegionName、NameAndAddressFormat 和 LanguageId 控制收件人地址的格式。FieldGreetingLine 实现了 GREETINGLINE，AlternateText、NameFormat 和 LanguageId 控制称呼文本。

DATABASE 字段

FieldDatabase 实现了 DATABASE 字段，公开了保存在该字段中的连接详细信息：Connection、FileName、Query、TableFormat、InsertHeadings、InsertOnceOnMailMerge、FirstRecord 和 LastRecord。要在此字段更新时提供查询结果，请实现 IFieldDatabaseProvider 及其 GetQueryResult(fileName, connection, query, field) 方法，然后在调用 Update() 之前将其分配给 Document.FieldOptions.FieldDatabaseProvider。必须设置 Connection 属性——如果不设置，Update() 将没有数据源可供查询。

条件合并字段 — NEXTIF 和 SKIPIF

FieldNextIf 和 FieldSkipIf 实现了 NEXTIF 和 SKIPIF 字段，每个字段都公开 LeftExpression、ComparisonOperator 和 RightExpression 用于条件测试。Document.FieldOptions.ComparisonExpressionEvaluator（一个 IComparisonExpressionEvaluator）可以覆盖这些条件表达式的求值方式。

图片合并字段尺寸设置

MergeFieldImageDimension 表示通过图片合并字段插入的图像的宽度或高度，构造方式为 new MergeFieldImageDimension(value)（单位为点）或使用显式 MergeFieldImageDimensionUnit（Point 或 Percent）的 new MergeFieldImageDimension(value, unit)。其 Value 和 Unit 属性均可写。

范围内与范围外的内容

Document.MailMergeSettings 返回一个 MailMergeSettings 建模邮件合并配置的对象 OOXML 持久化在文档内部 — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, 并且通过 Office Data Source Object (ODSO) 设置 OdsoFieldMapData/OdsoRecipientData 集合。这是配置 data 文档所携带的，而不是实时连接：读取和写入 MailMergeSettings 并不连接到数据库、电子表格或通讯录，而且此版本没有 MailMerge 执行类来运行合并并生成填充后的输出文档。此版本支持的是上述字段级别的层面：在单个文档中通过字段评估引擎识别、读取、更新和修改合并字段代码本身。

技巧与最佳实践

• 将 MailMergeSettings 视为可读取和往返的文档元数据，而不是用于连接外部数据的 API ——此版本中没有其背后的执行引擎。
• 在对 DATABASE 字段调用 Update() 之前，务必先设置 FieldDatabase.Connection，否则更新将没有可查询的内容。
• 一次实现 IFieldDatabaseProvider，并通过 Document.FieldOptions.FieldDatabaseProvider 进行分配，以统一文档中所有 DATABASE 字段的数据解析方式。
• 在决定如何以编程方式处理之前，使用 FieldMergeField.FieldName 读取 MERGEFIELD 绑定的数据源列。

常见问题

FAQ

在此版本中，我可以对 CSV 或数据库执行邮件合并吗？

不可以。此版本实现了邮件合并字段代码和 MailMergeSettings 配置数据模型，但没有 MailMerge 执行类来连接外部数据源并生成填充后的文档。

那么，我实际上可以用 MERGEFIELD 字段做些什么呢？

您可以直接读取和修改它们——FieldMergeField.FieldName 用于绑定的列名，TextBefore/TextAfter 用于周围的文字文本，Update()/Unlink()/Remove() 像其他字段一样——在当前文档中。

没有执行合并时，MailMergeSettings 是否毫无用处？

不——它仍然对读取或往返传递文档中存储的邮件合并配置很有用，例如 DataSource、Query 或 MainDocumentType，即使此版本不会根据该配置执行合并。

我该如何为 DATABASE 字段提供数据？

在调用 Update() 之前，实现 IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) 并将您的实现分配给 Document.FieldOptions.FieldDatabaseProvider。

我如何控制由图片合并字段插入的图像大小？

使用 MergeFieldImageDimension，它可以由点值或带有显式 MergeFieldImageDimensionUnit（Point 或 Percent）的值构造。

API Reference 摘要

另请参阅

• Aspose.Words for .NET — Enterprise Documentation