Skip to content

開始使用 Excely

Jump to bottom
Max Zheng edited this page Jan 15, 2024 · 30 revisions

安裝

此套件目前為搶鮮版

若您僅使用 CSV 相關功能，請執行以下指令以下載 Excely 本體：

dotnet add package Excely --version 0.1.0-alpha

若您想要使用 Excel 相關功能，請根據您偏好的依賴套件選擇對應的版本：

EPPlus

dotnet add package Excely.LGPL.EPPlus --version 0.1.0-alpha

ClosedXML

dotnet add package Excely.ClosedXML --version 0.1.0-alpha

開始使用

以下以 EPPlus.LGPL 依賴版本，進行 Excel 匯入、匯出的示範。

匯出

以下的範例展示了如何從 List 匯出為 Excel：

// usings
using Excely.Workflows;
using Excely.ClosedXML.Workflows;

// 創建物件列表
var students = new List<Student>()
{
    new Student(id: 0, name: "Test1", birthday: DateTime.Now),
    new Student(id: 1, name: "Test2", birthday: DateTime.Now),
};

// 建立匯出 List<Student> 的 exporter
var exporter = ExcelyExporter.FromClassList<Student>();

// 匯出為 Excel
using var excel = exporter.ToExcel(students);

可以看到我們首先呼叫靜態類別 ExcelyExporter 中的 FromClassList<T> 方法， 來創造一個可以輸入 List<T> 的 exporter。

ExcelyExporter 可以幫助您創建各種輸入版本的 exporter， 例如 FromDictionaryList 可以創建接受字典輸入的 exporter。

FromClassList<T> 有兩個參數可以輸入：

  • options - 此參數讓您可以自定義匯出流程的邏輯，詳細的使用方式請參考(尚未編寫)。
  • shaders - 此參數讓您在匯出後，能使用 shader 來依序調整匯出結果。關於 shader 的用法，請參考美化匯出結果。

ToExcel 則可以輸入以下參數：

  • sourceData - 匯入資料來源。
  • worksheetName - 匯出時創建的工作表名稱。
  • startCell - 開始匯出的座標(不填入則為最右上角)。

ToExcel 實際上是 ToWorksheet 的包裝，若您已經有想匯出的目標 excel 實例，請考慮改用 ToWorksheet。

匯入

以下的範例展示了如何從 worksheet 匯入為 List：

// 接續匯出章節匯出的檔案
var worksheet = excel.Workbook.Worksheets.First();

// 建立接受 worksheet 的 importer
var importer = new XlsxImporter();

// 匯入為 IEnumerable<Student>
var importResult = importer.ToClassList<Student>(worksheet);

與匯出時不同，這裡我們不是呼叫靜態類別來產生 importer，而是直接建立一個特定的 importer 物件， 這是因為匯入來源通常都是由套件依賴版本(如本例中的 Excely.EPPlus.LGPL)提供。

此處的 new XlsxImporter() 建構子可以輸入兩種參數：

  • startCell - 代表開始讀取來源的座標。若不填則從 worksheet 的最左上角開始讀取。
  • endCell - 代表強制結束讀取的座標，只會讀取 startCell 到 endCell 間的內容。若不填則不設限。

ToClassList 則可以輸入來源資料及自定義的轉換邏輯(可選)。

關於 option 參數的詳細使用方式請參考自訂轉換邏輯。

自訂轉換邏輯

自訂匯出邏輯

接續上面的例子，若我們想使 Student.Birthday 以字串形式(yyyy-MM-dd)匯出， 則需要使用 FromClassList<T> 的 option 參數， options 參數接受一個 ClassListTableFactoryOptions<T> 型別的物件，

以下是 ClassListTableFactoryOptions<T> 可以設定的幾個 Property：

  • WithSchema: 決定匯出時是否帶有表頭。
  • PropertyShowPolicy: 決定 Property 是否應作為欄位匯出。
  • PropertyNamePolicy: 決定 Property 作為欄位時的名稱。
  • PropertyOrderPolicy: 決定 Property 作為欄位時的順序。
  • CustomValuePolicy: 決定資料寫入欄位時的值。

此處我們先展示以 CustomValuePolicy 來使 Student.Birthday 以字串形式(yyyy-MM-dd)匯出的寫法：

// 延續前一章節的匯出範例...

// 建立自訂轉換邏輯
var exportOptions = new ClassListTableFactoryOptions<Student>
{
    CustomValuePolicy = (property, obj) => property.Name switch
    {
        nameof(Student.Birthday) => obj.Birthday?.ToString("yyyy-MM-dd"),
        _ => property.GetValue(obj)
    }
};

// 建立匯出 List<Student> 的 exporter
var exporter = ExcelyExporter.FromClassList<Student>(options: exportOptions);

// 匯出為 Excel
using var excel = exporter.ToExcel(students);

