如何使用 IronXL 在 C# 中將資料匯出至現有的 Excel 範本

為什麼Excel範本可以提高報表產生效率？

與從頭開始建立電子表格相比，Excel 範本具有顯著優勢。 範本可以保持專業的格式、複雜的公式、條件格式規則以及貴組織已經批准的經過驗證的資料結構。 財務團隊、營運部門和合規部門通常都有標準化的發票、儀表板和監管文件模板，這些模板必須在保留其設計的同時，整合來自資料庫、API 或記憶體集合的新資料。

透過以程式設計方式填入現有模板，您可以節省數小時的格式化工作，並確保每個產生的文件的一致性。 IronXL支援 XLSX、XLS、XLSM 和 XLTX 格式，無需安裝 Office，因此適用於伺服器環境、Docker 容器和雲端管道等不方便或無法安裝 Microsoft Office 的環境。

基於模板的方法的主要優點：

-公式保留－資料寫入後，現有的 SUM、AVERAGE 和查找公式會自動重新計算。 -樣式保留－字體、邊框、儲存格顏色和數字格式均與設計完全一致。 -條件格式設定－與儲存格區域關聯的規則會根據新的資料值繼續觸發 -完全不依賴 Office -- IronXL完全使用託管的.NET程式碼讀取和寫入 Excel 文件 -跨平台支援－可在 Windows、Linux 和 macOS 上運行，包括.NET 10 環境

如何在專案中安裝IronXL ？

首先透過NuGet安裝IronXL 。 開啟軟體包管理器控制台並執行：

Install-Package IronXL

Install-Package IronXL

或使用.NET CLI：

dotnet add package IronXL

dotnet add package IronXL

IronXL無需安裝 Microsoft Office 即可獨立運行，因此非常適合伺服器環境和跨平台應用程式。 有關詳細的設定說明，請造訪IronXL入門指南。 此程式庫面向.NET Framework、 .NET Core和.NET 5 至.NET 10，可在 Windows、Linux 和 macOS 上運作。

安裝完成後，在檔案頂部新增命名空間：

using IronXL;

using IronXL;

如何載入和填入現有的Excel模板？

使用 IronXL 的WorkBook.Load()方法載入現有模板非常簡單。 以下範例開啟季度銷售報告模板，並使用頂級語句向特定單元格填充資料：

using IronXL;

// Load the existing Excel template
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Write header values to named cells
sheet["B2"].Value = "Q4 2025 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;

// Add a profit formula -- Excel recalculates automatically
sheet["C8"].Formula = "=C6-C7";

// Populate a column range with monthly data
decimal[] monthlyData = { 10500, 12300, 15600, 11200 };
for (int i = 0; i < monthlyData.Length; i++)
{
    sheet[$"E{10 + i}"].DecimalValue = monthlyData[i];
}

// Save the populated file
workbook.SaveAs("Q4_Sales_Report.xlsx");

using IronXL;

