Tipuri de operațiuni Mail Merge
Ideea principală a Mail Merge este să creați automat un document sau mai multe documente pe baza șablonului și a datelor preluate din sursa de date. Aspose.Words vă permite să efectuați două tipuri diferite de operații mail merge: simple Mail Merge și Mail Merge cu regiuni.
Cel mai comun exemplu de utilizare a simplului Mail Merge este atunci când doriți să trimiteți un document pentru diferiți clienți, incluzând numele acestora la începutul documentului. Pentru a face acest lucru, trebuie să creați câmpuri de îmbinare, cum ar fi First Name și Last Name în șablonul dvs., apoi să le completați cu date din sursa de date. În timp ce cel mai comun exemplu de utilizare a Mail Merge cu regiuni este atunci când doriți să trimiteți un document care include comenzi specifice cu lista tuturor articolelor din fiecare comandă. Pentru a face acest lucru, va trebui să creați regiuni de îmbinare în interiorul șablonului dvs. – Regiune proprie pentru fiecare comandă, pentru a o completa cu toate datele necesare pentru articole.
Principala diferență dintre ambele operații de fuziune este că Mail Merge simplu (fără regiuni) repetă întregul document pentru fiecare înregistrare sursă de date, în timp ce Mail Merge cu regiuni repetă doar regiunile desemnate pentru fiecare înregistrare. Vă puteți gândi la o operație simplă Mail Merge ca la un caz particular de îmbinare cu regiuni în care singura regiune este întregul document.
Operație Simplă Mail Merge
Un simplu Mail Merge este folosit pentru a umple câmpurile Mail Merge din șablonul dvs. cu datele necesare din sursa de date (reprezentarea unui singur tabel). Deci este similar cu clasicul Mail Merge din Microsoft Word.
Puteți adăuga unul sau mai multe câmpuri de îmbinare în șablonul dvs. și apoi executați operația simplă mail merge. Este recomandat să îl utilizați dacă șablonul dvs. nu conține regiuni de îmbinare.
Principala limitare a utilizării acestui tip este că întregul conținut al documentului va fi repetat pentru fiecare înregistrare din sursa de date.
Cum se execută o operație simplă Mail Merge
Odată ce șablonul este gata, puteți începe să efectuați operația simplă mail merge. Aspose.Words vă permite să executați o operație simplă Mail Merge folosind diferite Execute methods care acceptă diverse obiecte de date ca sursă de date.
Următorul exemplu de cod arată cum să executați o operație simplă Mail Merge folosind una dintre metodele Execute:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
// Include the code for our template. | |
Document doc = new Document(); | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// Create Merge Fields. | |
builder.insertField(" MERGEFIELD CustomerName "); | |
builder.insertParagraph(); | |
builder.insertField(" MERGEFIELD Item "); | |
builder.insertParagraph(); | |
builder.insertField(" MERGEFIELD Quantity "); | |
builder.getDocument().save(dataDir + "MailMerge.TestTemplate.docx"); | |
// Fill the fields in the document with user data. | |
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" }, | |
new Object[] { "John Doe", "Hawaiian", "2" }); | |
builder.getDocument().save(dataDir + "MailMerge.Simple.docx"); |
Puteți observa diferența dintre document înainte de a executa simplu mail merge:

Și după executarea simplă mail merge:

