Mail Merge z regionami

Możesz tworzyć różne regiony w szablonie, aby mieć specjalne obszary, które możesz po prostu wypełnić swoimi danymi. Użyj Mail Merge z regionami, jeśli chcesz wstawić tabele, wiersze z powtarzającymi się danymi, aby dokumenty dynamicznie rosły, określając te regiony w szablonie.

Możesz tworzyć zagnieżdżone (podrzędne) regiony, a także scalać regiony. Główną zaletą korzystania z tego typu jest dynamiczne zwiększanie części wewnątrz dokumentu. Zobacz więcej szczegółów w następnym artykule “zagnieżdżone Mail Merge z regionami”.

Informacje o regionie Mail Merge można uzyskać za pomocą klasy MailMergeRegionInfo.

Jak wykonać Mail Merge z regionami

Region Mail Merge to określona część dokumentu, która ma punkt początkowy i punkt końcowy. Oba punkty są reprezentowane jako Mail Merge pola o określonych nazwach “TableStart:XXX” i “TableEnd:XXX”. Cała zawartość zawarta w regionie Mail Merge Zostanie Automatycznie powtórzona dla każdego rekordu w źródle danych.

Aspose.Words umożliwia wykonywanie Mail Merge z regionami przy użyciu jednej z metod ExecuteWithRegions, które akceptują IMailMergeDataSource niestandardowe źródło danych.

Poniższy przykład kodu pokazuje, jak wykonać Mail Merge z regionami z bazy danych sqlite za pomocą SQLiteCpp:

	// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C.git.
	void NestedMailMerge()
	{
	auto doc = MakeObject<Document>();
	auto builder = MakeObject<DocumentBuilder>(doc);
	builder->InsertField(u" MERGEFIELD TableStart:Customers");

	builder->Write(u"Full name:\t");
	builder->InsertField(u" MERGEFIELD FullName ");
	builder->Write(u"\nAddress:\t");
	builder->InsertField(u" MERGEFIELD Address ");
	builder->Write(u"\nOrders:\n");

	builder->InsertField(u" MERGEFIELD TableStart:Orders");

	builder->Write(u"\tItem name:\t");
	builder->InsertField(u" MERGEFIELD ItemName ");
	builder->Write(u"\n\tQuantity:\t");
	builder->InsertField(u" MERGEFIELD Quantity ");
	builder->InsertParagraph();

	builder->InsertField(u" MERGEFIELD TableEnd:Orders");

	builder->InsertField(u" MERGEFIELD TableEnd:Customers");

	SQLite::Database database((std::string)(DatabaseDir + u"customers.db3"));

	// To be able to mail merge from your data source,
	// it must be wrapped into an object that implements the IMailMergeDataSource interface.
	auto customersDataSource = MakeObject<NestedMailMergeCustom::CustomersDataSource>(database);

	doc->get_MailMerge()->ExecuteWithRegions(customersDataSource);

	doc->Save(ArtifactsDir + u"NestedMailMergeCustom.CustomMailMerge.docx");
	}

	class OrdersDataSource : public MailMerging::IMailMergeDataSource
	{
	public:
	OrdersDataSource(SQLite::Database& database, int32_t id)
	: mQuery(database, "SELECT ItemName, Quantity FROM Orders WHERE CustomerId = ?")
	{
	mQuery.bind(1, id);
	}

	String get_TableName() override
	{
	return u"Orders";
	}

	bool GetValue(String fieldName, SharedPtr<Object>& fieldValue) override
	{

	if (fieldName == u"ItemName")
	{
	fieldValue = System::ObjectExt::Box<String>(String::FromUtf8(mQuery.getColumn(0).getString()));
	return true;
	}

	if (fieldName == u"Quantity")
	{
	fieldValue = System::ObjectExt::Box<int32_t>(mQuery.getColumn(1).getInt());
	return true;
	}

	fieldValue.reset();
	return false;
	}

	bool MoveNext() override
	{
	return mQuery.executeStep();
	}

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

	private:
	SQLite::Statement mQuery;
	};

	class CustomersDataSource : public MailMerging::IMailMergeDataSource
	{
	public:
	CustomersDataSource(SQLite::Database& database)
	: mDatabase{ database }
	, mQuery{ mDatabase, "SELECT * FROM Customers" }
	{
	}

	String get_TableName() override
	{
	return u"Customers";
	}

	bool GetValue(String fieldName, SharedPtr<Object>& fieldValue) override
	{
	if (fieldName == u"FullName")
	{
	fieldValue = System::ObjectExt::Box<String>(String::FromUtf8(mQuery.getColumn(1).getString()));
	return true;
	}

	if (fieldName == u"Address")
	{
	fieldValue = System::ObjectExt::Box<String>(String::FromUtf8(mQuery.getColumn(2).getString()));
	return true;
	}

	fieldValue.reset();
	return false;
	}

	bool MoveNext() override
	{
	return mQuery.executeStep();
	}

	SharedPtr<IMailMergeDataSource> GetChildDataSource(String tableName) override
	{
	if (tableName == u"Orders")
	{
	return MakeObject<OrdersDataSource>(mDatabase, mQuery.getColumn(0).getInt());
	}
	return nullptr;
	}
	private:
	SQLite::Database& mDatabase;
	SQLite::Statement mQuery;
	};

view raw nested-mail-merge.h hosted with ❤ by GitHub

Możesz zauważyć różnicę między dokumentem przed wykonaniem Mail Merge z regionami:

I po wykonaniu Mail Merge z regionami:

Ograniczenia Mail Merge z regionami

Jest kilka ważnych punktów, które należy wziąć pod uwagę podczas wykonywania Mail Merge z regionami:

Punkt początkowy TableStart:Orders i punkt końcowy TableEnd:Orders muszą znajdować się w tym samym wierszu lub komórce. Na przykład, jeśli rozpoczynasz region scalania w komórce tabeli, musisz zakończyć region scalania w tym samym wierszu, co pierwsza komórka. Nazwa pola scalania musi być zgodna z nazwą kolumny w DataTable. Jeśli nie określisz mapowanych pól, Mail Merge z regionami nie powiedzie się dla żadnego pola scalania, które ma nazwę inną niż nazwa kolumny.
Aspose.Words dla C++ obsługuje tylko źródła danych oparte na IMailMergeDataSource i IMailMergeDataSourceRoot. W przeciwieństwie do .NET i Java, C++ nie ma ogólnie przyjętego wieloplatformowego API do pracy z bazami danych (takimi jak ADODB, ODBC lub JDBC). Aby pracować z określonym źródłem danych, musisz zaimplementować interfejs IMailMergeDataSource lub IMailMergeDataSourceRoot.

Jeśli jedna z tych zasad zostanie złamana, otrzymasz nieoczekiwane wyniki lub może zostać zgłoszony wyjątek.

Jeśli nie używasz regionów Mail Merge, będzie on podobny do Microsoft Word mail merge, a cała zawartość dokumentu zostanie powtórzona dla każdego rekordu w źródle danych.

Prosta operacja Mail Merge W C++ Zagnieżdżone Mail Merge z regionami w C++