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 baseline Excel 2007 icon families. numeric stop count (3, 4, 또는 5) 입니다 encoded 안의 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 규칙의 각 중지 색은 고정 RGB 대신 SetThemeColor(ThemeId, Tint)으로 통합 문서 테마 인덱스와 틴트 값을 기준으로 설정할 수 있습니다. XLSX writer는 Tint가 정확히 0.0일 때 <color theme="N"/>를, 0이 아닐 때 <color theme="N" tint="0.5"/>를 내보내며, 이는 Excel의 "shortest form" 출력과 같습니다. reader는 두 속성 조합을 모두 구문 분석하고 theme도 tint도 없으면 RGB rgb= 경로로 되돌아갑니다. 두 모드는 슬롯마다 서로 배타적이며, 마지막에 호출된 Set이 적용됩니다. IsThemeColor는 검사용으로 활성 모드를 반영합니다
BIFF8 CF12는 해석된 RGB 색만 저장합니다 — 이번 릴리스에서는 XLSX 백엔드에서만 테마 모드가 왕복됩니다. iconSet 규칙에는 <color> 요소가 없으므로 테마 모드 추가는 영향을 주지 않습니다
색상 배율 페이로드
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 규칙의 각 중지는 (OverrideSet, IconId) 쌍으로 식별되는 17개 기본 제공 아이콘 패밀리의 아이콘으로 표시 아이콘을 재정의할 수 있습니다. XLSX는 재정의된 각 중지마다 <cfIcon iconSet="..." iconId="N"/>를 내보냅니다. BIFF8 CF12는 BIFF8 와이어 형식에 중지별 재정의용 슬롯이 없으므로 기본 패밀리 아이콘을 계속 렌더링합니다. 따라서 현재 릴리스에서 이 기능은 XLSX 전용입니다. HasIconOverride[i]는 SetIconOverride를 통해 명시적으로 활성화된 중지에 대해서만 True를 반환하며, 기본 아이콘 중지는 계속 패밀리의 기본 중지 위치 아이콘을 사용합니다
규칙
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 중 하나만 CF12 규칙당 nil이 아니며, 규칙의 Kind와 일치합니다. 레거시 cellIs 규칙(CF12 아님)은 셋 모두 nil로 두고 Operator_ + Formula1 / Formula2를 사용합니다
Style 속성(v2.35.0+)은 처음 읽을 때 지연 생성됩니다. 반환된 객체는 규칙이 소유하며 소멸자에서 해제됩니다. Style에서 대응하는 SetXxx 호출로 HasXxx를 설정합니다. BIFF8 reader는 이를 Style로 디코딩하는 것과 별도로 원시 바이트를 DxfBlob에 보관합니다(v2.35.1+). 따라서 로드-수정-저장 왕복은 로드 후 Style에 가한 변경을 반영하며, 사용자가 건드리지 않으면 저장된 파일에는 원본과 같은 오버라이드가 유지됩니다
BIFF8 CF12 Data Bar, Color Scale, Icon Set 규칙에서는 [MS-XLS]가 인라인 DXF 블록을 비워 둘 것을 요구합니다. v2.87.4부터 HotXLS는 이를 따르며, .xls 파일 저장 시 Rule.Style을 통해 지정한 스타일 오버라이드는 이 세 CF12 종류에 대해 직렬화하지 않습니다. 다만 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-version shadow detection (v2.37.0+)
Excel이 저장한 파일에는 같은 sqref를 덮는 Excel 2003 셀 값 CONDFMT와 Excel 2007+ CONDFMT12가 함께 포함되는 경우가 많습니다 — 셀 값 레코드는 이전 Excel도 렌더링할 수 있는 교차 버전 대체 수단입니다. reader는 TotalRange에서 정확한 경계 상자 일치를 감지한 뒤 더 오래된 항목을 IsShadowed = True로 표시하므로 조건부 서식 컬렉션을 순회하는 사용자 코드가 중복 항목을 건너뛸 수 있습니다. writer는 Excel 2003 ↔ Excel 2007+ 호환성을 위해 저장 시 계속 두 레코드 계열을 모두 내보냅니다
와이어 형식
BIFF8 SaveAs(xlExcel97)에서 CF12 규칙은 Excel 2003과의 교차 버전 호환성을 위해 레거시 CONDFMT ($01B0) + CF ($01B1)와 함께 CONDFMT12 ($0879) + CF12 ($087A) 레코드를 내보냅니다. reader는 최신 레코드를 인식해 같은 메모리 내 규칙 모델로 노출하므로 확장 규칙이 포함된 Excel 작성 .xls 파일도 데이터 손실 없이 왕복됩니다
예제
// 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 쪽)