Cum se creează mai multe documente îmbinate
În Aspose.Words, operația standard Mail Merge umple doar un singur document cu conținut din sursa de date. Deci, va trebui să executați operația Mail Merge de mai multe ori pentru a crea mai multe documente îmbinate ca ieșire.
Următorul exemplu de cod arată cum să generați mai multe documente îmbinate în timpul unei operații mail merge:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
public class ProduceMultipleDocumentsDuringMailMerge { | |
private static final String dataDir = Utils.getSharedDataDir(ProduceMultipleDocumentsDuringMailMerge.class) + "MailMerge/"; | |
public static void main(String[] args) throws Exception { | |
produceMultipleDocuments(dataDir, "TestFile.doc"); | |
} | |
public static void produceMultipleDocuments(String dataDir, String srcDoc) throws Exception { | |
// Open the database connection. | |
ResultSet rs = getData(dataDir, "SELECT * FROM Customers"); | |
// Open the template document. | |
Document doc = new Document(dataDir + srcDoc); | |
// A record of how many documents that have been generated so far. | |
int counter = 1; | |
// Loop though all records in the data source. | |
while (rs.next()) { | |
// Clone the template instead of loading it from disk (for speed). | |
Document dstDoc = (Document) doc.deepClone(true); | |
// Extract the data from the current row of the ResultSet into a Hashtable. | |
Hashtable dataMap = getRowData(rs); | |
// Execute mail merge. | |
dstDoc.getMailMerge().execute(keySetToArray(dataMap), dataMap.values().toArray()); | |
// Save the document. | |
dstDoc.save(MessageFormat.format(dataDir + "TestFile Out {0}.doc", counter++)); | |
System.out.println("Counter : "); | |
} | |
} | |
/** | |
* Creates a Hashtable from the name and value of each column in the current | |
* row of the ResultSet. | |
*/ | |
public static Hashtable getRowData(ResultSet rs) throws Exception { | |
ResultSetMetaData metaData = rs.getMetaData(); | |
Hashtable values = new Hashtable(); | |
for (int i = 1; i <= metaData.getColumnCount(); i++) { | |
values.put(metaData.getColumnName(i), rs.getObject(i)); | |
} | |
return values; | |
} | |
/** | |
* Utility function that returns the keys of a Hashtable as an array of | |
* Strings. | |
*/ | |
public static String[] keySetToArray(Hashtable table) { | |
return (String[]) table.keySet().toArray(new String[table.size()]); | |
} | |
/** | |
* Utility function that creates a connection to the Database. | |
*/ | |
public static ResultSet getData(String dataDir, String query) throws Exception { | |
Class.forName("net.ucanaccess.jdbc.UcanaccessDriver"); | |
String connectionString = "jdbc:ucanaccess://" + dataDir + "Customers.mdb"; | |
// DSN-less DB connection. | |
Connection connection = DriverManager.getConnection(connectionString); | |
Statement statement = connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); | |
return statement.executeQuery(query); | |
} | |
} |
Mail Merge cu regiuni
Puteți crea diferite regiuni în șablonul dvs. pentru a avea zone speciale pe care le puteți completa pur și simplu cu datele dvs. Utilizați Mail Merge cu regiuni dacă doriți să inserați tabele, rânduri cu date repetate pentru ca documentele dvs. să crească dinamic, specificând acele regiuni din șablonul dvs.
Puteți crea regiuni imbricate (copil), precum și regiuni de îmbinare. Principalul avantaj al utilizării acestui tip este creșterea dinamică a părților din interiorul unui document. Vedeți mai multe detalii în articolul următor “imbricat Mail Merge cu regiuni”.
Cum se execută Mail Merge cu regiuni
O regiune Mail Merge este o parte specifică din interiorul unui document care are un punct de început și un punct final. Ambele puncte sunt reprezentate ca Mail Merge câmpuri care au nume specifice “TableStart:XXX” și “TableEnd:XXX”. Tot conținutul care este inclus într-o regiune Mail Merge va fi repetat automat pentru fiecare înregistrare din sursa de date.
Aspose.Words vă permite să executați Mail Merge cu regiuni folosind diferite Execute methods care acceptă diverse obiecte de date ca sursă de date.
Ca prim pas, trebuie să creăm DataSet
pentru a-l transmite mai târziu ca parametru de intrare la metoda ExecuteWithRegions
:
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
private static DataSet CreateDataSet() { | |
// Create the customers table. | |
DataTable tableCustomers = new DataTable("Customers"); | |
tableCustomers.getColumns().add("CustomerID"); | |
tableCustomers.getColumns().add("CustomerName"); | |
tableCustomers.getRows().add(new Object[] { 1, "John Doe" }); | |
tableCustomers.getRows().add(new Object[] { 2, "Jane Doe" }); | |
// Create the orders table. | |
DataTable tableOrders = new DataTable("Orders"); | |
tableOrders.getColumns().add("CustomerID"); | |
tableOrders.getColumns().add("ItemName"); | |
tableOrders.getColumns().add("Quantity"); | |
tableOrders.getRows().add(new Object[] { 1, "Hawaiian", 2 }); | |
tableOrders.getRows().add(new Object[] { 2, "Pepperoni", 1 }); | |
tableOrders.getRows().add(new Object[] { 2, "Chicago", 1 }); | |
// Add both tables to a data set. | |
DataSet dataSet = new DataSet(); | |
dataSet.getTables().add(tableCustomers); | |
dataSet.getTables().add(tableOrders); | |
// The "CustomerID" column, also the primary key of the customers table is the | |
// foreign key for the Orders table. | |
dataSet.getRelations().add(tableCustomers.getColumns().get("CustomerID"), | |
tableOrders.getColumns().get("CustomerID")); | |
return dataSet; | |
} |
Următorul exemplu de cod arată cum se execută Mail Merge cu regiuni folosind metoda ExecuteWithRegions(DataSet):
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java | |
// For complete examples and data files, please go to | |
// https://github.com/aspose-words/Aspose.Words-for-java | |
Document doc = new Document(); | |
DocumentBuilder builder = new DocumentBuilder(doc); | |
// The start point of mail merge with regions the dataset. | |
builder.insertField(" MERGEFIELD TableStart:Customers"); | |
// Data from rows of the "CustomerName" column of the "Customers" table will go | |
// in this MERGEFIELD. | |
builder.write("Orders for "); | |
builder.insertField(" MERGEFIELD CustomerName"); | |
builder.write(":"); | |
// Create column headers | |
builder.startTable(); | |
builder.insertCell(); | |
builder.write("Item"); | |
builder.insertCell(); | |
builder.write("Quantity"); | |
builder.endRow(); | |
// We have a second data table called "Orders", which has a many-to-one | |
// relationship with "Customers" | |
// picking up rows with the same CustomerID value. | |
builder.insertCell(); | |
builder.insertField(" MERGEFIELD TableStart:Orders"); | |
builder.insertField(" MERGEFIELD ItemName"); | |
builder.insertCell(); | |
builder.insertField(" MERGEFIELD Quantity"); | |
builder.insertField(" MERGEFIELD TableEnd:Orders"); | |
builder.endTable(); | |
// The end point of mail merge with regions. | |
builder.insertField(" MERGEFIELD TableEnd:Customers"); | |
// Pass our dataset to perform mail merge with regions. | |
DataSet customersAndOrders = CreateDataSet(); | |
doc.getMailMerge().executeWithRegions(customersAndOrders); | |
// Save the result | |
doc.save(dataDir + "MailMerge.ExecuteWithRegions.docx"); |
Puteți observa diferența dintre document înainte de a executa Mail Merge cu regiuni:

Și după executarea Mail Merge cu regiuni:

Limitări ale Mail Merge cu regiuni
Există câteva puncte importante pe care trebuie să le luați în considerare atunci când efectuați un Mail Merge cu regiuni:
- Punctul de pornire TableStart:Orders și punctul final TableEnd:Orders trebuie să fie ambele în același rând sau celulă. De exemplu, dacă începeți o regiune de îmbinare într-o celulă a unui tabel, trebuie să terminați regiunea de îmbinare în același rând cu prima celulă.
- Numele câmpului de îmbinare trebuie să se potrivească cu numele coloanei din DataTable. Dacă nu ați specificat câmpuri mapate, Mail Merge cu regiuni nu va avea succes pentru niciun câmp de îmbinare care are un nume diferit de numele coloanei.
Dacă una dintre aceste reguli este încălcată, veți obține rezultate neașteptate sau poate fi aruncată o excepție.