TCondFormat / TCondFormatRule
Jednotka: lxCondFormat
Rodina podmieneného formátovania BIFF8 (.xls), ktorá podporuje rozšírené pravidlá Excelu 2007+. TXLSWorksheet uchováva kolekciu položiek TCondFormat; každá položka pokrýva jeden alebo viac rozsahov buniek a drží usporiadaný zoznam objektov TCondFormatRule, pričom každé pravidlo je buď staršie pravidlo založené na hodnote bunky, alebo pravidlo CF12 Data Bar / Color Scale / Icon Set. Štyri vstupné body Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) vytvárajú pravidlá správneho podtypu. K dispozícii od v2.34.0
Enumerácia druhu prahu
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
Enumerácia rodiny sád ikon
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
17 základných rodín ikon Excelu 2007. Počet číselných zastavení (3, 4 alebo 5) je zakódovaný v názve enumerácie
Prahová hodnota (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;
Dátová lišta
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;
Prenos farby témy XLSX tam aj späť (v2.43.0+)
Farba výplne pruhu v pravidle Data Bar a farby jednotlivých zastavení v pravidle Color Scale sa môžu nastaviť proti indexu témy zošita a hodnote tint cez SetThemeColor(ThemeId, Tint) namiesto pevného RGB. Zapisovač XLSX vytvára <color theme="N"/>, keď je Tint presne 0.0, alebo <color theme="N" tint="0.5"/>, keď je nenulový, čo zodpovedá vlastnému výstupu Excelu v jeho najkratšej forme. Čítačka spracuje obe kombinácie atribútov a pri chýbajúcom theme aj tint sa vracia k ceste s RGB rgb=. Dva režimy sa pre jeden slot navzájom vylučujú; posledné volanie Set vyhráva a IsThemeColor odráža aktívny režim na kontrolu
BIFF8 CF12 uchováva iba vyriešenú farbu RGB — režim témy sa v tomto vydaní prenáša výlučne cez backend XLSX. Pravidlá iconSet nemajú žiadne prvky <color>, takže pridanie režimu témy sa ich netýka
Farebná škála
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;
Sada ikon
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;
Prepísanie ikony pre jednotlivé zastavenia (v2.44.0+)
Každé zastavenie v pravidle Icon Set môže prepísať svoju zobrazovanú ikonu ľubovoľnou ikonou z ktorejkoľvek z 17 zabudovaných rodín ikon, identifikovanou dvojicou (OverrideSet, IconId). XLSX zapisuje pre každé prepísané zastavenie <cfIcon iconSet="..." iconId="N"/>. BIFF8 CF12 naďalej zobrazuje predvolenú ikonu rodiny, pretože binárny formát BIFF8 nemá miesto pre prepísanie po zastaveniach — v aktuálnom vydaní je to schopnosť iba pre XLSX. HasIconOverride[i] vracia True iba pre zastavenia, ktoré boli výslovne aktivované cez SetIconOverride; zastavenia s predvolenou ikonou naďalej používajú predvolenú ikonu podľa pozície zastavenia v rodine
Pravidlo
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;
Presne jeden z DataBar / ColorScale / IconSet je pri každom pravidle CF12 nenil, čo zodpovedá Kind pravidla. Staršie pravidlá cellIs (ne-CF12) nechávajú všetky tri nil a používajú Operator_ + Formula1 / Formula2
Vlastnosť Style (v2.35.0+) sa vytvára lenivo pri prvom čítaní; vrátený objekt vlastní pravidlo a uvoľní sa v jeho destruktore. Nastavte HasXxx príslušným volaním SetXxx na Style. Čítačka BIFF8 okrem dekódovania do Style uchováva surové bajty aj v DxfBlob (v2.35.1+), takže cyklus načítanie-upravenie-uloženie odrazí každú zmenu Style po načítaní; ak sa používateľ nedotkne, uložený súbor nesie tie isté prepísania ako pôvodný
V pravidlách BIFF8 CF12 Data Bar, Color Scale a Icon Set vyžaduje [MS-XLS] prázdny inline blok DXF. Od v2.87.4 HotXLS toto pravidlo dodržiava: prepísania štýlu priradené cez Rule.Style sa pri ukladaní súborov .xls pre tieto tri typy CF12 neserializujú. Samotná konfigurácia pravidla Data Bar / Color Scale / Icon Set je stále zachovaná cez chvost špecifický pre typ CF12. Výstup podmieneného formátovania XLSX nie je dotknutý
Kontajner
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-Verzia shadow detection (v2.37.0+)
Súbory uložené v Exceli často nesú zároveň starší CONDFMT pre Excel 2003 aj CONDFMT12 pre Excel 2007+ pre ten istý sqref — záznam s hodnotou bunky je spätná záchrana pre staršie Excel, ktoré ho ešte vedia vykresliť. Čítačka označí starší záznam IsShadowed = True po zistení presnej zhody ohraničujúceho boxu na TotalRange, takže používateľský kód, ktorý prechádza kolekciu podmieneného formátovania, môže duplikát preskočiť. Zapisovač pri ukladaní naďalej vysiela obe rodiny záznamov pre kompatibilitu Excel 2003 ↔ Excel 2007+
Drôtový formát
Pri SaveAs(xlExcel97) na BIFF8 pravidlá CF12 emitujú CONDFMT12 ($0879) + CF12 ($087A) záznamy spolu so staršími CONDFMT ($01B0) + CF ($01B1) pre kompatibilitu s Excelom 2003. Čítačka rozpozná moderné záznamy a vystaví ich cez ten istý pamäťový model pravidiel, takže súbory .xls vytvorené Excelom s rozšírenými pravidlami sa prenesú bez straty údajov
Príklad
// 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;
Pozri tiež
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (strana XLSX)