SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface IConditionalFormat

    Represents a conditional formatting rule for a range.

    Used for modifying the type and rules of a conditional formatting entry.

    • Conditional formatting rules can be used to highlight, format, or modify cell appearance based on data conditions or criteria.

    • Conditional formatting help users identify patterns, trends, and exceptions in data by applying visual styles dynamically.

    interface IConditionalFormat {
        isIAnchored: true;
        isIConditionalFormat: true;
        addListeners(
            listeners: IConditionalFormat.IListeners,
            options?: IListener.Options,
        ): Remove;
        apply(): void;
        cloneWithUpdate?(updates: U): this;
        close(): void;
        delete(): void;
        getAnchorType?(): IAnchored.Type;
        getCondition(): ICondition<any> | null;
        getCoords(): Readonly<IRange.Coords>;
        getDecorationAt(
            rowIndex: number,
            colIndex: number,
            value: Scalar,
        ): Decoration | null;
        getIndex(): number;
        getName?(): string | null;
        getPropertiesAt(
            rowIndex: number,
            colIndex: number,
            value: Scalar,
        ): Readonly<P>;
        getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
        getScale(): Scale | null;
        getSnapshot(options?: CopyOptions): IConditionalFormat.ISnapshot;
        getStyle(): IStyle.Properties<Serializable> | null;
        isClosed(): boolean;
        isDeleted(): boolean;
        isProtected(): boolean;
        isStopIfTrue(): boolean;
        setCondition(
            condition: Input<any> | null,
            options?: ITransaction.OperationOptions,
        ): this;
        setIndex(index: number): this;
        setRanges(
            address: ICellRanges.Address,
            options?: ITransaction.OperationOptions,
        ): this;
        setStopIfTrue(
            stopIfTrue: boolean,
            options?: ITransaction.OperationOptions,
        ): this;
        toJSON(): IConditionalFormat.JSON | null;
        update(
            properties: IConditionalFormat | IConditionalFormat.Modifiers,
            options?: ITransaction.OperationOptions,
        ): this;
    }

    Hierarchy (View Summary)

    Index
    isIAnchored isIConditionalFormat
    addListeners apply cloneWithUpdate? close delete getAnchorType? getCondition getCoords getDecorationAt getIndex getName? getPropertiesAt getRanges getScale getSnapshot getStyle isClosed isDeleted isProtected isStopIfTrue setCondition setIndex setRanges setStopIfTrue toJSON update
    isIAnchored: true

    For runtime type checking.

    isIConditionalFormat: true

    For runtime type checking.

    • Applies the condition.

      Returns void

    • Creates a new instance of the range with specified updates applied.

      Parameters

      • updates: U

        The updates to apply to the range's properties.

      Returns this

      A new ICellRanged instance with the applied updates.

    • Similar to delete but cleans resources and can't be undone.

      Returns void

    • Deletes the anchored item.

      Returns void

    • Retrieves the coordinates for the range.

      Returns Readonly<IRange.Coords>

      The range's coordinates.

      The coordinates are not the coordinates where this is contained but the coordinates for access getPropertiesAt.

    • Returns what this rule draws in a cell, or null if it draws nothing there.

      Parameters

      • rowIndex: number

        The cell's row.

      • colIndex: number

        The cell's column.

      • value: Scalar

        The cell's value.

      Returns Decoration | null

      The render-side companion to IProperties.ICellRanged.getPropertiesAt: a rule that restyles a cell answers through that, a rule that draws in it answers through this. Only a data bar or an icon set ever returns a decoration — a color scale resolves to a fill and so travels the style path.

      Like getPropertiesAt this is a synchronous read off a prepared cache, never an evaluation: the range-wide domain (min / max / percentile) is resolved asynchronously when values change. A rule whose domain has not resolved yet returns null.

    • Returns the index of this conditional format within its container.

      Returns number

      The index is the evaluation order (index 0 evaluates first). Exported to OOXML as priority = index + 1.

    • The name of the anchor or null if it has none.

      Returns string | null

    • Retrieves the properties associated with a specified cell within the range.

      Parameters

      • rowIndex: number

        The row index within the range.

      • colIndex: number

        The column index within the range.

      • value: Scalar

        The value at the coordinates.

      Returns Readonly<P>

      The properties associated with the specified cell as a read-only object.

    • Returns the ranges this object is anchored to, in authored order.

      Parameters

      Returns ICellRanges

      • Never null. An item whose last range was removed by a row/column delete returns an invalid ranges — ask ICellRanges.isInvalid, the same contract as ITable.getDataRange.
      • This is the general accessor. Most anchored types hold exactly one range and declare their own getRange() for it, but data validations, conditional formats and protected ranges are authored as several, and any single range can become several when a delete splits it.

    • Returns the value→visual mapping for this rule, or null if the rule is a predicate.

      Returns Scale | null

      Color scales, data bars and icon sets are not predicates: they map the whole range's spread of values onto a rendering rather than testing each cell. A rule carries either a IConditionalFormat.getCondition or a scale, never both.

    • Returns if the model has been closed

      Returns boolean

    • Returns if the model has been deleted

      Returns boolean

    • If the anchor is unable to be modified.

      Returns boolean

    • Returns boolean

      IConditionalFormat.setStopIfTrue

      The flag as authored, which is what round-trips — not whether it takes effect. It is a predicate-rule concept: a color scale, data bar or icon set always applies, so it ends nothing, and Excel greys the checkbox out for all three. The attribute is still schema-legal on any cfRule, so a rule can arrive from a file carrying it on a data bar; Excel ignores it there and so does evaluation here. The authored value is kept verbatim rather than rewritten on load, so such a rule round-trips unchanged.

    • Set the condition.

      Parameters

      Returns this

      The condition is the rule's predicate — there is no second, OOXML-shaped representation of it. A rule that maps a range of values onto a visual instead of testing each cell carries a IConditionalFormat.getScale rather than a condition.

    • Sets the index of this conditional format within its container.

      Parameters

      • index: number

        The new index to set.

      Returns this

    • Re-anchors this rule to address, REPLACING every range it currently covers.

      Parameters

      • address: ICellRanges.Address

        The range or ranges to cover — anything ISheet.getRanges accepts ('A1:C20', 'A1:A5, C1:C5', coords). Resolved against this rule's own sheet.

      • Optionaloptions: ITransaction.OperationOptions

        Transaction options; description names the entry in undo history.

      Returns this

      A REPLACE, not an add: the ranges named become the whole anchor. An address that names nothing throws rather than leaving the rule unanchored — clearing is IAnchored.delete.

      Undoable, and refused on a protected sheet. A rule spans several ranges as readily as one; Excel writes them as one sqref, and so do we.

    • Sets whether to stop evaluating additional conditional formatting rules if this rule is true.

      Parameters

      Returns this

      This will only affect formatting rules for the current range or cell.

    • Set multiple properties at the same time.

      Parameters

      Returns this

      Only the keys named are touched. An explicit null clears a key — required when switching a rule between its two shapes, since condition+style and scale are mutually exclusive (setting one side also clears the other unless the caller named both).

      Passing another rule takes its whole definition — every key, cleared where the other rule has none — so the shape switches with it. The anchor is not part of it.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods