TCondFormat / TCondFormatRule 及 CF12 規格類別
單元： lxCondFormat
支援 Excel 2007+ 延伸規則的 BIFF8（.xls）條件格式家族。TXLSWorksheet 會維護 TCondFormat 項目集合；每個項目涵蓋一個或多個儲存格範圍，並保有一組有序的 TCondFormatRule 物件，而每個規則不是傳統的儲存格值規則，就是 CF12 資料條 / 色階 / 圖示集規則。四個 Sheet.AddCondFormat* 入口點（DataBar、ColorScale2、ColorScale3、IconSet）會建立正確子型別的規則。自 v2.34.0 起提供
閾值種類列舉
type
TXLSCfValueKind = (
cfvNumber = 0,
cfvMinOfRange = 1,
cfvMaxOfRange = 2,
cfvPercent = 3,
cfvPercentile = 4,
cfvFormula = 5,
cfvAutoMin = 6, // Excel 2010+ data-bar only
cfvAutoMax = 7); // Excel 2010+ data-bar only
圖示集系列列舉
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
17 baseline Excel 2007 icon families. numeric stop count (3, 4, 或 5) 是 encoded 中的 enum 名稱
閾值值 (cfvo)
type
TXLSCfValue = class
constructor Create(AKind: TXLSCfValueKind;
const AValue: WideString; AColor: LongWord);
procedure SetThemeColor(ThemeId: Word; Tint: Single); // v2.43.0+
procedure ClearThemeColor; // v2.43.0+
property Kind: TXLSCfValueKind;
property Value: WideString; // numeric literal or formula text
property Color: LongWord; // BGR RGB for ColorScale stops
property IsThemeColor: Boolean; // v2.43.0+ true = theme mode active
property ThemeColorId: Word; // v2.43.0+ theme palette index
property ThemeColorTint: Single; // v2.43.0+ -1.0 .. 0.0 .. +1.0
end;
資料橫條內容
type
TXLSDataBarSpec = class
procedure SetThemeColor(ThemeId: Word; Tint: Single); // v2.43.0+ — opt bar fill into theme mode
procedure ClearThemeColor; // v2.43.0+ — revert to RGB Color
property Min: TXLSCfValue;
property Max: TXLSCfValue;
property Color: LongWord; // bar fill
property ShowValue: Boolean; // false = hide cell text
property MinLength: Byte; // 0..100 percent
property MaxLength: Byte; // 0..100 percent
property IsThemeColor: Boolean; // v2.43.0+ true = theme mode active
property ThemeColorId: Word; // v2.43.0+ theme palette index
property ThemeColorTint: Single; // v2.43.0+ -1.0 .. 0.0 .. +1.0
end;
XLSX 佈景主題 色彩 往返 (v2.43.0+)
Data Bar 規則的條狀填滿顏色與 Color Scale 規則的各停止點顏色，都可以透過 SetThemeColor(ThemeId, Tint) 搭配活頁簿主題索引與 tint 值設定，而不是固定 RGB。XLSX 寫入器在 Tint 恰好為 0.0 時會輸出 <color theme="N"/>，在非零時則輸出 <color theme="N" tint="0.5"/>，符合 Excel 自己的 "shortest form" 輸出。讀取器會解析這兩種屬性組合，當 theme 與 tint 都不存在時，回退到 RGB rgb= 路徑。每個欄位兩種模式互斥；最後呼叫的 Set 會生效，IsThemeColor 會反映目前啟用的模式以供檢視
BIFF8 CF12 只儲存已解析的 RGB 顏色 — 這個版本中 theme 模式只在 XLSX 後端完整往返。iconSet 規則沒有 <color> 元素，因此這次的 theme 模式新增不會影響它們
色階內容
type
TXLSColorScaleSpec = class
constructor Create(IsThreeStop: Boolean);
procedure SetStop(I: Integer; Kind: TXLSCfValueKind;
const Value: WideString; Color: LongWord);
property StopCount: Integer; // 2 or 3
property Stops[I: Integer]: TXLSCfValue; default;
end;
圖示集內容
type
TXLSIconSetSpec = class
constructor Create(ASetType: TXLSIconSetType);
procedure SetThreshold(I: Integer; Kind: TXLSCfValueKind;
const Value: WideString);
// Per-stop icon override (v2.44.0+).
procedure SetIconOverride(I: Integer;
OverrideSet: TXLSIconSetType; IconId: Byte);
procedure ClearIconOverride(I: Integer);
property SetType: TXLSIconSetType;
property Reverse: Boolean; // reverse the icon order
property ShowOnly: Boolean; // true = icon only, hide cell text
property IconCount: Integer; // 3, 4 or 5 (derived from SetType)
property Thresholds[I: Integer]: TXLSCfValue;
property HasIconOverride[I: Integer]: Boolean; // v2.44.0+
property IconOverrideSet[I: Integer]: TXLSIconSetType; // v2.44.0+
property IconOverrideId[I: Integer]: Byte; // v2.44.0+
end;
圖示集的逐停止點覆寫（v2.44.0+）
Icon Set 規則中的每個停止點都可以用 17 種內建圖示家族中的任一圖示覆寫其顯示圖示，並以 (OverrideSet, IconId) 配對識別。XLSX 會針對每個被覆寫的停止點輸出 <cfIcon iconSet="..." iconId="N"/>。BIFF8 CF12 仍會顯示家族預設圖示，因為 BIFF8 wire format 沒有逐停止點覆寫的欄位 — 這在目前版本中是 XLSX 專用能力。只有透過 SetIconOverride 明確啟用的停止點，HasIconOverride[i] 才會回傳 True；預設圖示停止點仍會使用家族的停止位置預設值
規則
type
TCondFormatRule = class
property Kind: TXLSCfKind;
property cfType: Word; // CF-record subtype
property Operator_: Word; // comparison operator for cellIs
property DataBar: TXLSDataBarSpec; // non-nil for Data Bar rules
property ColorScale: TXLSColorScaleSpec; // non-nil for Color Scale rules
property IconSet: TXLSIconSetSpec; // non-nil for Icon Set rules
property Style: TXLSDxfStyle; // DXF override; lazy-created (v2.35.0+)
property DxfBlob: TXLSBlob; // raw DXF bytes from Parse (v2.35.0+)
property Priority: Word; // CF12 ipriority; 0 = writer assigns (v2.45.0+)
end;
每個 CF12 規則中 DataBar、ColorScale、IconSet 只會有一個非 nil，與規則的 Kind 一致。傳統儲存格規則（非 CF12）則會讓三者都維持 nil，並使用 Operator_ 加 Formula1 / Formula2
Style 屬性（v2.35.0+）會在第一次讀取時延後建立；回傳物件由規則擁有，並在其解構時釋放。請透過在 Style 上對應的 SetXxx 呼叫來設定 HasXxx。BIFF8 讀取器除了將它們解碼為 Style（v2.35.1+）之外，也會把原始位元組保留在 DxfBlob 中，因此載入-編輯-儲存往返會反映任何載入後對 Style 的修改；如果使用者沒有碰它，儲存檔會帶著與原始檔相同的覆寫
在 BIFF8 CF12 資料條、色階與圖示集規則中，[MS-XLS] 要求內嵌 DXF 區塊必須為空。自 v2.87.4 起，HotXLS 依照這項規則：儲存 .xls 檔時，透過 Rule.Style 指定的樣式覆寫不會被序列化到這三種 CF12 類型。資料條／色階／圖示集規則本身仍會透過 CF12 類型專屬尾端保留下來。XLSX 條件格式輸出不受影響
容器
type
TCondFormat = class
procedure ClearRow(row: Integer);
procedure ClearCol(col: Integer);
procedure ClearRange(row1, col1, row2, col2: Integer);
procedure MoveRanges(row1, col1, row2, col2,
drow, dcol: Integer);
function RuleCount: Integer; // v2.40.0+
function Rule(I: Integer): TCondFormatRule; // v2.40.0+
property Range[i: Integer]: TCondRange; default;
property IsEmpty: Boolean;
property IsExt12: Boolean; // true = emits CONDFMT12/CF12
property IsShadowed: Boolean; // v2.37.0+ — duplicate CONDFMT marker
property TotalRange: TCondRange; // v2.37.0+ — merged-extent range
end;
Cross-version shadow detection (v2.37.0+)
Excel 儲存的檔案常同時帶有 Excel 2003 的儲存格值 CONDFMT 與 Excel 2007+ 的 CONDFMT12，而且覆蓋相同的 sqref — 較舊的儲存格值記錄是舊版 Excel 仍可顯示的跨版本回退。讀取器在偵測到 TotalRange 的精確邊界框比對後，會把較舊的項目標記為 IsShadowed = True，因此遍歷條件格式集合的使用者面向程式可以略過重複項目。寫入器在儲存時仍會輸出兩種記錄家族，以維持 Excel 2003 ↔ Excel 2007+ 相容性
傳輸格式
在 BIFF8 SaveAs(xlExcel97) 中，CF12 規則會輸出 CONDFMT12 ($0879) + CF12 ($087A) 記錄，並與傳統 CONDFMT ($01B0) + CF ($01B1) 一起提供，讓 Excel 2003 也能跨版本相容。讀取器會辨識這些現代記錄，並透過相同的記憶體規則模型公開它們，因此帶有延伸規則的 Excel 建立 .xls 檔可以無資料遺失地往返
範例
// Data bar with custom min/max thresholds.
with Sheet.AddCondFormatDataBar('A1:A10', $00FF0000,
cfvNumber, '0', cfvNumber, '100').DataBar do
begin
ShowValue := True;
MinLength := 10;
MaxLength := 90;
end;
// 3 Arrows icon set, reversed so green points down.
with Sheet.AddCondFormatIconSet('B1:B10', icsArrows3).IconSet do
begin
Reverse := True;
ShowOnly := False;
end;
另請參閱
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat（XLSX 端）