Classe TCondFormat
Unidade: lxCondFormat
Família de formatação condicional do BIFF8 (.xls) com suporte às regras de extensão do Excel 2007+. TXLSWorksheet mantém uma coleção de entradas TCondFormat; cada entrada cobre um ou mais intervalos de células e mantém uma lista ordenada de objetos TCondFormatRule, sendo cada regra uma regra legada de valor de célula ou uma regra CF12 de Data Bar / Color Scale / Icon Set. Os quatro pontos de entrada Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) constroem regras do subtipo correto. Disponível desde v2.34.0
Enumeração de tipo de limite
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
Enumeração de família de conjunto de ícones
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, ou 5) é encoded no enum nome
Valor de limite (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;
Conteúdo da barra de dados
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 cor ida e volta (v2.43.0+)
A cor de preenchimento de uma regra Data Bar e as cores de cada ponto de uma regra Color Scale podem ser definidas contra um índice de tema da pasta de trabalho mais um valor de tom por meio de SetThemeColor(ThemeId, Tint) em vez de um RGB fixo. O gravador XLSX emite <color theme="N"/> quando Tint é exatamente 0.0 ou <color theme="N" tint="0.5"/> quando é diferente de zero, seguindo a saída de "forma mais curta" do próprio Excel. O leitor analisa as duas combinações de atributos e cai para o caminho RGB rgb= quando nem theme nem tint estão presentes. Os dois modos são mutuamente exclusivos por slot; o último Set chamado vence. IsThemeColor reflete o modo ativo para inspeção
O BIFF8 CF12 armazena apenas a cor RGB resolvida — o modo tema faz round-trip no backend XLSX exclusivamente nesta versão iconSet não têm elementos <color>, então a adição do modo tema não os afeta
Conteúdo da escala de cores
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;
Conteúdo do conjunto de ícones
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;
Substituição de ícone por ponto de parada (v2.44.0+)
Cada ponto de parada em uma regra Icon Set pode substituir seu ícone exibido por qualquer ícone de qualquer uma das 17 famílias de ícones internas, identificado por um par (OverrideSet, IconId). O XLSX emite <cfIcon iconSet="..." iconId="N"/> por ponto de parada substituído. O CF12 do BIFF8 continua a renderizar o ícone padrão da família porque o formato de fio do BIFF8 não tem slot para substituição por ponto de parada — isso é um recurso exclusivo do XLSX nesta versão. HasIconOverride[i] retorna True apenas para pontos de parada explicitamente ativados por meio de SetIconOverride; os pontos de parada com ícone padrão continuam usando o padrão de posição de parada da família
Regra
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;
Apenas um de DataBar / ColorScale / IconSet é não nulo por regra CF12, correspondendo ao Kind da regra. Regras legadas cellIs (não CF12) deixam os três como nulos e usam Operator_ + Formula1 / Formula2
A propriedade Style (v2.35.0+) é criada preguiçosamente na primeira leitura; o objeto retornado pertence à regra e é liberado no destrutor. Defina HasXxx pela chamada correspondente SetXxx em Style. O leitor BIFF8 mantém os bytes brutos em DxfBlob além de decodificá-los em Style (v2.35.1+), então um round-trip de carregar-editar-salvar reflete qualquer mutação de Style após o carregamento; se o usuário não mexer nele, o arquivo salvo carrega as mesmas substituições do original
Em regras Data Bar, Color Scale e Icon Set de CF12 em BIFF8, [MS-XLS] exige que o bloco DXF inline esteja vazio. A partir de v2.87.4, o HotXLS segue essa regra: substituições de estilo atribuídas por meio de Rule.Style não são serializadas para esses três tipos CF12 ao salvar arquivos .xls. A configuração da regra Data Bar / Color Scale / Icon Set ainda é preservada pela cauda específica do tipo CF12. A saída de formatação condicional XLSX não é afetada
Contêiner
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+)
Arquivos salvos pelo Excel frequentemente trazem tanto um CONDFMT de valor de célula do Excel 2003 quanto um CONDFMT12 do Excel 2007+ cobrindo o mesmo sqref — o registro de valor de célula é um fallback entre versões que o Excel mais antigo ainda consegue renderizar. O leitor marca a entrada mais antiga com IsShadowed = True depois de detectar uma correspondência exata de caixa delimitada em TotalRange, então o código voltado ao usuário que percorre a coleção de formatação condicional pode ignorar o duplicado. O gravador continua emitindo ambas as famílias de registros ao salvar para compatibilidade entre Excel 2003 ↔ Excel 2007+
Formato de transferência
Em SaveAs(xlExcel97) de BIFF8, as regras CF12 emitem CONDFMT12 ($0879) + CF12 ($087A) ao lado do legado CONDFMT ($01B0) + CF ($01B1) para compatibilidade cruzada com o Excel 2003. O leitor reconhece os registros modernos e os expõe pelo mesmo modelo de regra em memória, para que arquivos .xls criados no Excel com regras de extensão façam round-trip sem perda de dados
Exemplo
// 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;
Veja também
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (lado XLSX)