TX Text Control 中的郵件合并 類是一個強大的庫，旨在通過將數據合并到模板中來自動創建文檔。它充當結構化數據（例如來自數據庫、JSON 或 XML）和動態文檔生成之間的橋梁，對于需要自動化文檔工作流程的應用程序來說非常有用。

從本質上講，MailMerge 類簡化了創建專業、數據驅動文檔的復雜任務，允許開發人員輕松地將模板中的字段與數據源合并。模板是使用 TX Text Control 文字處理界面設計的，合并字段代表動態內容。

TX Text Control 是一款功能類似于 MS Word 的文字處理控件，包括文檔創建、編輯、打印、郵件合并、格式轉換、拆分合并、導入導出、批量生成等功能。廣泛應用于企業文檔管理，網站內容發布，電子病歷中病案模板創建、病歷書寫、修改歷史、連續打印、病案歸檔等功能的實現。

TX Text Control 最新下載   

合并區塊

合并塊是 TX Text Control 的 MailMerge 類中的一個關鍵概念，它允許在文檔中動態生成結構化、可重復的內容。合并塊允許開發人員有效地處理模板中的重復數據結構，例如列表、表格或嵌套區域。

從高層次上講，合并塊是模板中定義的部分，對應于數據集合或數據表。在合并過程中，MailMerge 會遍歷數據源，動態創建每條記錄的內容。這些合并塊可以使用 MailMerge 類的現成功能進行有條件的呈現、過濾和排序。

代碼級操作

但是 MailMerge 類還允許在合并過程中進行非常詳細的代碼級操作。這包括處理合并事件、自定義合并過程以及以編程方式控制合并操作的輸出。這種級別的控制對于需要對合并過程進行細粒度控制的復雜文檔生成場景至關重要。

本文介紹如何使用“字段合并” 事件來操作合并字段位于表格單元格內時由事件返回的表格單元格。在本例中，我們將使用一個非常簡單的模板，該模板由兩個合并字段和一個用紅色突出顯示的簡單重復塊組成。

為了合并模板，我們將使用以下簡化的 JSON 數據。

[
{
"invoice-id": "1",
"invoice-date": "2019-01-01",
"line-items": [
{
"product-id": "1",
"quantity": "1",
"unit-price": "8"
},
{
"product-id": "2",
"quantity": "2",
"unit-price": "200"
},
{
"product-id": "3",
"quantity": "1",
"unit-price": "100"
},
{
"product-id": "4",
"quantity": "1",
"unit-price": "3"
}
]
}
]

為了合并此模板，將使用以下代碼：

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);

MailMerge mailMerge = new MailMerge();
mailMerge.TextComponent = textControl1;

string jsonData = File.ReadAllText("data.json");
mailMerge.MergeJsonData(jsonData);

合并后的文檔結果如下：

FieldMerged 事件

現在讓我們附加 FieldMerged 事件來操作合并過程。

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);

MailMerge mailMerge = new MailMerge();
mailMerge.TextComponent = textControl1;
mailMerge.FieldMerged += MailMerge_FieldMerged;

string jsonData = File.ReadAllText("data.json");
mailMerge.MergeJsonData(jsonData);

每次合并字段時（成功或失敗），都會調用此事件。如果字段位于表格單元格內，則返回表格單元格。

在此事件中，我們檢查TableCell屬性是否不為空。如果不為空，我們將設置單元格的背景顏色。

private void MailMerge_FieldMerged(object sender, MailMerge.FieldMergedEventArgs e)
{
if (e.TableCell != null)
{
e.TableCell.CellFormat.BackColor = Color.Red;
e.TableCell.CellFormat.BottomBorderWidth = 60;
e.TableCell.CellFormat.BottomBorderColor = Color.Blue;
}

因此，合并過程中所有合并的單元格都會被著色。

動態單元格顏色

讓我們通過添加一些邏輯使這個過程動態化。CellFilterInstructions類用于將一個值與給定值進行比較以返回特定的顏色。

using System;
using System.Drawing;
using System.Linq;

public class CellFilterInstructions
{
public double? CompareValue { get; set; } = null;
public RelationalOperator? Operator { get; set; } = null;
public Color TrueColor { get; set; } = Color.White;
public Color FalseColor { get; set; } = Color.White;

public enum RelationalOperator
{
Equals = 0,
NotEqual,
LessThan,
GreaterThan,
}

// evaluates the instruction and returns the proper color
public Color? GetColor(string value)
{
if (Double.TryParse(ParseToNumber(value), out double dValue) == true)
{
switch (Operator)
{
case RelationalOperator.Equals:
return (dValue == CompareValue ? TrueColor : FalseColor);
case RelationalOperator.NotEqual:
return (dValue != CompareValue ? TrueColor : FalseColor);
case RelationalOperator.GreaterThan:
return (dValue > CompareValue ? TrueColor : FalseColor);
case RelationalOperator.LessThan:
return (dValue < CompareValue ? TrueColor : FalseColor);
default:
return null;
}
}
else
return null;

}

private string ParseToNumber(string text)
{
var numericChars = "0123456789,.".ToCharArray();
return new String(text.Where(c => numericChars.Any(n => n == c)).ToArray());
}
}

以下代碼創建了一條新規則，如果值大于 10，則返回綠色，如果值小于 10，則返回紅色。此規則被序列化并存儲在表單元格的Name屬性中。

textControl1.Load("template.tx", TXTextControl.StreamType.InternalUnicodeFormat);

CellFilterInstructions cellFilterInstructions = new CellFilterInstructions() {
CompareValue = 10,
Operator = CellFilterInstructions.RelationalOperator.GreaterThan,
TrueColor = Color.Green,
FalseColor = Color.Red
};

textControl1.Tables[1].Cells[2,2].Name =
JsonConvert.SerializeObject(cellFilterInstructions);

MailMerge mailMerge = new MailMerge();
mailMerge.TextComponent = textControl1;
mailMerge.FieldMerged += MailMerge_FieldMerged;

string jsonData = File.ReadAllText("data.json");
mailMerge.MergeJsonData(jsonData);

在FieldMerged事件中，此規則被放棄并評估。然后，返回的顏色將應用于表格單元格的表格單元格格式。

private void MailMerge_FieldMerged(object sender, MailMerge.FieldMergedEventArgs e)
{
// custom field handling
if (e.TableCell == null)
return;

if (e.TableCell.Name != "")
{
CellFilterInstructions instructions =
(CellFilterInstructions)JsonConvert.DeserializeObject(
e.TableCell.Name,
typeof(CellFilterInstructions));

// retrieve the color
Color? color = instructions.GetColor(e.MailMergeFieldAdapter.ApplicationField.Text);

// apply the color
if (color != null)
e.TableCell.CellFormat.BackColor = (Color)color;
}
}

以下屏幕截圖顯示了此合并過程的結果：

結論

TX Text Control 中的 MailMerge 類為自動化文檔生成過程提供了強大而靈活的解決方案。使用合并塊和代碼級操作，開發人員可以輕松創建動態、數據驅動的文檔。FieldMerged 事件對合并過程提供了細粒度的控制，允許開發人員根據特定條件自定義輸出。這種級別的控制對于需要精確處理數據和內容的復雜文檔生成場景至關重要。

歡迎下載|體驗更多TX Text Control產品