Слияние писем — это функция Microsoft Word для быстрого и легкого создания документов, таких как письма, этикетки и конверты. Aspose.Words Cloud берет стандартное слияние писем и продвигает его на много шагов вперед, превращая его в полноценное решение для создания отчетов, которое позволяет вам создавать еще более сложные документы, такие как отчеты, каталоги, инвентаризации и счета-фактуры. Преимущества решения для создания отчетов Aspose.Words Cloud:
- Разработка отчетов в Microsoft Word с использованием стандартных полей слияния почты
- Определите области в документе, которые увеличиваются, например, строки с подробностями заказа.
- Вставка изображений во время слияния почты
- Вставьте HTML во время слияния почты
Основные шаги
Шаги по выполнению слияния почты довольно просты. Сначала вы используете Microsoft Word для создания и оформления документа Word, обычно называемого шаблоном. Обратите внимание, что документ не обязательно должен быть шаблоном Microsoft Word (.dot), это может быть обычный документ .doc. Вы вставляете некоторые специальные поля, называемые полями слияния, в шаблон в тех местах, куда вы хотите, чтобы позже были вставлены данные из вашего источника данных. Затем с помощью Aspose.Words REST API вы выполняете операцию слияния почты. Операция слияния почты возьмет данные из вашего источника данных и объединит их в документ.
Вы также можете назначить повторяющиеся области слияния в документе или вставить специальные поля слияния, которые позволяют вставлять другой контент, такой как изображения. В зависимости от того, как вы настроите поля слияния и повторяющиеся области внутри документа, документ будет увеличиваться для размещения нескольких записей в вашем источнике данных. Если вы не используете области слияния, то слияние будет похоже на слияние Microsoft Word, и все содержимое документа будет повторяться для каждой записи в источнике данных. Используя повторяющиеся области слияния, вы можете назначить части внутри документа, которые будут повторяться для каждой записи в источнике данных. Например, если вы отметите строку таблицы как повторяющуюся область, то эта строка таблицы будет повторяться, заставляя таблицу динамически увеличиваться для размещения всех ваших данных.
Подготовить документ
Перед выполнением слияния почты вам необходимо подготовить шаблон документа. Вам следует вставить поля слияния, которые будут заменены значениями из вашего источника данных.
Вставка полей слияния в документ
Чтобы вставить поля слияния в документ:
- Откройте документ в Microsoft Word.
- В документе щелкните место, где вы хотите разместить поле слияния.
- Откройте меню «Вставка» и выберите «Поле», чтобы открыть диалоговое окно «Поле».
- В списке «Имена полей» выберите MergeField.
- В текстовом поле Имя поля введите имя поля слияния и нажмите ОК.
Поскольку поле слияния является обычным полем Microsoft Word, вы можете переключаться между отображением кодов полей и результатов в документе Microsoft Word с помощью сочетания клавиш Alt+F9. Коды полей отображаются между фигурными скобками.
Простое слияние писем
Чтобы подготовить шаблон для выполнения простого слияния почты (без областей, аналогично классическому слиянию почты в Microsoft Word), вам нужно просто вставить одно или несколько полей слияния в те места, которые вы хотите заполнить данными из источника данных.
Давайте рассмотрим демо-приглашение на ужин. Оно создает письмо для списка клиентов, определенных в источнике данных. Шаблон содержит ряд полей слияния, которые заполняются из двух источников данных; другими словами, два слияния почты выполняются одно за другим. Сначала данные из первого источника данных объединяются в шаблон. Этот источник данных содержит только одну строку, поскольку это информация о приглашающем, поэтому все содержимое документа не повторяется, и только соответствующие поля заполняются данными. Затем выполняется вторая операция слияния почты. Источник данных, который он использует, содержит информацию о клиентах. Весь шаблон повторяется для каждой строки данных, и каждая повторная копия заполняется данными соответствующего клиента.
В результате у нас получился документ, состоящий из пяти заполненных, полных и персонализированных пригласительных писем (фрагмент самого первого из них представлен ниже):
Как вы видите, возможно, а иногда и полезно, выполнять более одной операции слияния с одним и тем же шаблоном для поэтапного добавления данных. Вы можете вставить поля NEXT в документ Word, чтобы заставить механизм слияния почты выбрать следующую запись из источника данных и продолжить слияние. Когда механизм встречает поле NEXT, он просто выбирает следующую запись в источнике данных и продолжает слияние, не копируя никакого содержимого. Это можно использовать при создании таких документов, как почтовые этикетки.
Ниже приведен код для выполнения простого слияния писем:
// Полные примеры и файлы данных можно найти по адресу https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "DinnerInvitation.docx";
var destFileName = "InviterAdded.docx";
var data = File.ReadAllText(@"c:\Data\" + "Inviter.xml");
string folder = null; // File exists at the root of the storage
// Загрузить исходный документ в облачное хранилище
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
// Выполнить операцию слияния почты в первый раз
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
// Выполнить операцию слияния почты второй раз
fileName = destFileName;
destFileName = "FinalDinnerInvitation.docx";
data = File.ReadAllText(@"c:\Data\" + "Clients.xml");
executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
Слияние почты с регионами
Если вы хотите динамически увеличивать части внутри документа, используйте слияние с областями. Чтобы указать область слияния в документе, вам нужно вставить два поля слияния, чтобы отметить начало и конец области слияния. Все содержимое документа, включенное в область слияния, будет автоматически повторяться для каждой записи в источнике данных.
Чтобы отметить начало области слияния почты, вставьте MERGEFIELD с именем TableStart:MyTable, где MyTable соответствует тегу или ключу в XML или JSON соответственно. Чтобы отметить конец области слияния почты, вставьте еще один MERGEFIELD с именем TableEnd:MyTable. Между этими полями маркировки разместите поля слияния, которые соответствуют полям вашего источника данных. Эти поля слияния будут заполнены данными из первой строки источника данных, затем вся область будет повторена, а новые поля будут заполнены данными из второй строки и т. д.
При маркировке региона соблюдайте следующие простые правила:
- Поля TableStart и TableEnd должны находиться в одном разделе документа.
- При использовании внутри таблицы TableStart и TableEnd должны находиться в одной строке таблицы.
- Регионы слияния почты могут быть вложены друг в друга.
- Области слияния должны быть правильно сформированы (всегда существует пара совпадающих TableStart и TableEnd с одинаковым именем таблицы)
В качестве примера взгляните на демо-версию Item Catalog. Вот фрагмент региона, подготовленного для слияния:
Обратите внимание, что оба поля маркировки TableStart:Item и TableEnd:Item размещены в одной строке таблицы Word. После выполнения слияния почты, вот результат:
Код для выполнения слияния почты с регионами приведен ниже:
// Полные примеры и файлы данных можно найти по адресу https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "Invoice_Template.doc";
var destFileName = "Invoice_Template_out_.doc";
var data = File.ReadAllText(@"c:\Data\" + "CustomerData.xml");
string folder = null; // File exists at the root of the storage
// Загрузить входной документ в облачное хранилище
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: true);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
Слияние писем с использованием синтаксиса шаблона «Mustache»
Этот синтаксис позволяет создавать шаблоны для использования с почтовым слиянием, которые используют маркеры обычного текста вместо полей слияния. Эти маркеры выглядят так: {{ FieldName }}
Синтаксис Object.Attribute
Вы можете легко объединить атрибуты полей, используя следующий синтаксис:
{{ Address.Street }}
Это позволит объединить данные из XML-данных, которые выглядят следующим образом:
<Order> // <-- Current context is here.
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
<PhoneNumber>543 1234</PhoneNumber>
</Order>
Блоки Foreach
Вы можете объединить данные из нескольких записей с помощью тега foreach. Это похоже на области слияния почты с обычными полями слияния. Вы можете вкладывать такие блоки.
{{ #foreach Order }}
{{ Number }}
{{ Address.Street }}
{{ #foreach Item }}
{{ Description }} {{ Cost}} {{ Total }}
{{/foreach Item }}
{{ /foreach Order }}
Вы также можете смешивать эти поля и помещать их в другие поля Microsoft Word, такие как поля ЕСЛИ или Формулы.
Условный блок
Вы можете использовать слияние почты с оператором IF с помощью Aspose.Words Cloud. Блок IF выполняется только в том случае, если связанное с ним логическое выражение истинно. Синтаксис IF показан ниже.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
Ниже приведен код для выполнения слияния писем с использованием шаблона «Mustache»:
// Полные примеры и файлы данных можно найти по адресу https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "VendorTemplate.doc";
var destFileName = "VendorTemplate_Out.docx";
string folder = null; // File exists at the root of the storage
var data = File.ReadAllText(@"c:\Data\" + "Vendors.xml");
// Загрузить входной документ в облачное хранилище
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
var postExecuteTemplateRequest = new PostExecuteTemplateRequest(fileName, data, folder, destFileName: destFileName);
var actual = wordsApi.PostExecuteTemplate(postExecuteTemplateRequest);
Вставить HTML во время слияния почты
Оба API executeMailMerge и executeTemplate поддерживают вставку HTML в поле слияния. Вам просто нужно убедиться, что вы экранируете символы HTML в строке источника данных и используете атрибут “format”=“html”, как показано ниже:
{
"dataSourceList": {
"contractDS": {
"contractDescription": {
"format":"html",
"htmlText": "<b>Test me 1<br><br><i>Test me 2<br><br><u>Test me 2</u></i></b><br>"
}
}
}
}
Следующий код показывает, как вставить HTML во время слияния почты:
// Полные примеры и файлы данных можно найти по адресу https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
using System;
using System.IO;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;
namespace Aspose.Words.Cloud.Examples.CSharp
{
public class PopulateMailMergeTemplateWithHTMLData
{
public static void Run()
{
WordsApi wordsApi = new WordsApi(Constants.AppKey, Constants.AppSID);
try
{
string fileName = "template.doc";
string destName = "Out_PostDocumentExecuteMailMergeWithHTMLData.docx";
// Загрузить исходный документ в облачное хранилище
wordsApi.UploadFile(new UploadFileRequest(File.Open("..\\..\\..\\Resources\\" + fileName, FileMode.Open), fileName, Constants.MYStorage));
string data = File.ReadAllText("..\\..\\..\\Resources\\TestPostDocumentExecuteMailMerge.txt", System.Text.Encoding.UTF8);
ExecuteMailMergeRequest request = new ExecuteMailMergeRequest(fileName, data, null, Constants.MYStorage, null, null, null, null, null, null, destName);
DocumentResponse result = wordsApi.ExecuteMailMerge(request);
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
}
}
Вставка изображений во время слияния писем
Вы также можете вставлять изображения в поле слияния. Коэффициент масштабирования для изображений можно задать с помощью ‘%’, ‘px’ или ’’ (пропорциональное масштабирование).Код для вставки изображений во время слияния приведен ниже:
// Полные примеры и файлы данных можно найти по адресу https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet
string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);
var fileName = "TestMailMergeWithImages.doc";
var destFileName = "TestMailMergeWithImages_Out.docx";
var data = File.ReadAllText(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + "MailMergeData.txt");
string folder = null; // File exists at the root of the storage
// Загрузить входной документ в облачное хранилище
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + fileName), null, null);
storageApi.PutCreate(request);
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
Облачные SDK
Хотя приведенный выше код находится в .NET, Aspose.Words Cloud SDK доступны на пяти разных языках: .NET, Java, Ruby, Python и Node.js. Поэтому вы можете удобно вызывать API Mail Merge на любом из этих языков.