إدراج Checkbox إس، إدخال النص، أو الصور

يأخذ محرك الدمج مستندا كمدخل، ويبحث عن MERGEFIELD الحقول فيه، ويستبدلها بالبيانات التي تم الحصول عليها من مصدر البيانات. عادة، يتم إدراج نص عادي و HTML، ولكن يمكن للمستخدمين Aspose.Words أيضا إنشاء مستند يتعامل مع سيناريوهات أكثر غرابة لحقول mail merge.

تتيح لك وظيفة Aspose.Words القوية تمديد عملية mail merge:

• أدخل مربعات الاختيار وحقول نموذج إدخال النص في المستند أثناء mail merge
• أدخل الصور من أي مساحة تخزين مخصصة (ملفات، BLOB حقول، إلخ.)

إدراج Checkbox إس وإدخال النص خلال Mail Merge

في بعض الأحيان يكون من الضروري إجراء عملية Mail Merge بحيث لا يتم استبدال النص في حقل الدمج، ولكن يتم استبدال مربع الاختيار أو حقل إدخال النص. على الرغم من أن هذا ليس السيناريو الأكثر شيوعا، إلا أنه مفيد جدا لبعض المهام.

تظهر لقطة الشاشة التالية لمستند ورد نموذجا يحتوي على حقول دمج:

تظهر لقطة الشاشة هذه لمستند ورد أدناه المستند الذي تم إنشاؤه بالفعل:

لاحظ أنه تم استبدال بعض الحقول بنص عادي، وتم استبدال بعض الحقول بحقول نموذج مربع الاختيار، وتم استبدال الحقل Subject بحقل إدخال نص.

يوضح مثال الكود التالي كيفية إدراج مربعات الاختيار وحقول النص المدخلة في مستند أثناء mail merge:

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

// Setup mail merge event handler to do the custom work.
doc->get_MailMerge()->set_FieldMergingCallback(MakeObject<WorkingWithFields_::HandleMergeField>());
// Trim trailing and leading whitespaces mail merge values.
doc->get_MailMerge()->set_TrimWhitespaces(false);

ArrayPtr<String> fieldNames =
    MakeArray<String>({u"RecipientName", u"SenderName", u"FaxNumber", u"PhoneNumber", u"Subject", u"Body", u"Urgent", u"ForReview", u"PleaseComment"});

ArrayPtr<SharedPtr<System::Object>> fieldValues = MakeArray<SharedPtr<System::Object>>(
    {System::ObjectExt::Box<String>(u"Josh"), System::ObjectExt::Box<String>(u"Jenny"), System::ObjectExt::Box<String>(u"123456789"),
     System::ObjectExt::Box<String>(u""), System::ObjectExt::Box<String>(u"Hello"), System::ObjectExt::Box<String>(u"<b>HTML Body Test message 1</b>"),
     System::ObjectExt::Box<bool>(true), System::ObjectExt::Box<bool>(false), System::ObjectExt::Box<bool>(true)});

doc->get_MailMerge()->Execute(fieldNames, fieldValues);

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

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
class HandleMergeField : public IFieldMergingCallback
{
private:
    SharedPtr<DocumentBuilder> mBuilder;

    /// <summary>
    /// This handler is called for every mail merge field found in the document,
    /// for every record found in the data source.
    /// </summary>
    void FieldMerging(SharedPtr<FieldMergingArgs> e) override
    {
        if (mBuilder == nullptr)
        {
            mBuilder = MakeObject<DocumentBuilder>(e->get_Document());
        }

        // We decided that we want all boolean values to be output as check box form fields.
        if (System::ObjectExt::Is<bool>(e->get_FieldValue()))
        {
            // Move the "cursor" to the current merge field.
            mBuilder->MoveToMergeField(e->get_FieldName());

            String checkBoxName = String::Format(u"{0}{1}", e->get_FieldName(), e->get_RecordIndex());

            mBuilder->InsertCheckBox(checkBoxName, System::ObjectExt::Unbox<bool>(e->get_FieldValue()), 0);

            return;
        }

        if (e->get_FieldName() == u"Body")
        {
            mBuilder->MoveToMergeField(e->get_FieldName());
            mBuilder->InsertHtml(System::ObjectExt::Unbox<String>(e->get_FieldValue()));
        }
        else if (e->get_FieldName() == u"Subject")
        {
            mBuilder->MoveToMergeField(e->get_FieldName());
            String textInputName = String::Format(u"{0}{1}", e->get_FieldName(), e->get_RecordIndex());
            mBuilder->InsertTextInput(textInputName, TextFormFieldType::Regular, u"", System::ObjectExt::Unbox<String>(e->get_FieldValue()), 0);
        }
    }

