TCondFormat / TCondFormatRule
Unidade: lxCondFormat
A família de formatação condicional BIFF8 (.xls) que suporta regras de extensão do Excel 2007+. TXLSWorksheet mantém uma coleção de entradas TCondFormat; cada entrada abrange um ou mais intervalos de células e contém uma lista ordenada de objetos TCondFormatRule, sendo cada regra uma regra legada de valor de célula ou uma regra CF12 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 limiar
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);
As 17 famílias base de ícones do Excel 2007. O número de paragens (3, 4 ou 5) é codificado no nome da enumeração
Valor de limiar (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;
Payload de 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;
Round-trip de cor de tema XLSX (v2.43.0+)
A cor de preenchimento da barra numa regra Data Bar e as cores por paragem numa regra Color Scale podem ser definidas com base num índice de tema do livro mais um valor de tint através de SetThemeColor(ThemeId, Tint) em vez de um RGB fixo. O escritor XLSX emite <color theme="N"/> quando Tint é exatamente 0.0 ou <color theme="N" tint="0.5"/> quando não é zero, correspondendo à própria saída em "shortest form" do Excel. O leitor analisa ambas as combinações de atributos e recua para o caminho RGB rgb= quando não existe nem theme nem tint. 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 guarda apenas a cor RGB resolvida — o modo de tema faz round-trip exclusivamente no backend XLSX nesta versão. As regras iconSet não têm elementos <color>, pelo que a adição do modo de tema não as afeta
Payload de 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;
Payload de 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 paragem (v2.44.0+)
Cada paragem numa regra Icon Set pode substituir o ícone apresentado por qualquer ícone de qualquer uma das 17 famílias de ícones incorporadas, identificado por um par (OverrideSet, IconId). O XLSX emite <cfIcon iconSet="..." iconId="N"/> por cada paragem substituída. O BIFF8 CF12 continua a renderizar o ícone predefinido da família porque o formato binário BIFF8 não tem espaço para substituição por paragem — esta é uma capacidade apenas XLSX na versão atual. HasIconOverride[i] devolve True apenas para as paragens explicitamente ativadas via SetIconOverride; as paragens com ícone predefinido continuam a usar a predefinição de posição da paragem 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;
Exatamente um de DataBar / ColorScale / IconSet não é nulo por regra CF12, correspondendo ao Kind da regra. As regras legadas cellIs (não-CF12) deixam os três nulos e usam Operator_ + Formula1 / Formula2
A propriedade Style (v2.35.0+) é criada preguiçosamente na primeira leitura; o objeto devolvido pertence à regra e é libertado no seu destrutor. Defina HasXxx através da chamada SetXxx correspondente em Style. O leitor BIFF8 mantém os bytes brutos em DxfBlob para além de os descodificar em Style (v2.35.1+), pelo que um ciclo carregar-editar-guardar reflete qualquer mutação pós-carregamento de Style; se o utilizador não lhe tocar, o ficheiro guardado leva as mesmas substituições que o original
Nas regras BIFF8 CF12 Data Bar, Color Scale e Icon Set, [MS-XLS] exige que o bloco DXF inline esteja vazio. A partir de v2.87.4, HotXLS segue essa regra: as substituições de estilo atribuídas através de Rule.Style não são serializadas para esses três tipos CF12 ao guardar ficheiros .xls. A própria configuração da regra Data Bar / Color Scale / Icon Set continua a ser preservada através da cauda específica do tipo CF12. A saída de formatação condicional XLSX não é afetada
Contentor
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+)
Os ficheiros guardados pelo Excel trazem muitas vezes tanto um CONDFMT de valor de célula do Excel 2003 como um CONDFMT12 do Excel 2007+ a cobrir o mesmo sqref — o registo de valor de célula é uma reserva entre versões que o Excel mais antigo ainda consegue renderizar. O leitor marca a entrada mais antiga com IsShadowed = True depois de detetar uma correspondência exata de caixa delimitadora em TotalRange, para que o código exposto ao utilizador que percorre a coleção de formatação condicional possa ignorar a duplicado. O escritor continua a emitir ambas as famílias de registos ao guardar para compatibilidade entre Excel 2003 ↔ Excel 2007+
Formato de dados
Em SaveAs(xlExcel97) no BIFF8, as regras CF12 emitem CONDFMT12 ($0879) + CF12 ($087A) juntamente com o legado CONDFMT ($01B0) + CF ($01B1) para compatibilidade entre versões com o Excel 2003. O leitor reconhece os registos modernos e expõe-nos através do mesmo modelo de regra em memória, para que ficheiros .xls criados pelo 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;
Consulte também
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (lado XLSX)