Clase TCondFormat

Unidad: lxCondFormat

La familia de formato condicional BIFF8 (.xls) da soporte a las reglas de extensión de Excel 2007+. TXLSWorksheet mantiene una colección de entradas TCondFormat; cada entrada cubre uno o más rangos de celdas y conserva una lista ordenada de TCondFormatRule, y cada regla puede ser una regla heredada de valor de celda o una regla CF12 de barra de datos, escala de color o conjunto de iconos Los cuatro puntos de entrada Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) construyen reglas del subtipo correcto. Disponible desde 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-establecer 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, o 5) es encoded en el enum nombre

Threshold valor (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 útil 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 una barra de datos y los colores de cada escala pueden configurarse con un índice de tema del libro más un valor de tinte 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 no es cero, en línea con 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 se excluyen mutuamente por ranura; gana la última llamada a Set IsThemeColor refleja el modo activo para inspección

BIFF8 CF12 almacena solo el RGB resuelto — el modo tema se mantiene entre guardado y apertura exclusivamente en el backend XLSX de esta versión iconSet las reglas no tienen elementos <color>, así que la adición del modo tema no les afecta

Carga útil 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 útil 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 escala, v2.44.0+

Cada escala de una regla de conjunto de iconos puede reemplazar su icono mostrado con 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 escala anulada. BIFF8 CF12 sigue mostrando el icono predeterminado de la familia porque el formato binario BIFF8 no tiene una ranura para anulación por escala, así que esta capacidad solo existe en XLSX en la versión actual. HasIconOverride[i] devuelve True solo para las escalas que se activaron explícitamente mediante SetIconOverride; las escalas con icono predeterminado siguen usando el valor predeterminado de la posición dentro de la familia

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;

Solo uno de DataBar / ColorScale / IconSet es no nulo por cada regla CF12, lo que coincide 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 bajo demanda 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 en bruto en DxfBlob además de decodificarlos en Style (v2.35.1+), de modo que un ciclo de cargar-editar-guardar refleja cualquier modificación de Style después de la carga; si el usuario no lo toca, el archivo guardado conserva las mismas anulaciones que el original

En reglas BIFF8 CF12 de barra de datos, escala de color y conjunto de iconos, [MS-XLS] exige que el bloque DXF en línea esté vacío. A partir de v2.87.4, HotXLS cumple esa regla: las anulaciones 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 de barra de datos, escala de color o conjunto de iconos sigue preservándose mediante la cola específica del tipo CF12. La salida de formato condicional XLSX no cambia

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

Los archivos guardados en Excel suelen incluir 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 un respaldo entre versiones que el Excel antiguo todavía puede renderizar. El lector marca la entrada antigua mediante IsShadowed = True después de detectar una coincidencia exacta de cuadro delimitador en TotalRange, así que el código visible para el usuario que recorre la colección de formato condicional puede omitir el duplicado. El escritor sigue emitiendo ambas familias de registros al guardar para compatibilidad entre Excel 2003 y Excel 2007+

Wire formato

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 en Excel con reglas de extensión se conservan 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)