CustomValuePolicy 是一個由 ClassListTableFactoryOptions 定義好的委派， 其第一個參數代表當前正在處理的 Property， 第二個參數為當前正在處理的來源物件(要匯出的物件)。 在上面的範例中，我們設定了將資料寫入至 Excel 欄位時的轉換邏輯， 當處理 Student.Birthday 欄位時，將寫入的值改為 yyyy-MM-dd 形式的字串，其餘欄位則維持原值。

ClassListTableFactoryOptions 的其他自定義參數使用方式請參考(尚未編寫)。

自訂匯入邏輯

接續上一章節，若我們想將帶有匯出為 yyyy-MM-dd 形式的 Excel 匯入回 IEnumerable， 則需要使用 ToClassList<T> 的 options 參數， 其接受一個 ClassListTableConverterOptions<T> 型別的物件。

以下是 ClassListTableConverterOptions<T> 可以設定的幾個 Property：

  • WithSchema: 匯入的 Table 是否含有表頭。
  • ThrowWhenError: 當轉換發生錯誤時是否立刻擲出異常。
  • EnableAutoTypeConversion: 當寫入的值與目標型別不同時，是否自動嘗試轉換。
  • PropertyNamePolicy: 當 WithSchema 為 true 時，決定 Property 作為欄位時的名稱。
  • PropertyIndexPolicy: 當 WithSchema 為 false 時，取得 Property 出現在表頭時的位置。
  • PropertyValueSettingPolicy: 決定將值寫入至 Property 時應寫入的值。
  • ErrorHandlingPolicy: 將值輸入進物件發生錯誤時，決定錯誤處理方式。

為了使 yyyy-MM-dd 形式的字串轉換回 DateTime 形式， 我們需要設定 PropertyValueSettingPolicy 如下：

// 延續前一章節的匯入範例...

// 建立自訂轉換邏輯
var importOptions = new ClassListTableConverterOptions<Student>
{
    PropertyValueSettingPolicy = (property, originalValue) => property.Name switch
    {
        nameof(Student.Birthday) => originalValue != null ? DateTime.Parse(originalValue.ToString()) : null,
        _ => originalValue
    }
};

// 建立接受 worksheet 的 importer
var importer = new XlsxImporter();

// 匯入為 IEnumerable<Student>
var importResult = importer.ToClassList<Student>(worksheet, options: importOptions);

PropertyValueSettingPolicy 是一個由 ClassListTableConverterOptions 定義好的委派， 其第一個參數代表當前正在處理的 Property， 第二個參數為從資料來源讀取到的值。 在上面的範例中，我們設定了讀取 Excel 內容時的轉換邏輯， 當處理 Student.Birthday 欄位時，將讀取到的 yyyy-MM-dd 形式字串轉換為 DateTime，其餘欄位則維持原值。

順帶再介紹 ClassListTableConverterOptions 另一個參數 EnableAutoTypeConversion， 當此參數為 true 時，會自動嘗試將來源值轉型為目標型別， 其轉換方式是先嘗試使用 TypeConverter，若該型別沒有對應的 TypeConverter， 或是 TypeConverter 轉換失敗時，則嘗試使用強制轉型。 有了這個方便的參數，其實不需要大費周章的自行撰寫 format string 到 DateTime 的轉換。

自動轉型的過程效率較低，當需要轉型的欄位較多或追求效能表現時，請考慮停用自動轉型，並自己撰寫對應邏輯。

ClassListTableConverterOptions 的其他自定義參數使用方式請參考(尚未編寫)。

美化匯出結果

目前為止，我們匯出的 Excel 都沒有做任何外觀上的調整。 為了增強使用者體驗，你可能會想為匯出資料加上主題色彩、表頭篩選或自適應欄位寬度等等， 這時你可以使用 Shader 功能來輕鬆完成設定。

根據不同的匯出目標(如Excel、CSV)以及不同的版本依賴，可能會有不同的可用 Shader， 這裡我們以美化 Excel 來舉例。

EPPlus.LGPL 依賴版本中目前有以下 Shader 可供選擇：

  • CellFittingShader: 欄位大小自適應
  • SchemaFilterShader: 啟用表頭篩選
  • TableThemeShader: 表格色彩美化
  • ErrorMarkShader: 在指定欄位標註備註，並使其文字色彩為紅色

更多支援的 Shader 請參考(尚未編寫)

所有 Shader 的基本使用方式都相同，只需要建立實例，並呼叫 Excute 函式：

// 延續匯出範例...
using var excel = exporter.ToExcel(students);
var worksheet = excel.Workbook.Worksheets.First();

// 建立 Shader
var cellFittingShader = new CellFittingShader();
// 執行 Shader
cellFittingShader.Excute(worksheet);

除了這種使用方式，也可以使用 FromClassList<T> 的 shaders 參數， 一次傳入一整組 Shader，並在匯出後自動執行：

// 以匯出範例做修改...

// 建立匯出 List<Student> 的 exporter
var exporter = ExcelyExporter.FromClassList<Student>(
    options: exportOptions,
    shaders: new IShader[]
    {
        new CellFittingShader(),
        new SchemaFilterShader(),
    });
Clone this wiki locally