Klasy TCondFormat / TCondFormatRule i CF12

Moduł: lxCondFormat

Rodzina formatowania warunkowego BIFF8 (.xls) obsługująca reguły rozszerzeń Excela 2007+. TXLSWorksheet utrzymuje kolekcję wpisów TCondFormat; każdy wpis obejmuje jeden lub więcej zakresów komórek i zawiera uporządkowaną listę obiektów TCondFormatRule, z których każda jest albo regułą legacy opartą na wartości komórki, albo regułą CF12 Data Bar / Color Scale / Icon Set. Cztery punkty wejścia Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) tworzą reguły właściwego podtypu. Dostępne od v2.34.0

Threshold kind enumeration

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

Icon-ustawić family enumeration

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, lub 5) jest encoded w enum nazwa

Threshold wartość (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;

Ładunek paska danych

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 motyw kolor dwukierunkowy (v2.43.0+)

Kolor wypełnienia paska w regule Data Bar i kolory poszczególnych punktów w regule Color Scale można ustawić względem indeksu motywu skoroszytu z wartością tint przez SetThemeColor(ThemeId, Tint) zamiast stałego RGB. Zapisujący XLSX emituje <color theme="N"/> gdy Tint wynosi dokładnie 0.0 lub <color theme="N" tint="0.5"/> gdy jest niezerowy, zgodnie z własnym wyjściem Excela w „najkrótszej formie”. Czytnik analizuje oba zestawienia atrybutów i przechodzi na ścieżkę RGB rgb= gdy nie ma ani theme, ani tint. Dwa tryby są wzajemnie wykluczające dla jednego slotu; wygrywa to wywołanie Set, które nastąpiło jako ostatnie. IsThemeColor odzwierciedla aktywny tryb do inspekcji

BIFF8 CF12 przechowuje tylko rozstrzygnięty kolor RGB — tryb motywu przechodzi przez zapis i odczyt wyłącznie na backendzie XLSX w tej wersji. Reguły iconSet nie mają elementów <color>, więc dodanie trybu motywu nie ma na nie wpływu

Ładunek skali kolorów

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;

Icon ustawić payload

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;

Nadpisanie ikony dla każdego punktu (v2.44.0+)

Każdy punkt w regule Icon Set może zastąpić swoją ikonę wyświetlaną dowolną ikoną z dowolnej z 17 wbudowanych rodzin ikon, oznaczoną parą (OverrideSet, IconId). XLSX emituje <cfIcon iconSet="..." iconId="N"/> dla każdego nadpisanego punktu. BIFF8 CF12 nadal renderuje ikonę domyślną rodziny, ponieważ format przewodowy BIFF8 nie ma miejsca na nadpisanie per punkt — to w obecnym wydaniu możliwość wyłącznie dla XLSX. HasIconOverride[i] zwraca True tylko dla punktów, które zostały jawnie włączone przez SetIconOverride; punkty z domyślną ikoną nadal używają domyślnej ikony dla danej pozycji

Rule

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;

Dokładnie jedno z DataBar / ColorScale / IconSet jest nie-nil dla każdej reguły CF12, zgodnie z Kind reguły. Tradycyjne reguły cellIs (nie-CF12) pozostawiają wszystkie trzy jako nil i używają Operator_ + Formula1 / Formula2

Właściwość Style (v2.35.0+) jest tworzona leniwie przy pierwszym odczycie; zwrócony obiekt należy do reguły i jest zwalniany w jej destruktorze. Ustawiaj HasXxx odpowiednim wywołaniem SetXxx na Style. Czytnik BIFF8 oprócz zachowania surowych bajtów w DxfBlob dekoduje je też do Style (v2.35.1+), więc cykl wczytaj-edytuj-zapisz odzwierciedla każdą modyfikację Style po wczytaniu; jeśli użytkownik go nie dotknie, zapisany plik zachowuje te same nadpisania co oryginał

W regułach BIFF8 CF12 Data Bar, Color Scale i Icon Set [MS-XLS] wymaga, aby wbudowany blok DXF był pusty. Od v2.87.4 HotXLS stosuje tę regułę: nadpisania stylu przypisane przez Rule.Style nie są serializowane dla tych trzech typów CF12 przy zapisie plików .xls. Sama konfiguracja reguł Data Bar / Color Scale / Icon Set nadal jest zachowywana w typowym dla CF12 ogonie. Wynik formatowania warunkowego XLSX pozostaje bez zmian

Container

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+)

Pliki zapisane przez Excela często zawierają zarówno CONDFMT wartości komórek z Excela 2003, jak i CONDFMT12 z Excela 2007+ obejmujące ten sam sqref — rekord wartości komórek jest zapasowym wariantem między wersjami, który starszy Excel nadal potrafi wyrenderować. Czytnik oznacza starszy wpis jako IsShadowed = True po wykryciu dokładnego dopasowania obwiedni na TotalRange, dzięki czemu kod użytkowy iterujący po kolekcji formatowania warunkowego może pominąć duplikat. Zapisujący nadal emituje obie rodziny rekordów przy zapisie dla zgodności Excel 2003 ↔ Excel 2007+

Wire format

W BIFF8 SaveAs(xlExcel97), reguły CF12 emitują CONDFMT12 ($0879) + CF12 ($087A) obok starszych CONDFMT ($01B0) + CF ($01B1) dla zgodności między wersjami z Excelem 2003. Czytnik rozpoznaje nowoczesne rekordy i udostępnia je przez ten sam model reguł w pamięci, dzięki czemu pliki .xls utworzone przez Excela z regułami rozszerzonymi przechodzą zapis i odczyt bez utraty danych

Przykład

// 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;

Zobacz także

TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (strona XLSX)