Checkboxes、テキスト入力、または画像を挿入します

マージエンジンはドキュメントを入力として受け取り、その中のMERGEFIELDフィールドを探し、データソースから取得したデータに置き換えます。 通常、プレーンテキストとHTMLが挿入されますが、Aspose.WordsユーザーはMail Mergeフィールドのより珍しいシナリオを処理する文書を生成することもできます。

強力なAspose.Words機能を使用するとMail Mergeプロセスを拡張できます:

• checkboxesおよびテキスト入力フォームフィールドをmail merge中にドキュメントに挿入します
• 任意のカスタムストレージ(ファイル、BLOBフィールドなど)から画像を挿入します。)

Mail Merge中にCheckboxesとテキスト入力を挿入します

差し込み項目でテキストが置換されるのではなく、checkboxまたはテキスト入力フィールドで置換されるように、Mail Merge操作を実行する必要がある場合があります。 これは最も一般的なシナリオではありませんが、一部のタスクでは非常に便利です。

次のWordドキュメントのスクリーンショットは、差し込み項目を含むテンプレートを示しています:

以下のWord文書のスクリーンショットは、既に生成された文書を示しています:

一部のフィールドはプレーンテキストに置き換えられ、一部のフィールドはcheckboxフォームフィールドに置き換えられ、Subjectフィールドはテキスト入力フィールドに置

次のコード例は、mail merge中にcheckboxesと入力テキストフィールドをドキュメントに挿入する方法を示しています:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document(MyDir + "Mail merge destinations - Fax.docx");

// Setup mail merge event handler to do the custom work.
doc.MailMerge.FieldMergingCallback = new HandleMergeField();
// Trim trailing and leading whitespaces mail merge values.
doc.MailMerge.TrimWhitespaces = false;

string[] fieldNames = {
    "RecipientName", "SenderName", "FaxNumber", "PhoneNumber",
    "Subject", "Body", "Urgent", "ForReview", "PleaseComment"
};

object[] fieldValues = {
    "Josh", "Jenny", "123456789", "", "Hello",
    "<b>HTML Body Test message 1</b>", true, false, true
};

doc.MailMerge.Execute(fieldNames, fieldValues);

doc.Save(ArtifactsDir + "WorkingWithFields.MailMergeFormFields.docx");

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
private class HandleMergeField : IFieldMergingCallback
{
    /// <summary>
    /// This handler is called for every mail merge field found in the document,
    /// for every record found in the data source.
    /// </summary>
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs e)
    {
        if (mBuilder == null)
            mBuilder = new DocumentBuilder(e.Document);

        // We decided that we want all boolean values to be output as check box form fields.
        if (e.FieldValue is bool)
        {
            // Move the "cursor" to the current merge field.
            mBuilder.MoveToMergeField(e.FieldName);

            string checkBoxName = $"{e.FieldName}{e.RecordIndex}";

            mBuilder.InsertCheckBox(checkBoxName, (bool) e.FieldValue, 0);

            return;
        }

        switch (e.FieldName)
        {
            case "Body":
                mBuilder.MoveToMergeField(e.FieldName);
                mBuilder.InsertHtml((string) e.FieldValue);
                break;
            case "Subject":
            {
                mBuilder.MoveToMergeField(e.FieldName);
                string textInputName = $"{e.FieldName}{e.RecordIndex}";
                mBuilder.InsertTextInput(textInputName, TextFormFieldType.Regular, "", (string) e.FieldValue, 0);
                break;
            }
        }
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        args.ImageFileName = "Image.png";
        args.ImageWidth.Value = 200;
        args.ImageHeight = new MergeFieldImageDimension(200, MergeFieldImageDimensionUnit.Percent);
    }

    private DocumentBuilder mBuilder;
}

Mail Merge中に画像を挿入する

Mail Merge操作を実行するときは、特殊なimageMail Mergeフィールドを使用してデータベースからドキュメントにイメージを挿入できます。 ImageMail MergeフィールドはImage:MyFieldNameという名前の差し込み項目です。

データベースからの画像の挿入

