C# WinForms 主從清單框架 BaseTreeListForm：樹狀分類、分頁、導入導出、報表整合完整架構

設計定位

BaseTreeListForm 是 WinForms 業務模組的「主視窗」基類，整合：

• 左側樹狀分類（支援多層、延遲載入）。
• 右側資料清單（TreeList/Grid，支援分頁、排序、多選）。
• 工具列：新增/修改/刪除/查詢/導入/導出/列印。
• 雙擊回傳實體（供選擇器模式）。

核心屬性開關

關鍵虛擬方法（分類與資料雙軌）

public abstract class BaseTreeListForm : Form
{
    // 分類樹
    protected abstract IList BuildTypes(int parentId); // 遞迴建構

    // 資料清單
    protected abstract IList BuildLists(bool isFull);  // isFull=true 列印/導出時載入全部

    // 選中節點實體
    protected abstract BaseModel GetSelectedType(Node node);
    protected abstract BaseModel GetSelectedInfo(Node node);

    // CRUD
    protected virtual BaseModel AddInfo() => null;
    protected virtual bool ModifyInfo(BaseModel source) => false;
    protected virtual bool ConfirmDelete(params string[] ids) => false;
    protected virtual bool ConfirmDeleteType(params string[] ids) => false;

    // 導入/導出/列印
    protected virtual void ExportInfo() { }
    protected virtual void PrintInfo() { }
    protected virtual void ImportInfo() { }
    protected virtual DataHelper CreateDataHelper() => null; // 導入需自訂連線
}

分類樹建構範例

protected override IList BuildTypes(int parentId)
{
    var qb = new QueryBuilder();
    qb.Append(QueryRelation.And, QueryCompare.Equal, "ParentId", parentId);
    qb.Append(QueryRelation.And, QueryCompare.Equal, "BaseType", (int)BaseType.Company);
    return new CompanyTypeDAL().Select(qb, "Sort DESC", null);
}

資料清單建構（含分頁、查詢條件、樹狀模式）

protected override IList BuildLists(bool isFull)
{
    var qb = new QueryBuilder();
    qb.Append(QueryRelation.And, QueryCompare.Equal, "IsDelete", 0);
    qb.Append(QueryRelation.And, QueryCompare.Equal, "CompanyId", AppContext.CurrentCompanyId);

    // 查詢視窗傳入的條件
    qb += QueryArgs.QueryBuilder;

    // 樹狀模式：依父節點過濾
    if (AllowTreeList)
        qb.Append(QueryRelation.And, QueryCompare.Equal, "ParentId", QueryArgs.ParentId);

    var dal = new CompanyDAL();
    if (!isFull) dal.PageArgs = PageArgs; // 分頁
    var list = dal.Select(qb, QueryArgs.Order, GetInfoFields());
    if (!isFull) PageArgs = dal.PageArgs; // 回寫總筆數
    return list;
}

欄位配置檔 (*.cls) 驅動右側清單

<Columns>
  <Column><Key>Code</Key><Text>編碼</Text><Width>100</Width><Align>Left</Align><Visible>true</Visible></Column>
  <Column><Key>Name</Key><Text>名稱</Text><Width>200</Width><Align>Left</Align><Visible>true</Visible></Column>
  <Column><Key>TypeName</Key><Text>類別</Text><Width>120</Width><Align>Left</Align><Visible>true</Visible></Column>
  <Column><Key>Contact</Key><Text>聯絡人</Text><Width>100</Width><Align>Left</Align></Column>
  <Column><Key>Phone</Key><Text>電話</Text><Width>120</Width><Align>Left</Align></Column>
  <Column><Key>Id</Key><Visible>false</Visible></Column> <!-- 隱藏主鍵 -->
</Columns>

導入配置檔 (*.ips) 實現 Excel 匯入

<ImportConfig>
  <TableName>TCompany</TableName>
  <Columns>
    <Column><Name>公司編碼</Name><Key>Code</Key><Primary>true</Primary></Column>
    <Column><Name>公司名稱</Name><Key>Name</Key></Column>
    <Column><Name>類別</Name><Key>CompanyTypeId</Key>
      <Reference>CompanyType</Reference>
      <ConvertFrom>TCompanyType.Name</ConvertFrom>
      <ConvertTo>TCompanyType.Id</ConvertTo>
    </Column>
    <Column><Name>聯絡人</Name><Key>Contact</Key></Column>
    <Column><Name>電話</Name><Key>Phone</Key></Column>
    <Column><Name>標籤</Name><Key>Tags</Key><Type>Binary</Type>
      <ConvertFrom>TTag.Name</ConvertFrom>
      <ConvertTo>TTag.Id</ConvertTo>
      <Sample>VIP,優質,潛在(半形逗號分隔)</Sample>
    </Column>
  </Columns>
</ImportConfig>

報表配置檔 (*.rps) 整合 BaseReportForm

同 BaseReportForm 章節，於 Config 目錄建立 FormClassName.rps 即可啟用列印/預覽功能。

實例化範例

public class CompanyManageForm : BaseTreeListForm
{
    public CompanyManageForm()
    {
        EditFormType = typeof(CompanyEditForm);
        TypeEditFormType = typeof(CompanyTypeEditForm);
        QueryFormType = typeof(CompanyQueryForm);
        TypeRootName = "所有分類";
        TypeNameField = "Name";
        ChildCountField = "ChildCount";
    }

    protected override IList BuildTypes(int parentId) { /* ... */ }
    protected override IList BuildLists(bool isFull) { /* ... */ }
    protected override BaseModel GetSelectedType(Node n) => new CompanyTypeDAL().Get(n.Tag);
    protected override BaseModel GetSelectedInfo(Node n) => new CompanyDAL().Get(n.Tag);
    protected override bool ConfirmDelete(params string[] ids) { /* 軟刪除 UPDATE IsDelete=1 */ }
}

總結

BaseTreeListForm 以 屬性開關控制功能 + 虛擬方法定義契約 + XML 配置驅動 UI/導入/報表 構建企業級主視窗標準框架。新增模組只需：繼承基類、設定屬性、實作 6~8 個虛擬方法、建立 3~4 個 XML 配置檔。將重複的分頁、查詢、CRUD、導入導出、列印邏輯下沉框架層，業務層專注於 SQL 與實體映射，開發效率與一致性大幅提升。