Mail Merge là một tính năng của Microsoft Word giúp tạo nhanh chóng và dễ dàng các tài liệu như thư, nhãn và phong bì. Aspose.Words Cloud sử dụng mail merge tiêu chuẩn và cải tiến nhiều bước, biến nó thành một giải pháp báo cáo hoàn chỉnh cho phép bạn tạo các tài liệu phức tạp hơn như báo cáo, danh mục, hàng tồn kho và hóa đơn. Ưu điểm của giải pháp báo cáo Aspose.Words Cloud là:
- Thiết kế báo cáo trong Microsoft Word bằng cách sử dụng các trường trộn thư tiêu chuẩn
- Xác định các vùng trong tài liệu phát triển, chẳng hạn như các hàng chi tiết của một đơn hàng
- Chèn hình ảnh trong khi trộn thư
- Chèn HTML trong khi trộn thư
Các bước cơ bản
Các bước thực hiện trộn thư khá dễ. Đầu tiên, bạn sử dụng Microsoft Word để tạo và thiết kế một tài liệu Word, thường được gọi là mẫu. Lưu ý rằng tài liệu không nhất thiết phải là Mẫu Microsoft Word (.dot), mà có thể là tài liệu .doc thông thường. Bạn chèn một số trường đặc biệt được gọi là trường trộn vào mẫu ở những nơi bạn muốn dữ liệu từ nguồn dữ liệu của mình được chèn sau. Sau đó, với API REST Aspose.Words, bạn thực hiện thao tác trộn thư. Thao tác trộn thư sẽ lấy dữ liệu từ nguồn dữ liệu của bạn và trộn vào tài liệu.
Bạn cũng có thể chỉ định các vùng hợp nhất có thể lặp lại trong tài liệu hoặc chèn các trường hợp nhất đặc biệt cho phép bạn chèn nội dung khác như hình ảnh. Tùy thuộc vào cách bạn thiết lập các trường hợp hợp nhất thư và các vùng có thể lặp lại bên trong tài liệu, tài liệu sẽ mở rộng để chứa nhiều bản ghi trong nguồn dữ liệu của bạn. Nếu bạn không sử dụng các vùng hợp nhất thư, thì hợp nhất thư sẽ tương tự như hợp nhất thư của Microsoft Word và toàn bộ nội dung tài liệu sẽ được lặp lại cho mỗi bản ghi trong nguồn dữ liệu. Sử dụng các vùng hợp nhất thư có thể lặp lại, bạn có thể chỉ định các phần bên trong tài liệu sẽ được lặp lại cho mỗi bản ghi trong nguồn dữ liệu. Ví dụ: nếu bạn đánh dấu một hàng bảng là vùng có thể lặp lại, thì hàng bảng này sẽ được lặp lại, khiến bảng tự động mở rộng để chứa tất cả dữ liệu của bạn.
Chuẩn bị một tài liệu
Trước khi thực hiện trộn thư, bạn cần chuẩn bị mẫu tài liệu. Bạn nên chèn các trường trộn sẽ được thay thế bằng các giá trị từ nguồn dữ liệu của bạn.
Chèn trường hợp nhập vào tài liệu
Để chèn trường hợp nhập vào tài liệu:
- Mở tài liệu của bạn trong Microsoft Word.
- Trong tài liệu, nhấp vào nơi bạn muốn đặt trường hợp nhập.
- Mở menu Chèn và chọn Trường để mở hộp thoại Trường.
- Từ danh sách Tên trường, chọn MergeField.
- Trong hộp văn bản Tên trường, nhập tên cho trường hợp nhập và nhấn OK.
Vì trường hợp nhập là trường Microsoft Word thông thường, bạn có thể chuyển đổi giữa việc hiển thị mã trường và kết quả trong tài liệu của mình trong Microsoft Word bằng phím tắt Alt+F9. Mã trường xuất hiện giữa dấu ngoặc nhọn.
Trộn thư đơn giản
Để chuẩn bị mẫu thực hiện trộn thư đơn giản (không có vùng, tương tự như trộn thư cổ điển có trong Microsoft Word), bạn chỉ cần chèn một hoặc nhiều trường trộn vào những nơi bạn muốn điền dữ liệu từ nguồn dữ liệu.
Chúng ta hãy xem bản demo Dinner Invitation. Nó tạo một lá thư cho danh sách khách hàng được xác định trong nguồn dữ liệu. Mẫu chứa một số trường hợp nhất được điền từ hai nguồn dữ liệu; nói cách khác, hai lần hợp nhất thư được thực hiện lần lượt. Đầu tiên, dữ liệu từ nguồn dữ liệu đầu tiên được hợp nhất vào mẫu. Nguồn dữ liệu này chỉ chứa một hàng vì đây là thông tin về người mời, do đó toàn bộ nội dung tài liệu không được lặp lại và chỉ các trường thích hợp được điền dữ liệu. Sau đó, thao tác hợp nhất thư thứ hai được thực hiện. Nguồn dữ liệu mà nó sử dụng chứa thông tin về khách hàng. Toàn bộ mẫu được lặp lại cho mỗi hàng dữ liệu và mỗi bản sao được lặp lại đều được điền dữ liệu của khách hàng tương ứng.
Kết quả là chúng ta có một tài liệu bao gồm năm lá thư mời đã điền đầy đủ và được cá nhân hóa (một phần của lá thư đầu tiên được hiển thị bên dưới):
Như bạn thấy, có thể thực hiện nhiều hơn một thao tác hợp nhất với cùng một mẫu để thêm dữ liệu theo từng giai đoạn và đôi khi hữu ích. Bạn có thể chèn các trường NEXT vào tài liệu Word để khiến công cụ hợp nhất thư chọn bản ghi tiếp theo từ nguồn dữ liệu và tiếp tục hợp nhất. Khi công cụ gặp trường NEXT, nó chỉ chọn bản ghi tiếp theo trong nguồn dữ liệu và tiếp tục hợp nhất mà không sao chép bất kỳ nội dung nào. Điều này có thể được sử dụng khi tạo tài liệu như nhãn thư.
Mã để thực hiện Trộn thư đơn giản được đưa ra dưới đây:
// Để biết ví dụ đầy đủ và tệp dữ liệu, vui lòng truy cập 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
// Tải tài liệu nguồn lên Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);
// Thực hiện thao tác trộn thư lần đầu tiên
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);
// Thực hiện thao tác Mail Merge lần thứ hai
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);
Trộn thư với các vùng
Nếu bạn muốn tăng động các phần bên trong tài liệu, hãy sử dụng tính năng trộn thư với các vùng. Để chỉ định một vùng trộn thư trong tài liệu, bạn cần chèn hai trường trộn thư để đánh dấu điểm bắt đầu và kết thúc của vùng trộn thư. Tất cả nội dung tài liệu được bao gồm bên trong vùng trộn thư sẽ tự động được lặp lại cho mọi bản ghi trong nguồn dữ liệu.
Để đánh dấu phần bắt đầu của một vùng trộn thư, hãy chèn MERGEFIELD có tên TableStart:MyTable, trong đó MyTable tương ứng với thẻ hoặc khóa trong XML hoặc JSON. Để đánh dấu phần kết thúc của vùng trộn thư, hãy chèn một MERGEFIELD khác có tên TableEnd:MyTable. Giữa các trường đánh dấu này, hãy đặt các trường trộn tương ứng với các trường của nguồn dữ liệu của bạn. Các trường trộn này sẽ được điền dữ liệu từ hàng đầu tiên của nguồn dữ liệu, sau đó toàn bộ vùng sẽ được lặp lại và các trường mới sẽ được điền dữ liệu từ hàng thứ hai, v.v.
Thực hiện theo các quy tắc đơn giản sau khi đánh dấu một vùng:
- Các trường TableStart và TableEnd phải nằm trong cùng một phần trong tài liệu
- Nếu được sử dụng bên trong một bảng, TableStart và TableEnd phải nằm trong cùng một hàng trong bảng
- Các vùng trộn thư có thể được lồng vào nhau
- Các vùng trộn thư phải được định dạng tốt (luôn có một cặp TableStart và TableEnd khớp với cùng tên bảng)
Ví dụ, hãy xem bản demo Item Catalog. Đây là một phần của vùng được chuẩn bị để trộn thư:
Lưu ý rằng cả hai trường đánh dấu TableStart:Item và TableEnd:Item đều được đặt bên trong cùng một hàng của bảng Word. Sau khi thực hiện trộn thư, đây là kết quả:
Mã để thực hiện Trộn thư với Regions được đưa ra dưới đây:
// Để biết ví dụ đầy đủ và tệp dữ liệu, vui lòng truy cập 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
// Tải tài liệu đầu vào lên Cloud 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);
Trộn thư bằng cú pháp mẫu ‘Mustache’
Cú pháp này cho phép bạn tạo các mẫu để sử dụng với tính năng trộn thư sử dụng các dấu hiệu văn bản thuần túy thay vì các trường trộn. Các dấu hiệu này trông như thế này: {{ FieldName }}
Cú pháp Object.Attribute
Bạn có thể dễ dàng hợp nhất các thuộc tính của trường bằng cú pháp sau:
{{ Address.Street }}
Thao tác này sẽ hợp nhất dữ liệu từ dữ liệu XML trông như thế này:
<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>
Mỗi khối
Bạn có thể hợp nhất dữ liệu từ nhiều bản ghi bằng thẻ foreach. Điều này tương tự như vùng hợp nhất thư với các trường hợp nhất thông thường. Bạn có thể lồng các khối như vậy.
{{ #foreach Order }}
{{ Number }}
{{ Address.Street }}
{{ #foreach Item }}
{{ Description }} {{ Cost}} {{ Total }}
{{/foreach Item }}
{{ /foreach Order }}
Bạn cũng có thể trộn các trường này và đặt chúng vào bên trong các trường Microsoft Word khác, chẳng hạn như trường IF hoặc trường Công thức.
Khối có điều kiện
Bạn có thể sử dụng mail merge với câu lệnh IF bằng Aspose.Words Cloud. Khối IF chỉ thực thi nếu biểu thức Boolean liên kết với nó là đúng. Cú pháp của IF được hiển thị bên dưới.
{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }
Mã để thực hiện Trộn thư bằng Mẫu ‘Mustache’ được đưa ra bên dưới:
// Để biết ví dụ đầy đủ và tệp dữ liệu, vui lòng truy cập 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");
// Tải tài liệu đầu vào lên Cloud Storage
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);
Chèn HTML trong khi trộn thư
Cả API executeMailMerge và executeTemplate đều hỗ trợ chèn HTML vào trường hợp hợp nhất. Bạn chỉ cần đảm bảo thoát ký tự HTML trong chuỗi nguồn dữ liệu và sử dụng thuộc tính “format”=“html” như hiển thị bên dưới:
{
"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>"
}
}
}
}
Đoạn mã sau đây cho biết cách chèn HTML trong quá trình trộn thư:
// Để biết ví dụ đầy đủ và tệp dữ liệu, vui lòng truy cập 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";
// Tải tài liệu gốc lên 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());
}
}
}
}
Chèn hình ảnh trong khi trộn thư
Bạn cũng có thể chèn hình ảnh vào trường hợp trộn. Hệ số tỷ lệ cho hình ảnh có thể được thiết lập bằng cách sử dụng ‘%’, ‘px’ hoặc ’’ (tỷ lệ tỷ lệ).Mã để chèn hình ảnh trong khi Trộn thư được đưa ra dưới đây:
// Để biết ví dụ đầy đủ và tệp dữ liệu, vui lòng truy cập 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
// Tải tài liệu đầu vào lên Cloud 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 đám mây
Mặc dù mã trên là .NET, Aspose.Words Cloud SDK có sẵn trong năm ngôn ngữ khác nhau: .NET, Java, Ruby, Python và Node.js. Do đó, bạn có thể dễ dàng gọi Mail Merge API bằng bất kỳ ngôn ngữ nào trong số các ngôn ngữ này.