Mail merge中に、ドキュメント内で画像Mail Mergeフィールドが検出されると、FieldMergingCallbackイベントが発生します。 このイベントに応答して、ファイル名、ストリーム、または画像オブジェクトをMail Mergeエンジンに返し、ドキュメントに挿入できるようにすることができます。

次のコード例は、データベースBLOBフィールドに格納されている画像をレポートに挿入する方法を示しています:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document(MyDir + "Mail merge destination - Northwind employees.docx");

doc.MailMerge.FieldMergingCallback = new HandleMergeImageFieldFromBlob();

string connString = "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + DatabaseDir + "Northwind.accdb";
OleDbConnection conn = new OleDbConnection(connString);
conn.Open();

OleDbCommand cmd = new OleDbCommand("SELECT * FROM Employees", conn);
IDataReader dataReader = cmd.ExecuteReader();

doc.MailMerge.ExecuteWithRegions(dataReader, "Employees");

conn.Close();
            
doc.Save(ArtifactsDir + "WorkingWithFields.MailMergeImageFromBlob.docx");

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
public class HandleMergeImageFieldFromBlob : IFieldMergingCallback
{
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        // Do nothing.
    }

    /// <summary>
    /// This is called when mail merge engine encounters Image:XXX merge field in the document.
    /// You have a chance to return an Image object, file name, or a stream that contains the image.
    /// </summary>
    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs e)
    {
        // The field value is a byte array, just cast it and create a stream on it.
        MemoryStream imageStream = new MemoryStream((byte[]) e.FieldValue);
        // Now the mail merge engine will retrieve the image from the stream.
        e.ImageStream = imageStream;
    }
}

Mail Merge中にイメージプロパティを設定する

画像の差し込み項目をマージする際に、WrapTypeなどのさまざまな画像プロパティを制御する必要がある場合があります。

現在、ImageFieldMergingArgsを使用すると、それぞれ画像の幅または高さのプロパティのみを設定できます。 この問題を解決するために、Aspose.WordsはShapeプロパティを提供し、挿入された画像やその他の形状を完全に制御するのを容易にします。

次のコード例は、さまざまなイメージプロパティを設定する方法を示しています:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.Writeln("{{#foreach example}}");
builder.Writeln("{{Image(126pt;126pt):stempel}}");
builder.Writeln("{{/foreach example}}");

doc.MailMerge.UseNonMergeFields = true;
doc.MailMerge.TrimWhitespaces = true;
doc.MailMerge.UseWholeParagraphAsRegion = false;
doc.MailMerge.CleanupOptions = MailMergeCleanupOptions.RemoveEmptyTableRows
        | MailMergeCleanupOptions.RemoveContainingFields
        | MailMergeCleanupOptions.RemoveUnusedRegions
        | MailMergeCleanupOptions.RemoveUnusedFields;

doc.MailMerge.FieldMergingCallback = new ImageFieldMergingHandler();
doc.MailMerge.ExecuteWithRegions(new DataSourceRoot());

doc.Save(ArtifactsDir + "WorkingWithFields.MailMergeImageField.docx");

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
private class ImageFieldMergingHandler : IFieldMergingCallback
{
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        //  Implementation is not required.
    }

    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs args)
    {
        Shape shape = new Shape(args.Document, ShapeType.Image)
        {
            Width = 126, Height = 126, WrapType = WrapType.Square
        };

        shape.ImageData.SetImage(MyDir + "Mail merge image.png");

        args.Shape = shape;
    }
}

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
public class DataSourceRoot : IMailMergeDataSourceRoot
{
    public IMailMergeDataSource GetDataSource(string s)
    {
        return new DataSource();
    }

    private class DataSource : IMailMergeDataSource
    {
        private bool next = true;

        string IMailMergeDataSource.TableName => TableName();

        private string TableName()
        {
            return "example";
        }

        public bool MoveNext()
        {
            bool result = next;
            next = false;
            return result;
        }

        public IMailMergeDataSource GetChildDataSource(string s)
        {
            return null;
        }

        public bool GetValue(string fieldName, out object fieldValue)
        {
            fieldValue = null;
            return false;
        }
    }
}