TCondFormat / TCondFormatRule та класи специфікацій CF12
Модуль: lxCondFormat
Сімейство умовного форматування BIFF8 (.xls), яке підтримує правила розширень Excel 2007+. TXLSWorksheet зберігає колекцію записів TCondFormat; кожен запис охоплює один або кілька діапазонів клітинок і містить впорядкований список об'єктів TCondFormatRule, де кожне правило є або застарілим правилом значення комірки, або правилом CF12 Data Bar / Color Scale / Icon Set. Чотири точки входу Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) створюють правила правильного підтипу. Доступно з v2.34.0
Перелік видів порогу
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
Перелік сімей наборів іконок
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
17 базових сімейств значків Excel 2007. Кількість числових зупинок (3, 4 або 5) закодована в назві enum
Порогове значення (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;
Корисне навантаження рядка даних
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 туди й назад (v2.43.0+)
Колір заливки смуги для правила Data Bar і кольори окремих зупинок для правила Color Scale можна задавати через індекс теми книги плюс значення tint за допомогою SetThemeColor(ThemeId, Tint) замість фіксованого RGB. Записувач XLSX виводить <color theme="N"/>, коли Tint дорівнює точно 0.0, або <color theme="N" tint="0.5"/>, коли значення не нульове, наслідуючи власний "найкоротший" формат Excel. Читач розбирає обидві комбінації атрибутів і переходить на шлях RGB rgb=, коли немає ні theme, ні tint. Два режими взаємовиключні для кожного слота; перемагає те, що було задано через Set останнім. IsThemeColor відображає активний режим для перевірки
У BIFF8 CF12 зберігається лише розв'язаний колір RGB — у цій версії режим theme проходить туди й назад лише в бекенді XLSX. Правила iconSet не мають елементів <color>, тож додавання режиму theme на них не впливає
Корисне навантаження колірної шкали
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;
Корисне навантаження набору іконок
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;
Переозначення значка окремої зупинки (v2.44.0+)
Кожна зупинка в правилі Icon Set може перевизначити значок відображення будь-яким значком із будь-якого з 17 вбудованих сімейств значків, ідентифікованих парою (OverrideSet, IconId). XLSX виводить <cfIcon iconSet="..." iconId="N"/> для кожної перевизначеної зупинки. BIFF8 CF12 і далі відображає значок за замовчуванням сімейства, бо формат BIFF8 не має місця для перевизначення окремої зупинки — у поточному випуску це можливість лише для XLSX. HasIconOverride[i] повертає True лише для зупинок, які явно увімкнені через SetIconOverride; зупинки з типовим значком і далі використовують значок за замовчуванням для своєї позиції
Правило
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;
Для кожного правила CF12 ненульове лише одне з DataBar / ColorScale / IconSet, що відповідає його Kind. Застарілі правила cellIs (не CF12) лишають усі три значення nil і використовують Operator_ + Formula1 / Formula2
Властивість Style (v2.35.0+) створюється ліниво під час першого читання; повернутий об'єкт належить правилу і звільняється в його деструкторі. Встановлюйте HasXxx через відповідний виклик SetXxx на Style. Читач BIFF8 додатково зберігає сирі байти в DxfBlob поряд із декодуванням у Style (v2.35.1+), тому цикл завантаження-редагування-збереження відображає будь-яку зміну Style після завантаження; якщо користувач його не торкається, збережений файл несе ті самі перевизначення, що й оригінал
У правилах BIFF8 CF12 Data Bar, Color Scale та Icon Set [MS-XLS] вимагає, щоб вбудований блок DXF був порожнім. Починаючи з v2.87.4, HotXLS дотримується цього правила: перевизначення стилю, призначені через Rule.Style, не серіалізуються для цих трьох типів CF12 під час збереження .xls файлів. Саму конфігурацію правил Data Bar / Color Scale / Icon Set і далі зберігають через специфічний для CF12 хвіст. Вивід умовного форматування XLSX не змінюється
Контейнер
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-Версія shadow detection (v2.37.0+)
Файли, збережені Excel, часто містять і Excel 2003 cell-value CONDFMT, і Excel 2007+ CONDFMT12, що охоплюють той самий sqref — запис cell-value є резервом для сумісності між версіями, який старіший Excel і далі може відтворити. Читач позначає старіший запис через IsShadowed = True після виявлення точного збігу меж у TotalRange, тож код користувацького рівня, який ітерує колекцію умовного форматування, може пропустити дубль. Записувач і далі виводить обидва сімейства записів під час збереження для сумісності Excel 2003 ↔ Excel 2007+
Формат проводу
У BIFF8 SaveAs(xlExcel97), правила CF12 виводять записи CONDFMT12 ($0879) + CF12 ($087A) поряд із застарілими CONDFMT ($01B0) + CF ($01B1) для кросверсійної сумісності з Excel 2003. Читач розпізнає сучасні записи й відображає їх через ту саму in-memory модель правил, тож файли .xls, створені Excel і з розширеними правилами, проходять туди й назад без втрати даних
Приклад
// 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;
Дивіться також
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (сторона XLSX)