TCondFormat / TCondFormatRule and CF12 spec classes

Unité : lxCondFormat

La famille de mise en forme conditionnelle BIFF8 (.xls) prenant en charge les règles d'extension d'Excel 2007+ TXLSWorksheet keeps a collection of TCondFormat entries; each entry covers one or more cell ranges and holds an ordered list of TCondFormatRule , chaque règle étant soit une règle de valeur de cellule héritée, soit une règle CF12 Barre de données / Échelle de couleurs / Jeu d'icônes. Les quatre Sheet.AddCondFormat* entry points (DataBar, ColorScale2, ColorScale3, IconSet) construct rules of the correct subtype. Available since 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-set family enumeration

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

Les 17 familles d'icônes de base d'Excel 2007. Le nombre de paliers (3, 4 ou 5) est encodé dans le nom de l'enum

Threshold value (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 theme color round-trip (v2.43.0+)

La couleur de remplissage de la barre d'une règle Barre de données et les couleurs par palier d'une règle Échelle de couleurs peuvent être définies par rapport à un index de thème du classeur plus une valeur de teinte via SetThemeColor(ThemeId, Tint) instead of a frozen RGB. The XLSX writer emits <color theme="N"/> when Tint is exactly 0.0 or <color theme="N" tint="0.5"/> quand non nul, à la manière de la sortie "forme la plus courte" d'Excel elle-même. Le lecteur analyse les deux combinaisons d'attributs et retombe sur le RGB rgb= path when neither theme nor tint is present. Two modes are mutually exclusive per slot; whichever Set was called last wins IsThemeColor reflects the active mode for inspection

Le CF12 BIFF8 ne stocke que la couleur RGB résolue — le mode thème ne fait un aller-retour que sur le backend XLSX dans cette version iconSet rules have no <color> elements so the theme-mode addition does not affect them

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 icon override (v2.44.0+)

Chaque palier d'une règle Jeu d'icônes peut surcharger son icône affichée avec n'importe quelle icône de l'une des 17 familles d'icônes intégrées, identifiée par un (OverrideSet, IconId) pair. XLSX emits <cfIcon iconSet="..." iconId="N"/> par palier surchargé. Le CF12 BIFF8 continue d'afficher l'icône par défaut de la famille car le format filaire BIFF8 n'a pas d'emplacement pour la surcharge par palier — c'est une capacité propre à XLSX dans la version actuelle HasIconOverride[i] returns True only for stops that have been explicitly opted in via SetIconOverride; the default-icon stops continue to use the family's stop-position default

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;

Exactly one of DataBar / ColorScale / IconSet is non-nil per CF12 rule, matching the rule's Kind. Legacy cellIs rules (non-CF12) leave all three nil and use Operator_ + Formula1 / Formula2

The Style (v2.35.0+) est créée paresseusement à la première lecture ; l'objet renvoyé appartient à la règle et est libéré dans son destructeur. Définissez HasXxx via the corresponding SetXxx call on Style. The BIFF8 reader keeps the raw bytes in DxfBlob in addition to decoding them into Style (v2.35.1+), so a load-edit-save round-trip reflects any post-load mutation of Style ; si l'utilisateur n'y touche pas, le fichier enregistré porte les mêmes overrides que l'original

On BIFF8 CF12 Barre de données, Échelle de couleurs et Jeu d'icônes, [MS-XLS] exige que le bloc DXF inline soit vide. À partir de la v2.87.4, HotXLS respecte cette règle : les overrides de style assignés via Rule.Style ne sont pas sérialisés pour ces trois types de CF12 à l'enregistrement de fichiers .xls. La configuration même des règles Barre de données / Échelle de couleurs / Jeu d'icônes reste préservée via la partie spécifique au type du CF12. La sortie de mise en forme conditionnelle XLSX n'est pas affectée

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

Excel-saved files often carry both an Excel 2003 cell-value CONDFMT and an Excel 2007+ CONDFMT12 couvrant le même sqref — l'enregistrement de valeur de cellule est un repli inter-versions qu'un Excel plus ancien sait toujours afficher. Le lecteur signale l'entrée antérieure via IsShadowed = True after detecting an exact bounding-box match on TotalRange, de sorte que le code applicatif qui itère la collection de mise en forme conditionnelle peut ignorer le doublon. L'écriture continue d'émettre les deux familles d'enregistrements à la sauvegarde, pour la compatibilité Excel 2003 ↔ Excel 2007+

Wire format

On BIFF8 SaveAs(xlExcel97), CF12 rules emit CONDFMT12 ($0879) + CF12 ($087A) records alongside the legacy CONDFMT ($01B0) + CF ($01B1) pour la compatibilité inter-versions avec Excel 2003. Le lecteur reconnaît les enregistrements modernes et les expose via le même modèle de règles en mémoire, si bien que les fichiers .xls créés par Excel avec des règles d'extension font l'aller-retour sans perte de données

Exemple

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

Voir aussi

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