    void ImageFieldMerging(SharedPtr<ImageFieldMergingArgs> args) override
    {
        args->set_ImageFileName(u"Image.png");
        args->get_ImageWidth()->set_Value(200);
        args->set_ImageHeight(MakeObject<MergeFieldImageDimension>(200, MergeFieldImageDimensionUnit::Percent));
    }
};

إدراج الصور خلال Mail Merge

عند إجراء عملية mail merge، يمكنك إدراج صور من قاعدة البيانات في المستند باستخدام حقول صورة خاصة mail merge. حقل الصورة Mail Merge هو حقل دمج اسمه صورة: 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-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

// MERGEFIELDs with "Image:" tags will receive an image during a mail merge.
// The string after the colon in the "Image:" tag corresponds to a column name
// in the data source whose cells contain URIs of image files.
builder->InsertField(u"MERGEFIELD  Image:logo_FromWeb ");
builder->InsertField(u"MERGEFIELD  Image:logo_FromFileSystem ");

// Create a data source that contains URIs of images that we will merge.
// A URI can be a web URL that points to an image, or a local file system filename of an image file.
ArrayPtr<String> columns = MakeArray<String>({u"logo_FromWeb", u"logo_FromFileSystem"});
ArrayPtr<SharedPtr<System::Object>> URIs =
    MakeArray<SharedPtr<System::Object>>({System::ObjectExt::Box<String>(ImageUrl), System::ObjectExt::Box<String>(ImageDir + u"Logo.jpg")});

// Execute a mail merge on a data source with one row.
doc->get_MailMerge()->Execute(columns, URIs);

doc->Save(ArtifactsDir + u"MailMergeEvent.ImageFromUrl.docx");

تعيين خصائص الصورة خلال Mail Merge

أثناء دمج حقل دمج الصور، قد تحتاج أحيانا إلى التحكم في خصائص الصورة المختلفة، مثل WrapType.

حاليا، باستخدام ImageFieldMergingArgs، يمكنك فقط تعيين خصائص عرض الصورة أو ارتفاعها، على التوالي. للتغلب على هذه المشكلة، يوفر Aspose.Words خاصية Shape، مما يسهل التحكم الكامل في الصورة المدرجة أو أي شكل آخر.

يوضح مثال التعليمات البرمجية التالية كيفية تعيين خصائص صورة مختلفة:

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

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

doc->get_MailMerge()->set_UseNonMergeFields(true);
doc->get_MailMerge()->set_TrimWhitespaces(true);
doc->get_MailMerge()->set_UseWholeParagraphAsRegion(false);
doc->get_MailMerge()->set_CleanupOptions(MailMergeCleanupOptions::RemoveEmptyTableRows | MailMergeCleanupOptions::RemoveContainingFields |
                                         MailMergeCleanupOptions::RemoveUnusedRegions | MailMergeCleanupOptions::RemoveUnusedFields);

doc->get_MailMerge()->set_FieldMergingCallback(MakeObject<WorkingWithFields_::ImageFieldMergingHandler>());
doc->get_MailMerge()->ExecuteWithRegions(MakeObject<WorkingWithFields_::DataSourceRoot>());

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

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
class ImageFieldMergingHandler : public IFieldMergingCallback
{
private:
    void FieldMerging(SharedPtr<FieldMergingArgs> args) override
    {
        ASPOSE_UNUSED(args);
        //  Implementation is not required.
    }

    void ImageFieldMerging(SharedPtr<ImageFieldMergingArgs> args) override
    {
        auto shape = MakeObject<Shape>(args->get_Document(), ShapeType::Image);
        shape->set_Width(126);
        shape->set_Height(126);
        shape->set_WrapType(WrapType::Square);

        shape->get_ImageData()->SetImage(MyDir + u"Mail merge image.png");

        args->set_Shape(shape);
    }
};

//For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
class DataSourceRoot : public IMailMergeDataSourceRoot
{
private:
    class DataSource : public IMailMergeDataSource
    {
    public:
        bool MoveNext() override
        {
            bool result = next;
            next = false;
            return result;
        }

        SharedPtr<IMailMergeDataSource> GetChildDataSource(String s) override
        {
            ASPOSE_UNUSED(s);
            return nullptr;
        }

        bool GetValue(String fieldName, SharedPtr<System::Object>& fieldValue) override
        {
            ASPOSE_UNUSED(fieldName);
            fieldValue.reset();
            return false;
        }

        DataSource() : next(true)
        {
        }

    private:
        bool next;

        String get_TableName() override
        {
            return TableName();
        }

        String TableName()
        {
            return u"example";
        }
    };

public:
    SharedPtr<IMailMergeDataSource> GetDataSource(String s) override
    {
        ASPOSE_UNUSED(s);
        return MakeObject<WorkingWithFields_::DataSourceRoot::DataSource>();
    }
};