TCondFormat / TCondFormatRule

ユニット: lxCondFormat

Excel の拡張ルールをサポートする BIFF8 (.xls) の条件付き書式ファミリーです。TXLSWorksheet は TCondFormat エントリのコレクションを保持し、各エントリは 1 つ以上のセル範囲をカバーして TCondFormatRule オブジェクトの順序付きリストを持ちます。各ルールは従来のセル値ルールか CF12 の Data Bar / Color Scale / Icon Set ルールです。4 つの 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;

Data bar payload

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) でブックの theme インデックスと tint 値に対して設定できます。XLSX ライターは、Tint がちょうど 0.0 のときは <color theme="N"/> を、ゼロ以外のときは Excel の "shortest form" 出力に合わせて <color theme="N" tint="0.5"/> を出力します。リーダーは両方の属性組み合わせを解析し、theme も tint もない場合は RGB の rgb= パスにフォールバックします。2 つのモードはスロットごとに排他的で、最後に呼ばれた Set が有効になります。IsThemeColor は検査用にアクティブモードを反映します

BIFF8 CF12 は解決後の RGB 色のみを保存します — このリリースでは theme モードの往復は XLSX バックエンドに限定されます。iconSet ルールには <color> 要素がないため、この theme モード追加の影響はありません

Color scale payload

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 payload

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] は SetIconOverride で明示的に有効化されたストップに対してのみ True を返し、既定アイコンのストップは引き続きそのファミリの既定位置アイコンを使います

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;

各 CF12 ルールで非 nil なのは DataBar / ColorScale / IconSet のうち 1 つだけで、ルールの Kind に対応します。従来の cellIs ルール（非 CF12）では 3 つとも nil のままで、Operator_ と Formula1 / Formula2 を使います

Style プロパティ（v2.35.0 以降）は最初の読み取り時に遅延生成され、返されるオブジェクトはルールが所有し、デストラクタで解放されます。HasXxx は対応する SetXxx 呼び出しで Style に設定します。BIFF8 リーダーはデコードした内容に加えて生のバイト列も DxfBlob に保持し、さらに Style にも展開します（v2.35.1 以降）。そのため、読み込み後に Style を変更すると load-edit-save 往復に反映され、触れなかった場合は元ファイルと同じオーバーライドが保存されます

BIFF8 の CF12 Data Bar、Color Scale、Icon Set ルールでは、[MS-XLS] はインライン DXF ブロックを空にすることを要求します。v2.87.4 以降、HotXLS はこの規則に従い、.xls ファイル保存時に Rule.Style で設定したスタイルオーバーライドをこれら 3 種の CF12 ではシリアル化しません。Data Bar / Color Scale / Icon Set ルール自体は CF12 固有の末尾を通じて引き続き保持されます。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-version shadow detection (v2.37.0+)

Excel で保存されたファイルには、同じ sqref を対象にした Excel 2003 のセル値 CONDFMT と Excel 2007 以降の CONDFMT12 が両方含まれることがよくあります — 古い Excel でも描画できるようにするためのクロスバージョン互換フォールバックです。リーダーは TotalRange で完全な境界ボックス一致を検出したあと、古いエントリに IsShadowed = True を付けるので、条件付き書式コレクションを走査するユーザー向けコードは重複をスキップできます。ライターは保存時に Excel 2003 ↔ Excel 2007 以降の互換性のため、引き続き両方のレコードファミリを出力します

Wire format

BIFF8 の SaveAs(xlExcel97) では、CF12 ルールが CONDFMT12 ($0879) + CF12 ($087A) レコードと、旧来の CONDFMT ($01B0) + CF ($01B1) レコードを併せて出力し、Excel 2003 とのクロスバージョン互換性を確保します。リーダーは新しいレコードを認識し、それらを同じメモリ上のルールモデルとして公開するため、拡張ルールを含む 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;