Mail Merge یکی از ویژگی های Microsoft Word برای ایجاد سریع و آسان اسنادی مانند حروف، برچسب ها و پاکت نامه ها است. Aspose.Words Cloud ادغام ایمیل استاندارد را انجام می دهد و آن را چندین گام جلوتر می برد و آن را به یک راه حل گزارش دهی کامل تبدیل می کند که به شما امکان می دهد اسناد پیچیده تری مانند گزارش ها، کاتالوگ ها، موجودی ها و فاکتورها را تولید کنید. مزایای راه حل گزارش ابری Aspose.Words عبارتند از:
- طراحی گزارش در Microsoft Word با استفاده از فیلدهای ادغام ایمیل استاندارد
- مناطقی را در سند تعریف کنید که رشد می کنند، مانند ردیف های جزئیات یک سفارش
- درج تصاویر در حین ادغام ایمیل
- HTML را در حین ادغام ایمیل وارد کنید
مراحل اولیه
مراحل انجام ادغام ایمیل بسیار آسان است. ابتدا از مایکروسافت ورد برای ایجاد و طراحی یک سند Word استفاده می‌کنید که معمولاً به آن قالب می‌گویند. توجه داشته باشید که سند لازم نیست یک الگوی مایکروسافت ورد (.dot) باشد، بلکه می تواند یک سند .doc معمولی باشد. در مکان‌هایی که می‌خواهید داده‌های منبع داده‌تان بعداً درج شود، چند فیلد خاص به نام فیلدهای ادغام را در قالب وارد می‌کنید. سپس با Aspose.Words REST API، یک عملیات ادغام ایمیل را اجرا می کنید. عملیات ادغام نامه، داده ها را از منبع داده شما گرفته و در سند ادغام می کند.
همچنین می توانید مناطق ادغام قابل تکرار را در سند تعیین کنید یا فیلدهای ادغام خاصی را وارد کنید که به شما امکان می دهد محتوای دیگری مانند تصاویر را درج کنید. بسته به نحوه تنظیم فیلدهای ادغام ایمیل و مناطق قابل تکرار در داخل سند، سند رشد خواهد کرد تا چندین رکورد را در منبع داده شما جای دهد. اگر از مناطق ادغام ایمیل استفاده نمی کنید، ادغام نامه مشابه ادغام ایمیل Microsoft Word خواهد بود و کل محتوای سند برای هر رکورد در منبع داده تکرار می شود. با استفاده از مناطق ادغام ایمیل قابل تکرار، می توانید بخش هایی را در داخل یک سند تعیین کنید که برای هر رکورد در منبع داده تکرار می شود. به عنوان مثال، اگر یک ردیف جدول را به عنوان منطقه قابل تکرار علامت گذاری کنید، این ردیف جدول تکرار می شود و باعث می شود که جدول به صورت پویا رشد کند تا همه داده های شما را در خود جای دهد.
یک سند تهیه کنید
قبل از اجرای ادغام نامه، باید الگوی سند را آماده کنید. شما باید فیلدهای ادغام را وارد کنید که با مقادیر منبع داده شما جایگزین شوند.
درج فیلدهای ادغام در یک سند
برای درج فیلدهای ادغام در یک سند:
- سند خود را در Microsoft Word باز کنید.
- در سند، روی جایی که می‌خواهید یک فیلد ادغام قرار دهید، کلیک کنید.
- منوی Insert را باز کرده و Field را انتخاب کنید تا کادر گفتگو باز شود.
- از لیست Field names، MergeField را انتخاب کنید.
- در کادر متنی نام فیلد، یک نام برای فیلد ادغام وارد کنید و OK را فشار دهید.
از آنجایی که یک فیلد ادغام یک فیلد معمولی مایکروسافت ورد است، می توانید با استفاده از میانبر صفحه کلید Alt+F9 بین نمایش کدهای فیلد و نتایج در سند خود در Microsoft Word جابجا شوید. کدهای فیلد بین بریس های فرفری ظاهر می شوند.
ادغام ایمیل ساده
به منظور آماده سازی الگوی خود برای انجام یک ادغام ایمیل ساده (بدون مناطق، مشابه ادغام نامه های کلاسیک موجود در Microsoft Word) فقط باید یک یا چند فیلد ادغام را در مکان هایی که می خواهید با داده های منبع داده پر شود وارد کنید. .
اجازه دهید نگاهی به نسخه نمایشی دعوت شام بیندازیم. یک نامه برای لیستی از مشتریان تعریف شده در منبع داده ایجاد می کند. این الگو شامل تعدادی فیلد ادغام شده است که از دو منبع داده پر شده است. به عبارت دیگر، دو ادغام ایمیل یکی پس از دیگری انجام می شود. ابتدا داده های اولین منبع داده در قالب ادغام می شوند. این منبع داده فقط شامل یک ردیف است زیرا این اطلاعات مربوط به دعوت کننده است، بنابراین کل محتوای سند تکرار نمی شود و فقط فیلدهای مناسب با داده ها پر می شود. سپس دومین عملیات ادغام ایمیل اجرا می شود. منبع داده ای که استفاده می کند حاوی اطلاعاتی در مورد مشتریان است. کل الگو برای هر ردیف داده تکرار می شود و هر کپی تکراری با داده های مشتری مربوطه پر می شود.
در نتیجه، سندی داریم که شامل پنج دعوت نامه پر شده، کامل و شخصی شده است (بخشی از اولین دعوت نامه در زیر نشان داده شده است):
همانطور که می بینید، انجام بیش از یک عملیات ادغام با یک الگو برای افزودن داده ها در مراحل، ممکن است و گاهی مفید است. می توانید فیلدهای NEXT را در سند Word وارد کنید تا موتور ادغام نامه، رکورد بعدی را از منبع داده انتخاب کند و به ادغام ادامه دهد. هنگامی که موتور با یک فیلد NEXT روبرو می شود، فقط رکورد بعدی را در منبع داده انتخاب می کند و بدون کپی کردن محتوا به ادغام ادامه می دهد. این می تواند هنگام ایجاد اسنادی مانند برچسب های پستی استفاده شود.
کد اجرای Simple Mail Merge در زیر آمده است:
// برای نمونه های کامل و فایل های داده، لطفاً به 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 مطابق با نام جدول وجود دارد)
به عنوان مثال، نگاهی به نسخه نمایشی کاتالوگ آیتم بیندازید. در اینجا قطعه ای از یک منطقه آماده شده برای ادغام ایمیل است:
توجه داشته باشید که هر دو فیلد علامت گذاری TableStart:Item و TableEnd:Item در یک ردیف از جدول Word قرار می گیرند. پس از اجرای ادغام نامه، نتیجه اینجاست:
کد انجام Mail Merge with Regions در زیر آمده است:
// برای نمونه های کامل و فایل های داده، لطفاً به 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);
ادغام ایمیل با استفاده از نحو الگوی «سبیل».
این نحو به شما اجازه می دهد تا الگوهایی را برای استفاده با ادغام نامه ایجاد کنید که از نشانگرهای متن ساده به جای فیلدهای ادغام استفاده می کنند. این نشانگرها به این شکل هستند: {{ FieldName }}
نحو شیء
شما به راحتی می توانید ویژگی های فیلدها را با استفاده از نحو زیر ادغام کنید:
{{ 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 یا Formula قرار دهید.
بلوک مشروط
با استفاده از Aspose.Words Cloud می توانید از ادغام نامه با دستور IF استفاده کنید. بلوک IF تنها در صورتی اجرا می شود که عبارت بولی مرتبط با آن درست باشد. نحو IF در زیر نشان داده شده است.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
کد اجرای Mail Merge با استفاده از الگوی ‘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";
// سند اصلی را در Cloud Storage بارگذاری کنید
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” یا "” (مقیاس بندی متناسب) تنظیم کرد. کد درج تصاویر در طول Mail Merge در زیر آمده است:
// برای نمونه های کامل و فایل های داده، لطفاً به 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. بنابراین، می‌توانید به راحتی Mail Merge API را به هر یک از این زبان‌ها فراخوانی کنید.