Слияние почты

Слияние почты

Это руководство показывает, как работать с кодами полей слияния писем и данными конфигурации слияния писем в Aspose.Words FOSS для .NET, а также где проходит граница выполнения слияния. Aspose.Words FOSS для .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), затем назначьте его Document.FieldOptions.FieldDatabaseProvider перед вызовом Update(). Свойство Connection должно быть установлено — без него Update() не имеет источника данных для запроса.

Условные поля слияния — NEXTIF и SKIPIF

FieldNextIf и FieldSkipIf реализуют поля NEXTIF и SKIPIF, каждый из которых предоставляет LeftExpression, ComparisonOperator и RightExpression для условного теста. Document.FieldOptions.ComparisonExpressionEvaluator (это IComparisonExpressionEvaluator) может переопределять способ оценки этих условных выражений.

Размеры поля слияния изображения

MergeFieldImageDimension представляет ширину или высоту изображения, вставляемого через поле слияния изображения, формируемую как new MergeFieldImageDimension(value) (в пунктах) или new MergeFieldImageDimension(value, unit) с явным MergeFieldImageDimensionUnit (Point или Percent). Его свойства Value и Unit оба доступны для записи.

Что входит в область охвата, а что нет

Document.MailMergeSettings возвращает a MailMergeSettings объект, моделирующий конфигурацию слияния писем, OOXML сохраняется внутри документа — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, и настройки Office Data Source Object (ODSO) через OdsoFieldMapData/OdsoRecipientData коллекции. Это конфигурация data которую документ несёт, а не живое соединение: чтение и запись MailMergeSettings не подключается к базе данных, таблице или списку адресов, и у этой версии нет MailMerge класса выполнения для запуска слияния и создания заполненных выходных документов из него. Что эта версия поддерживает, так это слой уровня полей выше: распознавание, чтение, обновление и модификацию самих кодов полей слияния внутри одного документа через движок оценки полей.

Советы и лучшие практики

• Обрабатывайте MailMergeSettings как метаданные документа, которые можно читать и передавать дальше, а не как API для подключения к внешним данным — в этом издании нет движка выполнения.
• Всегда задавайте FieldDatabase.Connection перед вызовом Update() на поле DATABASE, иначе обновление не будет иметь чего запрашивать.
• Реализуйте IFieldDatabaseProvider один раз и назначьте его через Document.FieldOptions.FieldDatabaseProvider, чтобы централизовать способ, которым все поля DATABASE в документе получают свои данные.
• Используйте FieldMergeField.FieldName, чтобы определить, к какому столбцу источника данных привязан MERGEFIELD, прежде чем решать, как обрабатывать его программно.

Распространённые проблемы

FAQ

Могу ли я выполнить mail merge против CSV или базы данных в этом издании?

Нет. Это издание реализует коды полей mail-merge и модель конфигурационных данных MailMergeSettings, но нет класса выполнения MailMerge, который подключался бы к внешнему источнику данных и генерировал заполненные документы.

Что же я могу фактически делать с полями MERGEFIELD?

Вы можете читать и изменять их напрямую — FieldMergeField.FieldName для имени привязанного столбца, TextBefore/TextAfter для окружающего буквального текста и Update()/Unlink()/Remove() как любое другое поле — в текущем документе.

Бесполезен ли MailMergeSettings без выполнения слияния?

Нет — он всё ещё полезен для чтения или обратного прохождения сохранённой конфигурации слияния почты в документе, такой как DataSource, Query или MainDocumentType, даже если эта версия не использует эту конфигурацию для выполнения слияния.

Как предоставить данные для поля DATABASE?

Реализуйте IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) и назначьте вашу реализацию Document.FieldOptions.FieldDatabaseProvider перед вызовом Update().

Как контролировать размер изображения, вставляемого полем picture merge?

Используйте MergeFieldImageDimension, построенный с точечным значением или значением плюс явный MergeFieldImageDimensionUnit (Point или Percent).

API Reference Сводка

См. также:

• Aspose.Words for .NET — Enterprise Documentation