Delphi 2009 TCategoryPanelGroup 入門：ChevronAlignment、CollapseAll/ExpandAll 與 Collapsed 屬性實戰

TCategoryPanelGroup 快速上手指南

TCategoryPanelGroup 是 Delphi 2009 強化的可摺疊面板容器，支援分組管理多個 TCategoryPanel。本文從建立流程、核心屬性/方法到實戰程式碼，完整解析入門必備知識。

設計期建立流程

1. 從工具箱拖放 TCategoryPanelGroup 到表單
2. 右鍵點擊 Group → New Panel，重複 3 次建立 3 個面板
3. 設定各面板 Caption 屬性 (如 'CPanel1'、'CPanel2'、'CPanel3')
4. 調整面板 Height 適應內容

核心屬性與方法速查

完整實作程式碼

uses ExtCtrls, TypInfo;

const
  BoolArr: array[Boolean] of string = ('關閉 CPanel1', '展開 CPanel1');

procedure TForm1.FormCreate(Sender: TObject);
var i: Integer;
begin
  // 初始化面板高度
  CategoryPanel1.Height := ClientHeight div 2;
  CategoryPanel2.Height := CategoryPanel1.Height;
  CategoryPanel3.Height := CategoryPanel1.Height;
  CategoryPanel1.Caption := 'CPanel1';
  CategoryPanel2.Caption := 'CPanel2';
  CategoryPanel3.Caption := 'CPanel3';

  // 統一按鈕事件
  Button1.Tag := 1; // 全部關閉
  Button2.Tag := 2; // 全部展開
  Button3.Tag := 3; // 切換 CPanel1
  Button2.OnClick := Button1.OnClick;
  Button3.OnClick := Button1.OnClick;

  Button1.Caption := '全部關閉';
  Button2.Caption := '全部展開';
  Button2.Click; // 預設展開所有

  // ChevronAlignment RadioGroup
  RadioGroup1.Caption := 'ChevronAlignment';
  for i := 0 to 2 do
    RadioGroup1.Items.Add(GetEnumName(TypeInfo(TAlignment), i));
  RadioGroup1.ItemIndex := 0;
end;

procedure TForm1.RadioGroup1Click(Sender: TObject);
begin
  CategoryPanelGroup1.ChevronAlignment := TAlignment(RadioGroup1.ItemIndex);
end;

procedure TForm1.Button1Click(Sender: TObject);
begin
  case TButton(Sender).Tag of
    1: CategoryPanelGroup1.CollapseAll; // 群組方法：全部摺疊
    2: CategoryPanelGroup1.ExpandAll;   // 群組方法：全部展開
    3: CategoryPanel1.Collapsed := not CategoryPanel1.Collapsed; // 單一面板屬性切換
  end;
  // 更新切換按鈕文字
  Button3.Caption := BoolArr[CategoryPanel1.Collapsed];
end;

行為深度解析

1. ChevronAlignment：箭號位置控制

2. CollapseAll / ExpandAll：群組批量操作

• 遍歷群組內所有面板，設定 Collapsed := True/False
• 觸發各面板 OnCollapse/OnExpand 事件
• 自動調整捲軸範圍 (VertScrollBar.Range)
• 效能：O(n)，n 為面板數量

3. Panel.Collapsed：單一面板狀態控制

// 切換摺疊狀態
CategoryPanel1.Collapsed := not CategoryPanel1.Collapsed;

// 事件回應
procedure TForm1.CategoryPanel1Collapse(Sender: TObject);
begin
  // 面板剛摺疊時執行
  // 可釋放面板內重資源控制項、暫停計時器等
end;

procedure TForm1.CategoryPanel1Expand(Sender: TObject);
begin
  // 面板剛展開時執行
  // 可重建資源、恢復計時器、載入資料
end;

進階實戰技巧

1. 記住使用者摺疊偏好 (持久化)

uses IniFiles;

procedure TForm1.SavePanelStates(Ini: TIniFile);
var i: Integer;
begin
  for i := 0 to CategoryPanelGroup1.Panels.Count - 1 do
    Ini.WriteBool('Panels', 'Panel' + IntToStr(i) + '_Collapsed',
      CategoryPanelGroup1.Panels[i].Collapsed);
end;

procedure TForm1.LoadPanelStates(Ini: TIniFile);
var i: Integer;
begin
  for i := 0 to CategoryPanelGroup1.Panels.Count - 1 do
    CategoryPanelGroup1.Panels[i].Collapsed :=
      Ini.ReadBool('Panels', 'Panel' + IntToStr(i) + '_Collapsed', False);
end;

2. 單一展開模式 (Accordion 效果)

procedure TForm1.CategoryPanelGroup1Expand(Sender: TObject);
var
  Panel: TCategoryPanel;
  i: Integer;
begin
  Panel := Sender as TCategoryPanel;
  // 摺疊其他面板
  for i := 0 to CategoryPanelGroup1.Panels.Count - 1 do
    if CategoryPanelGroup1.Panels[i] <> Panel then
      CategoryPanelGroup1.Panels[i].Collapsed := True;
end;
// 需在設計期為每個面板設定 OnExpand 事件指向此處理程序

3. 動態建立面板

function TForm1.AddCategoryPanel(const Caption: string; Height: Integer): TCategoryPanel;
begin
  Result := TCategoryPanel.Create(CategoryPanelGroup1);
  Result.Parent := CategoryPanelGroup1;
  Result.Caption := Caption;
  Result.Height := Height;
  Result.OnExpand := CategoryPanelGroup1Expand; // 掛載手風琴邏輯
  Result.OnCollapse := CategoryPanel1Collapse;
end;

// 使用
var newPanel := AddCategoryPanel('動態面板', 200);

4. 面板內容區塊控制項自動佈局

procedure TForm1.SetupPanelContent(Panel: TCategoryPanel; Content: TControl);
begin
  Content.Parent := Panel;
  Content.Align := alClient;
  Content.Anchors := [akLeft, akTop, akRight, akBottom];
  // 面板 Height 應 ≥ HeaderHeight + Content.Height + Padding
  Panel.Height := CategoryPanelGroup1.HeaderHeight + Content.Height + 20;
end;

常見問題與避坑指南

視覺狀態機圖解

用戶點擊 Chevron/標題
       ↓
Panel.Collapsed 切換 (True ↔ False)
       ↓
觸發 OnCollapse / OnExpand 事件
       ↓
面板高度變化: 展開=Height, 摺疊=HeaderHeight
       ↓
群組 VertScrollBar.Range 自動重算
       ↓
介面重繪完成

總結

TCategoryPanelGroup 以 ChevronAlignment 控制視覺錨點，CollapseAll/ExpandAll 提供群組批量操作，Panel.Collapsed 實現單一面板精細控制。掌握建立流程、狀態切換邏輯、事件回應機制、持久化偏好、手風琴模式五大核心技巧，即能快速構建專業的分組摺疊介面。