TCondFormat / TCondFormatRule و کلاس‌های spec 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 در دسترس است

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

Icon-set family enumeration

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) در نام enum کد می‌شود

Threshold value (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 را می‌توان با استفاده از شاخص تم کتاب‌کار به‌همراه مقدار tint از طریق SetThemeColor(ThemeId, Tint) به‌جای RGB ثابت تنظیم کرد. نویسنده XLSX وقتی Tint دقیقاً 0.0 باشد <color theme="N"/> صادر می‌کند یا وقتی مقدار غیرصفر باشد <color theme="N" tint="0.5"/>، مطابق با خروجی «کوتاه‌ترین فرم» خود Excel. خواننده هر دو ترکیب ویژگی را تجزیه می‌کند و وقتی نه theme و نه tint وجود ندارد، به مسیر RGB rgb= برمی‌گردد. دو حالت برای هر slot متقابلاً انحصاری هستند؛ هر کدام از Set که آخرین‌بار فراخوانی شده باشد برنده می‌شود و IsThemeColor حالت فعال را برای بررسی نشان می‌دهد

CF12 در BIFF8 فقط RGB حل‌شده را ذخیره می‌کند — حالت تم در این نسخه فقط روی backend XLSX رفت‌وبرگشت می‌شود قوانین iconSet هیچ عنصر <color> ندارند، بنابراین افزودن حالت تم روی آن‌ها اثری ندارد

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] فقط برای توقف‌هایی True برمی‌گرداند که صراحتاً با SetIconOverride فعال شده‌اند؛ توقف‌های با آیکون پیش‌فرض همچنان از پیش‌فرض موقعیت توقف خانواده استفاده می‌کنند

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 فقط یکی از DataBar / ColorScale / IconSet ناتهی است، مطابق با Kind قانون. قوانین قدیمی cellIs (غیر CF12) هر سه را تهی می‌گذارند و از Operator_ به‌همراه Formula1 / Formula2 استفاده می‌کنند

ویژگی Style (v2.35.0+) هنگام نخستین خواندن به‌صورت تنبل ایجاد می‌شود؛ شیء برگشتی مالکیتش با خود قانون است و در مخرب آن آزاد می‌شود. از طریق فراخوانی متناظر SetXxx روی Style، HasXxx را تنظیم کنید. خواننده BIFF8 در کنار رمزگشایی به Style، بایت‌های خام را در DxfBlob هم نگه می‌دارد (v2.35.1+)، بنابراین رفت‌وبرگشت load-edit-save هر تغییری را که پس از بارگذاری در Style اعمال شده باشد منعکس می‌کند؛ اگر کاربر به آن دست نزند، فایل ذخیره‌شده همان overrides فایل اصلی را حمل می‌کند

در قوانین Data Bar، Color Scale و Icon Setِ CF12 روی BIFF8، [MS-XLS] می‌خواهد بلوک DXF درون‌خطی خالی باشد. از v2.87.4، HotXLS همین قاعده را دنبال می‌کند: overrideهای سبک که از طریق Rule.Style اختصاص داده می‌شوند، هنگام ذخیره فایل‌های .xls برای آن سه نوع CF12 سریال‌سازی نمی‌شوند. پیکربندی خود قانون Data Bar / Color Scale / Icon Set همچنان از طریق tail مخصوص نوع 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-نسخه shadow detection (v2.37.0+)

فایل‌های ذخیره‌شده توسط Excel اغلب هم یک CONDFMT مقدار سلول Excel 2003 و هم یک CONDFMT12 Excel 2007+ را که همان sqref را پوشش می‌دهند، همراه دارند — رکورد مقدار سلول یک fallback میان‌نسلی است که Excel قدیمی‌تر هنوز می‌تواند رندر کند. خواننده پس از تشخیص یک تطابق دقیق باکس مرزی روی TotalRange، ورودی قدیمی‌تر را با IsShadowed = True علامت می‌زند، بنابراین کدی که از دید کاربر مجموعه قالب‌بندی شرطی را پیمایش می‌کند می‌تواند نسخه تکراری را نادیده بگیرد. نویسنده همچنان هر دو خانواده رکورد را هنگام ذخیره برای سازگاری Excel 2003 ↔ Excel 2007+ صادر می‌کند

Wire format

در SaveAs(xlExcel97) روی BIFF8، قوانین CF12 رکوردهای CONDFMT12 ($0879) + CF12 ($087A) را در کنار CONDFMT ($01B0) + CF ($01B1) قدیمی صادر می‌کنند تا سازگاری میان نسخه‌ها با Excel 2003 حفظ شود. خواننده رکوردهای جدید را تشخیص می‌دهد و آن‌ها را از طریق همان مدل قانون درون‌حافظه‌ای ارائه می‌کند تا فایل‌های .xls ساخته‌شده در Excel با قوانین افزونه بدون از دست رفتن داده رفت‌وبرگشت شوند

مثال

// 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)