TCondFormat / TCondFormatRule
หน่วย: lxCondFormat
ตระกูลการจัดรูปแบบตามเงื่อนไข BIFF8 (.xls) ที่รองรับกฎส่วนขยายของ Excel 2007+ TXLSWorksheet เก็บคอลเลกชันของรายการ TCondFormat แต่ละรายการครอบคลุมช่วงเซลล์หนึ่งหรือหลายช่วง และเก็บรายการเรียงลำดับของอ็อบเจ็กต์ TCondFormatRule โดยแต่ละกฎเป็นได้ทั้งกฎค่าเซลล์แบบเดิมหรือกฎ CF12 แบบ Data Bar / Color Scale / Icon Set จุดเชื่อมต่อ Sheet.AddCondFormat* ทั้งสี่จุด (DataBar, ColorScale2, ColorScale3, IconSet) จะสร้างกฎชนิดย่อยที่ถูกต้อง มีให้ใช้ตั้งแต่ 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
การแจกแจงตระกูลไอคอน
type
TXLSIconSetType = (
icsArrows3, icsArrows3Gray, icsFlags3,
icsTrafficLights3, icsTrafficLightsRimmed3, icsSigns3,
icsSymbols3, icsSymbolsUncircled3,
icsArrows4, icsArrows4Gray, icsRedToBlack4,
icsRatings4, icsTrafficLights4,
icsArrows5, icsArrows5Gray,
icsRatings5, icsQuarters5);
ตระกูลไอคอนพื้นฐาน 17 แบบของ Excel 2007 ค่า stop count เชิงตัวเลข (3, 4 หรือ 5) ถูกเข้ารหัสไว้ในชื่อ enum
Threshold ค่า (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 และสีของแต่ละ stop บนกฎ Color Scale สามารถตั้งด้วยดัชนีธีมของเวิร์กบุ๊กพร้อมค่าทินต์ผ่าน SetThemeColor(ThemeId, Tint) แทน RGB ที่ตรึงตาย ตัวเขียน XLSX จะปล่อย <color theme="N"/> เมื่อ Tint เท่ากับ 0.0 พอดี หรือ <color theme="N" tint="0.5"/> เมื่อไม่เป็นศูนย์ ซึ่งตรงกับเอาต์พุตรูปแบบสั้นที่สุดของ Excel เอง ตัวอ่านจะแยกวิเคราะห์ทั้งสองชุดแอตทริบิวต์และจะย้อนกลับไปใช้เส้นทาง RGB rgb= เมื่อไม่มี theme หรือ tint อยู่ โหมดทั้งสองเป็นแบบ mutually exclusive ต่อหนึ่งช่อง สิ่งที่ Set ถูกเรียกครั้งล่าสุดจะมีผล IsThemeColor สะท้อนโหมดที่ใช้งานอยู่สำหรับการตรวจสอบ
BIFF8 CF12 เก็บไว้เฉพาะสี RGB ที่คำนวณแล้วเท่านั้น — โหมดธีมจะส่งผ่าน round-trip ได้เฉพาะบนแบ็กเอนด์ XLSX ในรุ่นนี้ iconSet rules ไม่มีองค์ประกอบ <color> จึงไม่ได้รับผลจากการเพิ่มโหมดธีม
เพย์โหลด Color scale
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;
เพย์โหลด Icon set
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;
การแทนที่ไอคอนต่อ stop (v2.44.0+)
แต่ละ stop ในกฎ Icon Set สามารถแทนที่ไอคอนที่แสดงด้วยไอคอนใดก็ได้จากตระกูลไอคอนในตัวทั้ง 17 แบบ โดยระบุด้วยคู่ (OverrideSet, IconId) XLSX จะปล่อย <cfIcon iconSet="..." iconId="N"/> ต่อ stop ที่ถูกแทนที่ BIFF8 CF12 ยังแสดงไอคอนเริ่มต้นของตระกูลต่อไป เพราะรูปแบบสาย BIFF8 ไม่มีช่องสำหรับแทนที่ราย stop — ความสามารถนี้มีเฉพาะ XLSX ในรุ่นปัจจุบัน HasIconOverride[i] จะคืนค่า True เฉพาะ stop ที่ถูกเปิดใช้ผ่าน SetIconOverride อย่างชัดเจน ส่วน stop ที่ใช้ไอคอนเริ่มต้นยังคงใช้ค่าเริ่มต้นตามตำแหน่ง stop ของตระกูล
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;
หนึ่งใน DataBar / ColorScale / IconSet จะเป็น non-nil เพียงตัวเดียวต่อกฎ CF12 ซึ่งตรงกับ Kind ของกฎ กฎ cellIs แบบเก่า (ไม่ใช่ CF12) จะปล่อยทั้งสามเป็น nil และใช้ Operator_ + Formula1 / Formula2
พร็อพเพอร์ตี Style (v2.35.0+) จะถูกสร้างแบบ lazy เมื่ออ่านครั้งแรก วัตถุที่ส่งกลับเป็นของกฎและจะถูกปล่อยใน destructor ตั้งค่า HasXxx ผ่านการเรียก SetXxx ที่เกี่ยวข้องบน Style ตัวอ่าน BIFF8 จะเก็บไบต์ดิบไว้ใน DxfBlob เพิ่มจากการ decode เป็น Style (v2.35.1+) ด้วย ดังนั้นรอบ load-edit-save จะสะท้อนการแก้ไข Style หลังโหลด ถ้าผู้ใช้ไม่แตะต้องมัน ไฟล์ที่บันทึกจะมี overrides เดิมเหมือนไฟล์ต้นฉบับ
บนกฎ BIFF8 CF12 แบบ Data Bar, Color Scale และ Icon Set, [MS-XLS] กำหนดว่า DXF inline block ต้องว่าง ตั้งแต่ v2.87.4 HotXLS จึงทำตามกฎนั้น: การเขียน style overrides ที่กำหนดผ่าน Rule.Style จะไม่ถูก serialize สำหรับ CF12 ทั้งสามชนิดนี้เมื่อบันทึกไฟล์ .xls ตัวกำหนดค่า Data Bar / Color Scale / Icon Set เองยังคงถูกเก็บผ่าน tail เฉพาะชนิดของ CF12 เอาต์พุต conditional-formatting ของ XLSX ไม่ได้รับผล
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-เวอร์ชัน shadow detection (v2.37.0+)
ไฟล์ที่ Excel บันทึกมักมีทั้ง CONDFMT ของ Excel 2003 สำหรับค่าเซลล์และ CONDFMT12 ของ Excel 2007+ ที่ครอบคลุม sqref เดียวกัน — ระเบียนค่าเซลล์เป็น fallback ข้ามเวอร์ชันที่ Excel รุ่นเก่ายังเรนเดอร์ได้ ตัวอ่านจะตั้งค่าสถานะรายการเก่าเป็น IsShadowed = True หลังตรวจพบการตรงกันของ bounding-box แบบเป๊ะบน TotalRange ดังนั้นโค้ดฝั่งผู้ใช้ที่วนคอลเลกชัน conditional-format จึงข้ามรายการซ้ำได้ ตัวเขียนยังคงปล่อยระเบียนทั้งสองตระกูลเมื่อบันทึกเพื่อความเข้ากันได้ระหว่าง Excel 2003 ↔ Excel 2007+
Wire รูปแบบ
บน BIFF8 SaveAs(xlExcel97) กฎ CF12 จะปล่อยระเบียน CONDFMT12 ($0879) + CF12 ($087A) ควบคู่กับ CONDFMT ($01B0) + CF ($01B1) แบบเดิม เพื่อความเข้ากันได้ข้ามเวอร์ชันกับ Excel 2003 ตัวอ่านจะรู้จักระเบียนสมัยใหม่และเปิดเผยผ่านโมเดลกฎในหน่วยความจำแบบเดียวกัน ดังนั้นไฟล์ .xls ที่ Excel สร้างและมี extension rules จะ round-trip ได้โดยไม่สูญเสียข้อมูล
ตัวอย่าง
// 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)