TCondFormat / TCondFormatRule og CF12-spec-klasser

Enhed: lxCondFormat

BIFF8-(.xls)-familien til betinget formatering, der understøtter Excel 2007+-udvidelsesregler. TXLSWorksheet holder en samling af TCondFormat-poster; hver post dækker et eller flere celleområder og indeholder en ordnet liste af TCondFormatRule-objekter, hvor hver regel enten er en ældre celleværdi-regel eller en CF12 Data Bar / Color Scale / Icon Set-regel. De fire Sheet.AddCondFormat*-indgangspunkter (DataBar, ColorScale2, ColorScale3, IconSet) konstruerer regler af den korrekte undertype. Tilgængelig siden v2.34.0

Enumeration af tærskeltype

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

Enumeration af ikonsæt-familier

type
  TXLSIconSetType = (
    icsArrows3, icsArrows3Gray, icsFlags3,
    icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
    icsSymbols3, icsSymbolsUncircled3,
    icsArrows4, icsArrows4Gray, icsRedToBlack4,
    icsRatings4, icsTrafficLights4,
    icsArrows5, icsArrows5Gray,
    icsRatings5, icsQuarters5);

De 17 basis-Excel 2007-ikonfamilier. Det numeriske stopantal (3, 4 eller 5) er kodet ind i enum-navnet

Tærskelværdi (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;

Data bar-payload

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-temafarve round-trip (v2.43.0+)

Barfyldningsfarven på en Data Bar-regel og farverne på de enkelte stop på en Color Scale-regel kan sættes mod et projektmappe-temaindeks plus en toningsværdi via SetThemeColor(ThemeId, Tint) i stedet for en fastlåst RGB. XLSX-writer'en udsender <color theme="N"/>, når Tint er præcis 0.0, eller <color theme="N" tint="0.5"/>, når den ikke er nul, hvilket matcher Excels egen "korteste form"-output. Læseren fortolker begge attributkombinationer og falder tilbage til RGB-rgb=-stien, når hverken theme eller tint er til stede. De to tilstande er gensidigt udelukkende pr. plads; uanset hvilken Set der blev kaldt sidst, vinder den. IsThemeColor afspejler den aktive tilstand til inspektion

BIFF8 CF12 gemmer kun den opløste RGB-farve — tematilstand round-tripper i denne udgivelse udelukkende på XLSX-backenden. iconSet-regler har ingen <color>-elementer, så tematilstands-tilføjelsen påvirker dem ikke

Color scale-payload

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

Per-stop ikonoverride (v2.44.0+)

Hvert stop i en Icon Set-regel kan overskrive sit viste ikon med ethvert ikon fra en af de 17 indbyggede ikonfamilier, identificeret ved et (OverrideSet, IconId)-par. XLSX udsender <cfIcon iconSet="..." iconId="N"/> pr. overskrevet stop. BIFF8 CF12 fortsætter med at gengive familie-standardikonet, fordi BIFF8-wireformatet ikke har nogen plads til per-stop-overskrivelse — dette er en XLSX-only-funktion i den aktuelle udgivelse. HasIconOverride[i] returnerer kun True for stop, der eksplicit er valgt til via SetIconOverride; stop med standardikon fortsætter med at bruge familiens stoppositions-standard

Regel

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æcis én af DataBar / ColorScale / IconSet er ikke-nil pr. CF12-regel, hvilket matcher regelens Kind. Ældre cellIs-regler (ikke-CF12) lader alle tre være nil og bruger Operator_ + Formula1 / Formula2

Egenskaben Style (v2.35.0+) oprettes lazy ved første læsning; det returnerede objekt ejes af reglen og frigøres i dens destruktor. Sæt HasXxx via det tilsvarende SetXxx-kald på Style. BIFF8-læseren beholder de rå bytes i DxfBlob ud over at afkode dem til Style (v2.35.1+), så en load-edit-save round-trip afspejler enhver post-load-mutation af Style; hvis brugeren ikke rører den, bærer den gemte fil de samme overskrivelser som originalen

På BIFF8-CF12 Data Bar-, Color Scale- og Icon Set-regler kræver [MS-XLS], at den inline DXF-blok er tom. Fra og med v2.87.4 følger HotXLS denne regel: stiloverskrivelser tildelt gennem Rule.Style serialiseres ikke for disse tre CF12-typer, når der gemmes .xls-filer. Selve Data Bar / Color Scale / Icon Set-regel- konfigurationen bevares stadig gennem den CF12-type-specifikke hale. XLSX-output for betinget formatering påvirkes ikke

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;

Krydsversions-skyggedetektion (v2.37.0+)

Excel-gemte filer bærer ofte både en Excel 2003-celleværdi- CONDFMT og en Excel 2007+-CONDFMT12, der dækker det samme sqref — celleværdi-posten er en krydsversions-fallback, som ældre Excel stadig kan gengive. Læseren markerer den ældre post via IsShadowed = True efter at have registreret et præcist bounding-box-match på TotalRange, så brugerorienteret kode, der itererer samlingen af betinget formatering, kan springe duplikatet over. Writer'en fortsætter med at udsende begge postfamilier ved gemning for Excel 2003 ↔ Excel 2007+-kompatibilitet

Wire-format

Ved BIFF8-SaveAs(xlExcel97) udsender CF12-regler CONDFMT12 ($0879) + CF12 ($087A)- poster sammen med de ældre CONDFMT ($01B0) + CF ($01B1) for krydsversions-kompatibilitet med Excel 2003. Læseren genkender de moderne poster og viser dem gennem den samme in-memory-regelmodel, så Excel-forfattede .xls-filer med udvidelsesregler round-tripper uden datatab

Eksempel

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

Se også

TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (XLSX-siden)