HotXLS Docs

TCondFormat / TCondFormatRule 和 CF12 规范类

单元：lxCondFormat

支持 Excel 2007+ 扩展规则的 BIFF8 (.xls) 条件格式系列。TXLSWorksheet 维护一个 TCondFormat 条目集合；每个条目覆盖 一个或多个单元格区域，并持有 TCondFormatRule 对象的有序列表，每个规则要么是旧式单元格值规则，要么是 CF12 数据条 / 色阶 / 图标集规则。 四个 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+ 数据条
    cfvAutoMax     = 7); // 仅限 Excel 2010+ 数据条

图标集系列枚举

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) 编码在枚举名称中

阈值 (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;       // 数值字面量或公式文本
    property Color: LongWord;         // 色阶停止点的 BGR RGB
    property IsThemeColor: Boolean;    // v2.43.0+ true = 主题模式已激活
    property ThemeColorId: Word;       // v2.43.0+ 主题调色板索引
    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+ — 将条填充选入主题模式
    procedure ClearThemeColor;                            // v2.43.0+ — 还原为 RGB Color
    property Min: TXLSCfValue;
    property Max: TXLSCfValue;
    property Color: LongWord;         // 条填充
    property ShowValue: Boolean;      // false = 隐藏单元格文本
    property MinLength: Byte;         // 0..100 百分比
    property MaxLength: Byte;         // 0..100 百分比
    property IsThemeColor: Boolean;    // v2.43.0+ true = 主题模式已激活
    property ThemeColorId: Word;       // v2.43.0+ 主题调色板索引
    property ThemeColorTint: Single;   // v2.43.0+ -1.0 .. 0.0 .. +1.0
  end;

XLSX 主题色往返 (v2.43.0+)

数据条规则上的条填充颜色和色阶规则上的每个停止点颜色， 可以通过 SetThemeColor(ThemeId, Tint) 而非冻结的 RGB 来设置为工作簿主题索引加上色调值。当 Tint 恰好为 0.0 时，XLSX 写入器发出 <color theme="N"/>；当不为零时发出 <color theme="N" tint="0.5"/>， 与 Excel 自身的"最短形式"输出相匹配。 读取器解析两种属性组合，并在 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 或 3
    property Stops[I: Integer]: TXLSCfValue; default;
  end;

图标集载荷

type
  TXLSIconSetSpec = class
    constructor Create(ASetType: TXLSIconSetType);
    procedure SetThreshold(I: Integer; Kind: TXLSCfValueKind;
      const Value: WideString);
    // 每个停止点的图标覆盖 (v2.44.0+)。
    procedure SetIconOverride(I: Integer;
      OverrideSet: TXLSIconSetType; IconId: Byte);
    procedure ClearIconOverride(I: Integer);
    property SetType: TXLSIconSetType;
    property Reverse: Boolean;        // 反转图标顺序
    property ShowOnly: Boolean;       // true = 仅图标，隐藏单元格文本
    property IconCount: Integer;      // 3、4 或 5（派生自 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+)

图标集规则中的每个停止点都可以用 17 个内置图标系列中任何一个的图标来覆盖其显示图标， 由 (OverrideSet, IconId) 对标识。XLSX 为每个被覆盖的停止点发出 <cfIcon iconSet="..." iconId="N"/>。 BIFF8 CF12 继续渲染系列默认图标，因为 BIFF8 传输格式没有用于逐个停止点覆盖的槽位 — 这是当前版本中仅限 XLSX 的功能。 HasIconOverride[i] 仅对通过 SetIconOverride 显式选入的停止点返回 True；默认图标停止点继续使用该系列的停止位置默认值

规则

type
  TCondFormatRule = class
    property Kind: TXLSCfKind;
    property cfType: Word;            // CF 记录子类型
    property Operator_: Word;         // cellIs 的比较运算符
    property DataBar: TXLSDataBarSpec;       // 对于数据条规则非 nil
    property ColorScale: TXLSColorScaleSpec; // 对于色阶规则非 nil
    property IconSet: TXLSIconSetSpec;       // 对于图标集规则非 nil
    property Style: TXLSDxfStyle;        // DXF 覆盖；惰性创建 (v2.35.0+)
    property DxfBlob: TXLSBlob;       // 来自 Parse 的原始 DXF 字节 (v2.35.0+)
    property Priority: Word;          // CF12 ipriority；0 = 写入器分配 (v2.45.0+)
  end;

每个 CF12 规则中 DataBar / ColorScale / IconSet 中恰好有一个为非 nil，与规则的 Kind 相匹配。旧式 cellIs 规则（非 CF12）将三者全部留为 nil， 并使用 Operator_ + Formula1 / Formula2

Style 属性 (v2.35.0+) 在首次读取时惰性创建； 返回的对象由规则拥有，并在其析构函数中释放。通过在 Style 上调用相应的 SetXxx 来设置 HasXxx。BIFF8 读取器除了将原始字节解码到 Style (v2.35.1+) 之外，还将原始字节保留在 DxfBlob 中，因此加载-编辑-保存往返反映了 Style 的任何加载后修改；如果用户不触及它，则保存的文件携带与原始文件相同的覆盖

在 BIFF8 CF12 数据条、色阶和图标集规则中， [MS-XLS] 要求内联 DXF 块为空。从 v2.87.4 开始， HotXLS 遵循该规则：当保存 .xls 文件时，通过 Rule.Style 分配的样式覆盖不会针对这三种 CF12 类型进行序列化。数据条 / 色阶 / 图标集规则配置本身仍通过 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 = 发出 CONDFMT12/CF12
    property IsShadowed: Boolean;    // v2.37.0+ — 重复的 CONDFMT 标记
    property TotalRange: TCondRange; // v2.37.0+ — 合并范围
  end;

跨版本阴影检测 (v2.37.0+)

Excel 保存的文件通常同时携带覆盖相同 sqref 的 Excel 2003 单元格值 CONDFMT 和 Excel 2007+ CONDFMT12 — 单元格值记录是一个较旧 Excel 仍可渲染的跨版本回退。 读取器在检测到 TotalRange 上精确的边界框匹配后， 通过 IsShadowed = True 标记较旧的条目，因此迭代条件格式集合的面向用户代码可以跳过重复项。写入器在保存时继续发出两个记录系列，以实现 Excel 2003 ↔ Excel 2007+ 兼容性

传输格式

在 BIFF8 SaveAs(xlExcel97) 上，CF12 规则发出 CONDFMT12 ($0879) + CF12 ($087A) 记录，并发出旧式 CONDFMT ($01B0) + CF ($01B1)，以实现与 Excel 2003 的跨版本兼容性。读取器识别现代记录并通过相同的内存中规则模型公开它们，因此带有扩展规则的 Excel 创作 .xls 文件可以在无数据丢失的情况下往返

示例

// 带有自定义最小/最大阈值的数据条。
with Sheet.AddCondFormatDataBar('A1:A10', $00FF0000,
  cfvNumber, '0', cfvNumber, '100').DataBar do
begin
  ShowValue := True;
  MinLength := 10;
  MaxLength := 90;
end;

// 3 箭头图标集，反转使绿色向下指。
with Sheet.AddCondFormatIconSet('B1:B10', icsArrows3).IconSet do
begin
  Reverse  := True;
  ShowOnly := False;
end;

另请参阅

TXLSWorksheet.AddCondFormatDataBar
TXLSWorksheet.AddCondFormatColorScale2
TXLSWorksheet.AddCondFormatColorScale3
TXLSWorksheet.AddCondFormatIconSet
TXLSXConditionalFormat（XLSX 侧）

Copyright © 2010-2026 losLab Software