// Load the existing Excel template
WorkBook workbook = WorkBook.Load("ReportTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Write header values to named cells
sheet["B2"].Value = "Q4 2025 Sales Report";
sheet["C4"].StringValue = DateTime.Now.ToString("MMMM dd, yyyy");
sheet["C6"].DecimalValue = 125000.50m;
sheet["C7"].DecimalValue = 98500.75m;

// Add a profit formula -- Excel recalculates automatically
sheet["C8"].Formula = "=C6-C7";

// Populate a column range with monthly data
decimal[] monthlyData = { 10500, 12300, 15600, 11200 };
for (int i = 0; i < monthlyData.Length; i++)
{
    sheet[$"E{10 + i}"].DecimalValue = monthlyData[i];
}

// Save the populated file
workbook.SaveAs("Q4_Sales_Report.xlsx");

這段程式碼載入一個預先設計的模板，保留所有現有格式，並填入指定的儲存格。 DecimalValue屬性確保數值資料保留正確的貨幣或小數格式。 當相鄰資料發生變化時，公式儲存格會自動重新計算，因此範本的計算邏輯保持不變。

有關使用 Excel 儲存格參考和區域的指導，請參閱IronXL儲存格和區域文件。 您也可以使用IronXL範例頁面來探索其他模式。

如何在模板中替換佔位標記？

許多範本使用佔位符文字標記(例如 {{CustomerName}} 或 {{InvoiceDate}})，這些標記需要替換為實際的執行時間值。 IronXL透過在定義的範圍內進行儲存格迭代來處理這種情況。 這種模式對於產生發票、填寫合約和建立個人化報告尤其有用：

using IronXL;

// Load an invoice template containing placeholder markers
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Iterate over a range and replace placeholder text
foreach (var cell in sheet["A1:H50"])
{
    if (cell.Text.Contains("{{CustomerName}}"))
        cell.Value = cell.Text.Replace("{{CustomerName}}", "Acme Corporation");

    if (cell.Text.Contains("{{InvoiceDate}}"))
        cell.Value = cell.Text.Replace("{{InvoiceDate}}", DateTime.Now.ToShortDateString());

    if (cell.Text.Contains("{{InvoiceNumber}}"))
        cell.Value = cell.Text.Replace("{{InvoiceNumber}}", "INV-2025-001");
}

// Append line items starting at row 15
var items = new[]
{
    new { Description = "Software License", Qty = 5, Price = 299.99 },
    new { Description = "Support Package",  Qty = 1, Price = 999.99 }
};

int startRow = 15;
foreach (var item in items)
{
    sheet[$"B{startRow}"].Value      = item.Description;
    sheet[$"E{startRow}"].IntValue   = item.Qty;
    sheet[$"F{startRow}"].DoubleValue = item.Price;
    sheet[$"G{startRow}"].Formula    = $"=E{startRow}*F{startRow}";
    startRow++;
}

workbook.SaveAs("GeneratedInvoice.xlsx");

using IronXL;

// Load an invoice template containing placeholder markers
WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

// Iterate over a range and replace placeholder text
foreach (var cell in sheet["A1:H50"])
{
    if (cell.Text.Contains("{{CustomerName}}"))
        cell.Value = cell.Text.Replace("{{CustomerName}}", "Acme Corporation");

    if (cell.Text.Contains("{{InvoiceDate}}"))
        cell.Value = cell.Text.Replace("{{InvoiceDate}}", DateTime.Now.ToShortDateString());

    if (cell.Text.Contains("{{InvoiceNumber}}"))
        cell.Value = cell.Text.Replace("{{InvoiceNumber}}", "INV-2025-001");
}

// Append line items starting at row 15
var items = new[]
{
    new { Description = "Software License", Qty = 5, Price = 299.99 },
    new { Description = "Support Package",  Qty = 1, Price = 999.99 }
};

int startRow = 15;
foreach (var item in items)
{
    sheet[$"B{startRow}"].Value      = item.Description;
    sheet[$"E{startRow}"].IntValue   = item.Qty;
    sheet[$"F{startRow}"].DoubleValue = item.Price;
    sheet[$"G{startRow}"].Formula    = $"=E{startRow}*F{startRow}";
    startRow++;
}

workbook.SaveAs("GeneratedInvoice.xlsx");

此方法在定義的儲存格範圍內搜尋標記，並將其替換為實際值。 模板的格式(字體、顏色、邊框和數字格式)始終保持不變。 如需在執行時間進行更進階的樣式更改，請參閱IronXL儲存格樣式指南，其中涵蓋背景顏色、字體屬性和邊框樣式。

using IronXL;

WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

var replacements = new Dictionary<string, string>
{
    { "{{CustomerName}}", "Acme Corporation" },
    { "{{InvoiceDate}}", DateTime.Now.ToShortDateString() },
    { "{{InvoiceNumber}}", "INV-2025-002" }
};

foreach (var cell in sheet["A1:H50"])
{
    if (string.IsNullOrEmpty(cell.Text)) continue;

    foreach (var replacement in replacements)
    {
        if (cell.Text.Contains(replacement.Key))
            cell.Value = cell.Text.Replace(replacement.Key, replacement.Value);
    }
}

workbook.SaveAs("GeneratedInvoice_Safe.xlsx");

using IronXL;

WorkBook workbook = WorkBook.Load("InvoiceTemplate.xlsx");
WorkSheet sheet = workbook.DefaultWorkSheet;

var replacements = new Dictionary<string, string>
{
    { "{{CustomerName}}", "Acme Corporation" },
    { "{{InvoiceDate}}", DateTime.Now.ToShortDateString() },
    { "{{InvoiceNumber}}", "INV-2025-002" }
};

foreach (var cell in sheet["A1:H50"])
{
    if (string.IsNullOrEmpty(cell.Text)) continue;

    foreach (var replacement in replacements)
    {
        if (cell.Text.Contains(replacement.Key))
            cell.Value = cell.Text.Replace(replacement.Key, replacement.Value);
    }
}

workbook.SaveAs("GeneratedInvoice_Safe.xlsx");

如何根據範本產生月度報告？

以下是一個實際範例，它使用包含預先格式化儲存格、圖表和百分比公式的現有 Excel 範本來產生每月銷售報告。 程式碼使用頂級語句，並接受一個產品到銷售映射的字典：

using IronXL;

// Load the monthly report template
WorkBook workbook = WorkBook.Load("MonthlyReportTemplate.xlsx");
WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");

// Build sample sales data
var salesData = new Dictionary<string, decimal>
{
    { "Product A", 42500.00m },
    { "Product B", 31750.50m },
    { "Product C", 18300.25m }
};

// Write report header
sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
sheet["B3"].Value = $"Generated: {DateTime.Now:g}";

// Write each product row starting at row 6
int currentRow = 6;
decimal totalSales = salesData.Values.Sum();

foreach (var sale in salesData)
{
    sheet[$"B{currentRow}"].Value = sale.Key;
    sheet[$"C{currentRow}"].DecimalValue = sale.Value;
    // Percentage of total formula
    sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C{currentRow + salesData.Count}*100";
    currentRow++;
}

// Write the total row and apply bold style
sheet[$"C{currentRow}"].DecimalValue = totalSales;
sheet[$"C{currentRow}"].Style.Font.Bold = true;

// Save with a date-stamped filename
string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
workbook.SaveAs(outputPath);

using IronXL;

// Load the monthly report template
WorkBook workbook = WorkBook.Load("MonthlyReportTemplate.xlsx");
WorkSheet sheet = workbook.GetWorkSheet("Monthly Report");

// Build sample sales data
var salesData = new Dictionary<string, decimal>
{
    { "Product A", 42500.00m },
    { "Product B", 31750.50m },
    { "Product C", 18300.25m }
};

// Write report header
sheet["B2"].Value = $"Sales Report - {DateTime.Now:MMMM yyyy}";
sheet["B3"].Value = $"Generated: {DateTime.Now:g}";

// Write each product row starting at row 6
int currentRow = 6;
decimal totalSales = salesData.Values.Sum();

foreach (var sale in salesData)
{
    sheet[$"B{currentRow}"].Value = sale.Key;
    sheet[$"C{currentRow}"].DecimalValue = sale.Value;
    // Percentage of total formula
    sheet[$"D{currentRow}"].Formula = $"=C{currentRow}/C{currentRow + salesData.Count}*100";
    currentRow++;
}

// Write the total row and apply bold style
sheet[$"C{currentRow}"].DecimalValue = totalSales;
sheet[$"C{currentRow}"].Style.Font.Bold = true;

// Save with a date-stamped filename
string outputPath = $"Reports/Monthly_Report_{DateTime.Now:yyyyMMdd}.xlsx";
workbook.SaveAs(outputPath);

此方法填入標準化模板，自動計算貢獻百分比，並保持模板的專業外觀。 範本中現有的圖表會根據新的資料值進行更新，因為它們的來源範圍保持不變。

從 DataTable 或 DataSet 傳輸資料時，保留列名並將第一行視為標題。 有關從 DataTable 物件匯入的更多信息，請參閱IronXL DataTable 文件。

如何排查常見的模板錯誤？

使用模板時，經常會出現一些問題。 下表列出了每種症狀及其病因和解決方法：

對於受密碼保護的文件，請將密碼作為第二個參數提供給 WorkBook.Load。 如果在寫入資料後公式沒有更新，請在呼叫 workbook.SaveAs() 之前呼叫 sheet.Calculate()。 對於大型資料集，儲存後應釋放工作簿對象，以便及時釋放託管記憶體和非託管記憶體。

其他故障排除資源可在IronXL故障排除文件和IronXL API 參考中找到。

IronXL還支援哪些其他 Excel 操作？

除了模板填充之外， IronXL還提供了一系列廣泛的 Excel 操作功能，可補充上述工作流程：

-讀取 Excel 檔案－將現有工作簿中的資料提取到 C# 物件、清單或資料表中 -從頭開始建立 Excel 檔案－在需要完全佈局控制時，無需範本即可產生新的工作簿。 -將資料表匯出到 Excel -- 將.NET資料表物件直接轉換為工作表行 -套用儲存格樣式－以程式設定背景顏色、字型粗細、邊框和數字格式 -熟練運用Excel公式－寫出和計算公式字串，包括SUM、VLOOKUP和條件式 -合併儲存格-- 合併和取消合併表頭和報表版面配置的儲存格區域 -保護工作表－鎖定儲存格或工作表，以防止意外編輯範本結構 -轉換為 PDF -- 無需使用 Excel，即可將填入的範本直接渲染成 PDF 檔案進行分發。 -匯出為 CSV 檔案-- 將工作表資料儲存為逗號分隔值，以便進行後續處理

這些功能與模板填充功能整合在一起，因此單一工作流程可以一次載入模板、填充模板、保護敏感公式單元格並匯出 XLSX 副本和 PDF 版本。

IronXL也與其他資料交換格式（如 XML）很好地集成，讓您可以匯入結構化資料、轉換資料並將結果匯出到模板中。 有關資料庫驅動報表產生的更高級集成，請參閱IronXL部落格上的社群教學。

如何在生產環境中開始使用IronXL ？

IronXL可免費用於開發和測試。 準備部署時，您可以從靈活的授權選項中進行選擇，這些選項涵蓋個人開發人員、團隊和 OEM 再分發。 造訪IronXL授權頁面，找到適合您專案的選項。

立即開始，探索免費試用版下載，並將本教學中的程式碼範例套用至您自己的範本。 IronXL NuGet頁面提供版本歷史記錄和軟體包詳細資訊。 社群討論和更多範例可在Iron Software GitHub儲存庫中找到。 有關 XLSX 檔案所基於的 Open XML 檔案格式的背景信息，請參閱ECMA-376 規格概述。

對於正在評估IronXL和其他替代方案的組織而言， IronXL比較指南涵蓋了功能差異、授權模式和效能基準，以幫助您做出明智的決定。