TCondFormat / TCondFormatRule
Jednotka: lxCondFormat
Rodina podmíněného formátování BIFF8 (.xls) podporující rozšiřující pravidla Excelu 2007+. TXLSWorksheet udržuje kolekci položek TCondFormat; každá položka pokrývá jeden nebo více rozsahů buněk a obsahuje seřazený seznam objektů TCondFormatRule, přičemž každé pravidlo je buď starší pravidlo podle hodnoty buňky, nebo pravidlo CF12 Data Bar / Color Scale / Icon Set. Čtyři vstupní body Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) vytvářejí pravidla správného podtypu. K dispozici od v2.34.0
Výčet 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
Výčet rodiny sad ikon
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
17 základních rodin ikon Excelu 2007. Počet číselných prahů (3, 4 nebo 5) je zakódován v názvu výčtu
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;
Datový pruh
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;
Obousměrný přenos barev motivu XLSX (v2.43.0+)
Barva výplně pruhu v pravidle Data Bar a barvy jednotlivých prahů v pravidle Color Scale lze nastavit vůči indexu motivu sešitu a hodnotě odstínu přes SetThemeColor(ThemeId, Tint) místo pevného RGB. Zapisovač XLSX vypíše <color theme="N"/>, když je Tint přesně 0.0, nebo <color theme="N" tint="0.5"/>, když je nenulový, což odpovídá výstupu Excelu v jeho „shortest form“ podobě. Čtečka parsuje obě kombinace atributů a vrátí se k cestě RGB rgb=, když není přítomno ani theme ani tint. Dva režimy se pro jeden slot vzájemně vylučují; platí poslední volání Set a IsThemeColor odráží aktivní režim pro kontrolu
BIFF8 CF12 ukládá pouze výslednou barvu RGB — režim motivu se v této verzi přenáší obousměrně výhradně na backendu XLSX iconSet pravidla nemají žádné prvky <color>, takže přidání režimu motivu se jich netýká
Barevná š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;
Přepsání ikony pro jednotlivý práh (v2.44.0+)
Každý práh v pravidle Icon Set může přepsat svou zobrazovanou ikonu libovolnou ikonou z libovolné z 17 vestavěných rodin ikon, určenou dvojicí (OverrideSet, IconId). XLSX zapisuje pro každý přepsaný práh <cfIcon iconSet="..." iconId="N"/>. BIFF8 CF12 dál vykresluje výchozí ikonu rodiny, protože binární formát BIFF8 nemá slot pro přepsání jednotlivých prahů — v aktuální verzi je to schopnost pouze pro XLSX. HasIconOverride[i] vrací True jen pro prahy, které byly výslovně zapnuty přes SetIconOverride; prahy s výchozí ikonou dál používají výchozí pozici prahu dané rodiny
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;
Právě jedna z položek DataBar / ColorScale / IconSet je pro každé pravidlo CF12 nenulová, což odpovídá hodnotě Kind pravidla. Starší pravidla cellIs (mimo CF12) ponechávají všechny tři jako nil a používají Operator_ + Formula1 / Formula2
Vlastnost Style (v2.35.0+) se vytváří líně při prvním čtení; vrácený objekt vlastní pravidlo a uvolňuje se v jeho destruktoru. Nastavte HasXxx přes odpovídající volání SetXxx na Style. Čtečka BIFF8 kromě dekódování do Style (v2.35.1+) zachovává surové bajty také v DxfBlob, takže průchod načtení-upravení-uložení zachytí každou změnu Style po načtení; když se ho uživatel nedotkne, uložený soubor nese stejné přepisy jako původní
U pravidel CF12 Data Bar, Color Scale a Icon Set v BIFF8 CF12 vyžaduje [MS-XLS] prázdný inline blok DXF. Od v2.87.4 se tím HotXLS řídí: přepisy stylu přiřazené přes Rule.Style se při ukládání souborů .xls pro tyto tři typy CF12 neserializují. Samotná konfigurace pravidla Data Bar / Color Scale / Icon Set se dál zachovává přes koncový blok specifický pro daný typ CF12. Výstup podmíněného formátování XLSX tím není dotčen
Kontejner
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-Verze shadow detection (v2.37.0+)
Excel-saved files často nesou jak Excel 2003 cell-value CONDFMT, tak Excel 2007+ CONDFMT12 pokrývající stejné sqref — záznam cell-value je křížově verzová záloha, kterou starší Excel stále dokáže vykreslit. Čtečka označí starší položku pomocí IsShadowed = True po zjištění přesné shody ohraničujícího boxu na TotalRange, takže uživatelský kód procházející kolekci podmíněného formátování může duplicitní záznam přeskočit. Zapisovač při uložení dál vypisuje obě rodiny záznamů pro kompatibilitu Excel 2003 ↔ Excel 2007+
Formát přenosu
U SaveAs(xlExcel97) v BIFF8 pravidla CF12 vypisují CONDFMT12 ($0879) + CF12 ($087A) vedle starších CONDFMT ($01B0) + CF ($01B1) pro kompatibilitu s Excelem 2003 napříč verzemi. Čtečka rozpozná moderní záznamy a zpřístupní je přes stejný model pravidel v paměti, takže soubory .xls vytvořené Excelem s rozšiřujícími pravidly projdou bez ztráty dat
Pří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;
Viz také
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (XLSX side)