TCondFormat / TCondFormatRule y clases de especificación CF12

Unidad: lxCondFormat

La familia de formato condicional BIFF8 (.xls) compatible con las reglas de extensión de Excel 2007+. TXLSWorksheet mantiene una colección de entradas TCondFormat; cada entrada abarca uno o varios rangos de celdas y contiene una lista ordenada de objetos TCondFormatRule, siendo cada regla una regla heredada de valor de celda o una regla CF12 de barra de datos / escala de colores / conjunto de iconos. Los cuatro puntos de entrada Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) construyen reglas del subtipo correcto. Disponible desde v2.34.0

Enumeración de tipo de umbral

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

Enumeración de familia de conjunto de iconos

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, o 5) es encoded en el enum nombre

Valor de umbral (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;

Carga de barra de datos

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 tema color ida y vuelta (v2.43.0+)

El color de relleno de barra de una regla Data Bar y los colores de cada punto de una regla Color Scale se pueden establecer frente a un índice de tema del libro más un valor de matiz mediante SetThemeColor(ThemeId, Tint) en lugar de un RGB fijo. El escritor XLSX emite <color theme="N"/> cuando Tint es exactamente 0.0 o <color theme="N" tint="0.5"/> cuando es distinto de cero, igual que la salida de "forma más breve" de Excel. El lector analiza ambas combinaciones de atributos y recurre a la ruta RGB rgb= cuando no está presente ni theme ni tint. Los dos modos son excluyentes por ranura; gana la última llamada a Set IsThemeColor refleja el modo activo para inspección

BIFF8 CF12 almacena solo el color RGB resuelto — el modo tema se conserva de ida y vuelta exclusivamente en el backend XLSX en esta versión iconSet no tiene elementos <color>, así que la adición del modo tema no les afecta

Carga de escala de color

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;

Carga de conjunto de iconos

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;

Anulación de icono por punto (v2.44.0+)

Cada punto de un conjunto de iconos puede sustituir su icono mostrado por cualquier icono de cualquiera de las 17 familias de iconos integradas, identificado por un par (OverrideSet, IconId). XLSX emite <cfIcon iconSet="..." iconId="N"/> por cada punto sustituido. BIFF8 CF12 sigue representando el icono predeterminado de la familia porque el formato de cable BIFF8 no tiene una ranura para sustituciones por punto — esta es una capacidad exclusiva de XLSX en la versión actual. HasIconOverride[i] devuelve True solo para los puntos que se han activado explícitamente mediante SetIconOverride; los puntos con icono predeterminado siguen usando el valor predeterminado de la posición del punto de la familia

Regla

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;

Solo uno de DataBar / ColorScale / IconSet es no nulo por cada regla CF12, en línea con Kind de la regla. Las reglas heredadas cellIs (no CF12) dejan los tres en nil y usan Operator_ + Formula1 / Formula2

La propiedad Style (v2.35.0+) se crea perezosamente en la primera lectura; el objeto devuelto pertenece a la regla y se libera en su destructor. Define HasXxx mediante la llamada SetXxx correspondiente en Style. El lector BIFF8 conserva los bytes sin procesar en DxfBlob además de decodificarlos en Style (v2.35.1+), de modo que un ciclo cargar-editar-guardar refleja cualquier mutación posterior a la carga de Style; si el usuario no lo toca, el archivo guardado lleva las mismas sustituciones que el original

En las reglas BIFF8 CF12 Data Bar, Color Scale e Icon Set, [MS-XLS] exige que el bloque DXF en línea esté vacío. A partir de v2.87.4, HotXLS sigue esa regla: las sustituciones de estilo asignadas mediante Rule.Style no se serializan para esos tres tipos CF12 al guardar archivos .xls. La propia configuración de la regla Data Bar / Color Scale / Icon Set sigue conservándose a través de la cola específica del tipo CF12. La salida de formato condicional XLSX no se ve afectada

Contenedor

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

Los archivos guardados por Excel suelen llevar tanto un CONDFMT de valor de celda de Excel 2003 como un CONDFMT12 de Excel 2007+ que cubren el mismo sqref — el registro de valor de celda es una alternativa entre versiones que el Excel antiguo todavía puede representar. El lector marca la entrada antigua con IsShadowed = True tras detectar una coincidencia exacta de caja delimitadora en TotalRange, de modo que el código de cara al usuario que recorre la colección de formato condicional pueda saltarse el duplicado. El escritor sigue emitiendo ambas familias de registros al guardar para compatibilidad entre Excel 2003 ↔ Excel 2007+

Formato de cable

En BIFF8 SaveAs(xlExcel97), las reglas CF12 emiten registros CONDFMT12 ($0879) + CF12 ($087A) junto con los CONDFMT ($01B0) + CF ($01B1) heredados para compatibilidad entre versiones con Excel 2003. El lector reconoce los registros modernos y los expone mediante el mismo modelo de reglas en memoria, de modo que los archivos .xls creados por Excel con reglas de extensión se conservan de ida y vuelta sin pérdida de datos

Ejemplo

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

Véase también

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