Bu gönderi, Java kullanılarak MS Word belgelerinde Adres Mektup Birleştirme işlemlerinin nasıl gerçekleştirileceğini kapsar. Bu makalenin sonunda, Adres Mektup Birleştirme şablonlarının nasıl oluşturulacağını ve Adres Mektup Birleştirmenin program aracılığıyla nasıl yürütüleceğini öğreneceksiniz.

Adres Mektup Birleştirme Hakkında

Posta Birleştirme, mektupları, zarfları, faturaları, raporları ve diğer belge türlerini dinamik olarak oluşturmanın kullanışlı bir yoludur. Adres Mektup Birleştirme’yi kullanarak, birleştirme alanlarını içeren bir şablon dosyası oluşturursunuz ve ardından bu alanları bir veri kaynağındaki verileri kullanarak doldurursunuz. Diyelim ki 20 farklı kişiye bir mektup göndermeniz gerekiyor ve her kopyada sadece alıcıların isimlerini ve adreslerini değiştirmeniz gerekiyor. Bu durumda, mektup için bir Adres Mektup Birleştirme şablonu oluşturabilir ve ardından ad ve adres alanlarını dinamik olarak doldurarak 20 harf oluşturabilirsiniz.

Java Adres Mektup Birleştirme API’sı - Ücretsiz İndirme

Aspose.Words for Java, çeşitli belge türlerini sıfırdan oluşturmanıza olanak tanıyan, iyi bilinen bir kelime işlemci API’sidir. API, şablonları ve veri kaynaklarını kullanarak belgeleri dinamik olarak oluşturmanıza olanak tanıyan yerleşik Adres Mektup Birleştirme özellikleri sağlar. Aspose.Words for Java, JAR olarak indirilebilir veya Maven tabanlı uygulamalara kurulabilir.

<repository>
    <id>AsposeJavaAPI</id>
    <name>Aspose Java API</name>
    <url>https://repository.aspose.com/repo/</url>
</repository>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-words</artifactId>
    <version>20.11</version>
    <classifier>jdk17</classifier>
</dependency>

Adres Mektup Birleştirme için Veri Kaynakları

Adres Mektup Birleştirmedeki veriler, JSON, XML, elektronik tablo veya bir veritabanı gibi herhangi bir veri kaynağından alınabilir.

MS Word’de Adres Mektup Birleştirme için Şablon Oluşturma

Adres Mektup Birleştirmede kullanılan şablon basit bir Word belgesi olabilir (ör. DOCX) ve şablon biçiminde olması gerekmez. Şablon belgesi, Adres Mektup Birleştirme yürütüldüğünde verilerle doldurulan birleştirme alanlarını içerir. MS Word kullanarak Adres Mektup Birleştirme şablonunun nasıl hazırlanacağına ilişkin adımlar aşağıdadır.

  • MS Word’de yeni bir belge oluşturun.
  • İmleci birleştirme alanı eklemek istediğiniz yere getirin.
  • Ekle menüsünden Alan seçeneğini seçin.
  • Alan adları listesinden MergeField’ı seçin.
  • Alan adı alanına birleştirme alanı için bir ad girin ve Tamam’a basın.
  • Belgeyi DOCX olarak kaydedin.

Aşağıda, örnek şablon belgesinin ekran görüntüsü verilmiştir.

adres mektup birleştirme kelime şablonu

Java kullanarak Adres Mektup Birleştirme Şablonu oluşturun

Adres Mektup Birleştirme şablonunu programlı olarak da oluşturabilirsiniz. Bunun için adımlar aşağıdadır.

Aşağıdaki kod örneği, Java kullanılarak Adres Mektup Birleştirme şablonunun nasıl oluşturulacağını gösterir.

// Belge oluşturucu oluştur
DocumentBuilder builder = new DocumentBuilder();

