TCondFormat / TCondFormatRule
Unit: lxCondFormat
Keluarga pemformatan bersyarat BIFF8 (.xls) yang mendukung aturan ekstensi Excel 2007+. TXLSWorksheet menyimpan koleksi TCondFormat; setiap entri mencakup satu atau beberapa rentang sel dan memuat daftar terurut objek TCondFormatRule, dengan setiap aturan berupa aturan nilai sel legacy atau aturan CF12 Data Bar / Color Scale / Icon Set. Empat titik masuk Sheet.AddCondFormat* (DataBar, ColorScale2, ColorScale3, IconSet) membentuk aturan subtype yang benar. Tersedia sejak v2.34.0
Enumerasi jenis ambang batas
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
Enumerasi keluarga kumpulan ikon
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
17 keluarga ikon dasar Excel 2007. Jumlah stop numerik (3, 4, atau 5) dikodekan di nama enum
Nilai ambang batas (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 data bar
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 warna tema XLSX (v2.43.0+)
Warna isian bar pada aturan Data Bar dan warna per-stop pada aturan Color Scale dapat diatur terhadap indeks tema workbook plus nilai tint melalui SetThemeColor(ThemeId, Tint) alih-alih RGB yang dibekukan. Penulis XLSX menghasilkan <color theme="N"/> saat Tint tepat 0.0 atau <color theme="N" tint="0.5"/> saat tidak nol, mengikuti output "bentuk terpendek" Excel. Pembaca mengurai kedua kombinasi atribut dan kembali ke jalur RGB rgb= saat tidak ada theme maupun tint yang ada. Dua mode saling eksklusif per slot; Set mana pun yang dipanggil terakhir akan menang. IsThemeColor mencerminkan mode aktif untuk pemeriksaan
CF12 BIFF8 hanya menyimpan warna RGB yang terselesaikan — mode tema hanya round-trip di backend XLSX pada rilis ini. Aturan iconSet tidak memiliki elemen <color>, jadi penambahan mode tema tidak memengaruhi mereka
Payload skala warna
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 kumpulan ikon
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;
Override ikon per-stop (v2.44.0+)
Setiap stop di aturan Icon Set dapat menimpa ikon tampilannya dengan ikon apa pun dari salah satu dari 17 keluarga ikon bawaan, diidentifikasi oleh pasangan (OverrideSet, IconId). XLSX menghasilkan <cfIcon iconSet="..." iconId="N"/> untuk setiap stop yang ditimpa. CF12 BIFF8 tetap merender ikon default keluarga karena format wire BIFF8 tidak menyediakan slot untuk override per-stop — ini adalah kemampuan khusus XLSX pada rilis saat ini. HasIconOverride[i] hanya mengembalikan True untuk stop yang secara eksplisit diaktifkan lewat SetIconOverride; stop ikon default terus memakai default posisi stop milik keluarga
Aturan
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;
Tepat satu dari DataBar / ColorScale / IconSet bernilai non-nil per aturan CF12, sesuai dengan Kind aturan. Aturan cellIs legacy (non-CF12) membiarkan ketiganya nil dan memakai Operator_ + Formula1 / Formula2
Properti Style (v2.35.0+) dibuat secara lazy saat pembacaan pertama; objek yang dikembalikan dimiliki oleh aturan dan dibebaskan di destruktornya. Atur HasXxx melalui panggilan SetXxx yang sesuai pada Style. Pembaca BIFF8 menyimpan byte mentah dalam DxfBlob selain mendekodenya ke Style (v2.35.1+), sehingga round-trip muat-edit-simpan akan mencerminkan perubahan Style setelah pemuatan; jika pengguna tidak menyentuhnya, file yang disimpan membawa override yang sama seperti aslinya
Pada aturan Data Bar, Color Scale, dan Icon Set CF12 BIFF8, [MS-XLS] mensyaratkan blok DXF inline kosong. Mulai v2.87.4, HotXLS mengikuti aturan itu: override gaya yang ditetapkan melalui Rule.Style tidak diserialkan untuk tiga jenis CF12 tersebut saat menyimpan file .xls. Konfigurasi aturan Data Bar / Color Scale / Icon Set itu sendiri masih dipertahankan melalui tail khusus jenis CF12. Output pemformatan bersyarat XLSX tidak terpengaruh
Kontainer
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-Versi shadow detection (v2.37.0+)
File buatan Excel sering memuat CONDFMT nilai sel Excel 2003 dan CONDFMT12 Excel 2007+ yang sama-sama mencakup sqref yang sama — record nilai sel adalah fallback lintas-versi yang masih bisa dirender Excel lama. Pembaca menandai entri lama lewat IsShadowed = True setelah mendeteksi kecocokan bounding box yang tepat pada TotalRange, sehingga kode yang iterasi koleksi pemformatan bersyarat dapat melewati duplikat. Penulis tetap menghasilkan kedua keluarga record saat save untuk kompatibilitas Excel 2003 ↔ Excel 2007+
Format kawat
Pada SaveAs(xlExcel97) BIFF8, aturan CF12 menghasilkan record CONDFMT12 ($0879) + CF12 ($087A) bersama CONDFMT ($01B0) + CF ($01B1) legacy untuk kompatibilitas lintas versi dengan Excel 2003. Pembaca mengenali record modern dan mengeksposnya melalui model aturan dalam memori yang sama sehingga file .xls buatan Excel dengan aturan ekstensi tetap round-trip tanpa kehilangan data
Contoh
// 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;
Lihat juga
TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat (sisi XLSX)