// Bir metin giriş alanı ekleyin, bu alanın benzersiz adı "Merhaba"dır, diğer parametreler tanımlar
// ne tür FormField olduğu, metnin formatı, alan sonucu ve maksimum metin uzunluğu (0 = sınır yok)
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Hello", 0);
builder.insertField("MERGEFIELD CustomerFirstName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD CustomerLastName \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " , ", 0);

// Belgeye paragraf sonu ekleme
builder.insertParagraph();

// Posta gövdesi ekle
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Thanks for purchasing our ", 0);
builder.insertField("MERGEFIELD ProductName \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", please download your Invoice at ",
	0);
builder.insertField("MERGEFIELD InvoiceURL \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "",
	". If you have any questions please call ", 0);
builder.insertField("MERGEFIELD Supportphone \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ", or email us at ", 0);
builder.insertField("MERGEFIELD SupportEmail \\* MERGEFORMAT");

builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", ".", 0);

builder.insertParagraph();

// Posta bitişi ekle
builder.insertTextInput("TextInput", TextFormFieldType.REGULAR, "", "Best regards,", 0);
builder.insertBreak(BreakType.LINE_BREAK);
builder.insertField("MERGEFIELD EmployeeFullname \\* MERGEFORMAT");

builder.insertTextInput("TextInput1", TextFormFieldType.REGULAR, "", " ", 0);
builder.insertField("MERGEFIELD EmployeeDepartment \\* MERGEFORMAT");

// Belgeyi kaydet
builder.getDocument().save("document.docx");

Java kullanarak Word Belgesinde Adres Mektup Birleştirme gerçekleştirin

Şablon hazır olduğunda, birleştirme alanlarını verilerle doldurabilirsiniz. Word şablonunda Adres Mektup Birleştirme gerçekleştirme adımları aşağıdadır.

Aşağıdaki kod örneği, Java kullanılarak Word belgelerinde adres mektup birleştirmenin nasıl gerçekleştirileceğini gösterir.

// Şablonumuz için kodu ekleyin
Document doc = new Document();

// Belgeyi belge oluşturucuya iletin
DocumentBuilder builder = new DocumentBuilder(doc);

// Birleştirme Alanları Oluştur
builder.insertField(" MERGEFIELD CustomerName ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Item ");
builder.insertParagraph();
builder.insertField(" MERGEFIELD Quantity ");

// Şablonu kaydet
builder.getDocument().save("MailMerge.TestTemplate.docx");

// Belgedeki alanları kullanıcı verileriyle doldurun
doc.getMailMerge().execute(new String[] { "CustomerName", "Item", "Quantity" },
		new Object[] { "John Doe", "Hawaiian", "2" });

// belgeyi kaydet 
builder.getDocument().save("MailMerge.Simple.docx");

Şablon

java'da basit adres mektup birleştirme

Çıktı

basit adres mektup birleştirme

XML Veri Kaynağını Kullanarak Adres Mektup Birleştirme Gerçekleştirin

Önceki örnekte, Java nesnelerini kullanarak Adres Mektup Birleştirme gerçekleştirdik. Ancak çoğu durumda, birleştirme alanlarını doldurmak için bir veri kaynağı kullanılır. Gösterim için, Adres Mektup Birleştirme’de bir XML veri kaynağının nasıl kullanılacağına bakalım. Bunun için adımlar aşağıdadır.

  • DataSet sınıfını kullanarak XML veri kaynağını yükleyin.
  • Adres Mektup Birleştirme şablonunu Belge sınıfını kullanarak yükleyin.
  • Veri kaynağındaki istenen veri tablosunu kullanarak birleştirme alanlarını doldurmak için yürütme işlevini kullanın.
  • Oluşturulan Word belgesini Document.save(String) yöntemini kullanarak kaydedin.

Bu örnekte kullanılan XML veri kaynağı aşağıdadır.

<?xml version="1.0" encoding="utf-8"?>
<customers>
	 <customer Name="John Ben Jan" ID="1" Domain="History" City="Boston"/>
 	<customer Name="Lisa Lane" ID="2" Domain="Chemistry" City="LA"/>
	 <customer Name="Dagomir Zits" ID="3" Domain="Heraldry" City="Milwaukee"/>
 	<customer Name="Sara Careira Santy" ID="4" Domain="IT" City="Miami"/>
</customers>

Aşağıdaki kod örneği, sağlanan XML veri kaynağındaki Müşteri verileri tablosunu kullanarak Adres Mektup Birleştirme şablonunun nasıl doldurulacağını gösterir.

// Veri Kümesini oluşturun ve XML'i okuyun
DataSet customersDs = new DataSet();
customersDs.readXml("Customers.xml");

// Bir şablon belgesi açın
Document doc = new Document("TestFile XML.docx");

// DataTable'ı kullanarak şablonu XML'den alınan verilerle doldurmak için adres mektup birleştirmeyi yürütün.
// Bu sınıfın ayrıca tek bir yinelenebilir bölge (ve iç içe geçmiş bölgeler) ile çalıştığını unutmayın.
// Tek bir XML veri kaynağından birden çok bölgeyi aynı anda birleştirmek için XmlMailMergeDataSet sınıfını kullanın.
// örneğin doc.getMailMerge().executeWithRegions(new XmlMailMergeDataSet(xmlData));
doc.getMailMerge().execute(customersDs.getTables().get("Customer"));

// Çıkış belgesini kaydet
doc.save("generated-document.docx");

Şablon

XML ile adres mektup birleştirme

Çıktı

adres mektup birleştirme xml'i

Java’da Bölgelerle Adres Mektup Birleştirme

Bazı durumlarda, belgede belirli bir bölgeyi tekrarlamanız gerekebilir. Örneğin, her müşteri tarafından verilen siparişleri ayrı bir tabloda görüntülemek istiyorsunuz. Bu gibi durumlarda Adres Mektup Birleştirme bölgelerinden yararlanabilirsiniz. Bölge oluşturmak için bölgenin başlangıç ve bitişini belirtebilirsiniz. Sonuç olarak, Adres Mektup Birleştirme yürütmesi sırasında verilerin her bir örneği için bölge tekrarlanacaktır.

Aşağıdaki ekran görüntüsü, bölgenin bir tablodan oluştuğu bir şablonu göstermektedir. «TableStart:Customers» ile başlar ve «TableEnd:Customers» ile biter.

adres mektup birleştirme bölgesi şablonu

Aşağıdaki kod örneği, bölgelerle bir şablonun nasıl oluşturulacağını ve bunun verilerle nasıl doldurulacağını gösterir.

// Belge oluştur
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Veri kümesi bölgeleriyle adres mektup birleştirmenin başlangıç noktası.
builder.insertField(" MERGEFIELD TableStart:Customers");
// "Müşteriler" tablosunun "MüşteriAdı" sütununun satırlarındaki veriler
// bu BİRLEŞTİRMEDE.
builder.write("Orders for ");
builder.insertField(" MERGEFIELD CustomerName");
builder.write(":");

// Sütun başlıkları oluştur
builder.startTable();
builder.insertCell();
builder.write("Item");
builder.insertCell();
builder.write("Quantity");
builder.endRow();

// Çoktan bire sahip "Siparişler" adlı ikinci bir veri tablomuz var.
// "Müşteriler" ile ilişki
// aynı CustomerID değerine sahip satırları almak.
builder.insertCell();
builder.insertField(" MERGEFIELD TableStart:Orders");
builder.insertField(" MERGEFIELD ItemName");
builder.insertCell();
builder.insertField(" MERGEFIELD Quantity");
builder.insertField(" MERGEFIELD TableEnd:Orders");
builder.endTable();

// Bölgelerle adres mektup birleştirmenin uç noktası.
builder.insertField(" MERGEFIELD TableEnd:Customers");

// Bölgelerle adres mektup birleştirme gerçekleştirmek için veri kümemizi iletin.
DataSet customersAndOrders = CreateDataSet();
doc.getMailMerge().executeWithRegions(customersAndOrders);

// sonucu kaydet
doc.save("MailMerge.ExecuteWithRegions.docx");

Çıktı

adres mektup birleştirme bölgesi

Java kullanarak İç İçe Adres Mektup Birleştirme Bölgeleri Oluşturma

Adres Mektup Birleştirme’deki diğer bir popüler senaryo, bölgeleri iç içe geçirdiğiniz zamandır. Örneğin, siparişleri ve her siparişteki kalemleri listelemeniz gerektiğinde iç içe geçmiş bölgeleri kullanabilirsiniz. Aşağıdaki resim, iç içe geçmiş bölgeler hakkında resmi daha net hale getiriyor.

Yukarıdaki resimde, Siparişler tablosuna ve Öğeler’deki her kaydın Siparişler’deki bir kayda bağlı olduğu Öğeler tablosuna sahibiz. Bu nedenle, bu iki tablo arasında birden çoğa bir ilişki vardır. Bu gibi durumlarda Aspose.Words, Adres Mektup Birleştirmeyi DataSet’te tanımlanan ilişkilere dikkat ederek yürütür. Örneğin, bir XML veri kaynağımız varsa Aspose.Words, ilişkileri bulmak için ya şema bilgisini ya da XML yapısını kullanır. Böylece, manuel olarak kendiniz halletmeniz gerekmeyecek ve Document.getMailMerge().executeWithRegions(DataSet) yöntemi sizin için çalışacaktır (önceki örnekte olduğu gibi).

Birleştirme Alanlarına Özel Biçimlendirme Uygula

Adres Mektup Birleştirme üzerinde size daha fazla kontrol sağlamak için Aspose.Words for Java, Adres Mektup Birleştirme işlemi sırasında birleştirme alanlarını özelleştirmenize izin verir. setFieldMergingCallback(IFieldMergingCallback) yöntemi, Adres Mektup Birleştirme işlemi üzerinde özel denetim için fieldMerging(FieldMergingArgs) ve imageFieldMerging(ImageFieldMergingArgs) yöntemlerini uygulayan bir sınıfı kabul eder. fieldMerging(FieldMergingArgs) olayı, Adres Mektup Birleştirme yürütmesi sırasında bir birleştirme alanıyla karşılaşıldığında gerçekleşir.

Adres Mektup Birleştirme işleminin nasıl özelleştirileceğine ve hücrelere biçimlendirmenin nasıl uygulanacağına ilişkin tam kod örneği aşağıdadır.

public class ApplyCustomFormattingDuringMailMerge {

    private static final String dataDir = Utils.getSharedDataDir(ApplyCustomFormattingDuringMailMerge.class) + "MailMerge/";

    public static void main(String[] args) throws Exception {
        Document doc = new Document(dataDir + "MailMerge.AlternatingRows.doc");

        // MergeField olayı için bir işleyici ekleyin.
        doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());

        // Bölgelerle adres mektup birleştirmeyi yürütün.
        DataTable dataTable = getSuppliersDataTable();
        doc.getMailMerge().executeWithRegions(dataTable);

        doc.save(dataDir + "MailMerge.AlternatingRows Out.doc");
    }

    /**
     * Değer tek ise true döndürür; değer çift ise false.
     */
    public static boolean isOdd(int value) throws Exception {
        return (value % 2 != 0);
    }

    /**
     * DataTable oluşturun ve onu verilerle doldurun. Gerçek hayatta bu DataTable
     * veri tabanından doldurulmalıdır.
     */
    private static DataTable getSuppliersDataTable() throws Exception {
        java.sql.ResultSet resultSet = createCachedRowSet(new String[]{"CompanyName", "ContactName"});

       for (int i = 0; i < 10; i++)
            addRow(resultSet, new String[]{"Company " + Integer.toString(i), "Contact " + Integer.toString(i)});

        return new DataTable(resultSet, "Suppliers");
    }

    /**
     * İle bağlantısı kesilmiş boş bir Java ResultSet oluşturan yardımcı bir yöntem
     * belirtilen sütunlar.
     */
    private static ResultSet createCachedRowSet(String[] columnNames) throws Exception {
        RowSetMetaDataImpl metaData = new RowSetMetaDataImpl();
        metaData.setColumnCount(columnNames.length);
       for (int i = 0; i < columnNames.length; i++) {
            metaData.setColumnName(i + 1, columnNames[i]);
            metaData.setColumnType(i + 1, java.sql.Types.VARCHAR);
        }

        CachedRowSet rowSet = RowSetProvider.newFactory().createCachedRowSet();
        ;
        rowSet.setMetaData(metaData);

        return rowSet;
    }

    /**
     * Belirtilen değerlerle yeni bir satır ekleyen bir yardımcı yöntem.
     * ResultSet'in bağlantısı kesildi.
     */
    private static void addRow(ResultSet resultSet, String[] values) throws Exception {
        resultSet.moveToInsertRow();

       for (int i = 0; i < values.length; i++)
            resultSet.updateString(i + 1, values[i]);

        resultSet.insertRow();

        // Bu "dans", sonuç kümesinin sonuna düzgün bir şekilde satır eklemek için gereklidir.
        // Başka bir şey yaparsam satırlar ya öne eklenir ya da sonuca
        // set, adres mektup birleştirme sırasında silinen bir satırla ilgili bir istisna atar.
        resultSet.moveToCurrentRow();
        resultSet.last();
    }
}

class HandleMergeFieldAlternatingRows implements IFieldMergingCallback {
    /**
     * Belgede karşılaşılan her birleştirme alanı için çağrılır. biz de yapabiliriz
     * bazı verileri adres mektup birleştirme motoruna döndürün veya adres mektup birleştirme motoruyla başka bir şey yapın.
     * belge. Bu durumda hücre biçimlendirmesini değiştiririz.
     */
    public void fieldMerging(FieldMergingArgs e) throws Exception {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.getDocument());

        // Bu şekilde yeni bir satırın başlangıcını yakalamış oluyoruz.
        if (e.getFieldName().equals("CompanyName")) {
            // Satır numarasının çift mi tek mi olduğuna bağlı olarak rengi seçin.
            Color rowColor;
            if (ApplyCustomFormattingDuringMailMerge.isOdd(mRowIdx))
                rowColor = new Color(213, 227, 235);
            else
                rowColor = new Color(242, 242, 242);

            // Şu anda tüm satır için hücre özelliklerini ayarlamanın bir yolu yoktur.
            // bu yüzden sıradaki tüm hücreleri yinelemeliyiz.
           for (int colIdx = 0; colIdx < 4; colIdx++) {
                mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
                mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
            }

            mRowIdx++;
        }
    }

    public void imageFieldMerging(ImageFieldMergingArgs args) throws Exception {
        // Hiçbir şey yapma.
    }

    private DocumentBuilder mBuilder;
    private int mRowIdx;
}

Çözüm

Adres Mektup Birleştirme, MS Word belgelerini dinamik olarak oluşturmak için size çok çeşitli özellikler sunar. Veritabanlarındaki veya diğer veri kaynaklarındaki verilere dayalı olarak basit ve karmaşık raporlar oluşturabilirsiniz. Bu makalede, Adres Mektup Birleştirme özelliklerini Java kullanarak programlı olarak nasıl uygulayacağınızı gördünüz. Belgeleri kullanarak Java Adres Mektup Birleştirme API’si hakkında daha fazla bilgi edinebilirsiniz.

Ayrıca bakınız