ws.conditionalFormats

add(ranges: CellRange[], rules: CFRuleInput[]): Promise<string>;

Add a new conditional format with ranges and rules. The API assigns IDs and priorities — callers provide rule configuration only. @param ranges - Cell ranges this format applies to @param rules - Rule inputs (without id/priority) @returns The generated format ID

get(formatId: string): Promise<ConditionalFormat | null>;

Get a conditional format by its ID. @param formatId - Format ID to look up @returns The conditional format, or null if not found

update(formatId: string, updates: ConditionalFormatUpdate): Promise<void>;

Update an existing conditional format. Supports replacing rules, ranges, and setting stopIfTrue on all rules. @param formatId - Format ID to update @param updates - Object with optional rules, ranges, and stopIfTrue

clearRuleStyle(formatId: string, ruleId: string): Promise<void>;

Clear the style of a specific rule within a conditional format, resetting all style properties (font, fill, border, number format) to unset. @param formatId - Format ID containing the rule @param ruleId - Rule ID within the format to clear style for

changeRuleType(formatId: string, ruleId: string, newRule: CFRuleInput): Promise<void>;

Change the type and configuration of a specific rule within a conditional format, preserving its ID and priority. This is the equivalent of OfficeJS's eight changeRuleTo*() methods, unified into one type-safe call using CFRuleInput. @param formatId - Format ID containing the rule @param ruleId - Rule ID to change @param newRule - New rule configuration (type + type-specific fields)

getItemAt(index: number): Promise<ConditionalFormat | null>;

Get a conditional format by its index in the priority-ordered list. @param index - Zero-based index @returns The conditional format at that index, or null if out of bounds

remove(formatId: string): Promise<void>;

Remove a conditional format by ID. @param formatId - Format ID to remove

list(): Promise<ConditionalFormat[]>;

Get all conditional formats on the sheet. @returns Array of conditional format objects

clear(): Promise<void>;

Clear all conditional formats from the sheet.

clearInRanges(ranges: CellRange[]): Promise<void>;

Clear conditional formats that intersect with the given ranges. @param ranges - Ranges to clear conditional formats from

reorder(formatIds: string[]): Promise<void>;

Reorder conditional formats by format ID array (first = highest priority). @param formatIds - Array of format IDs in the desired order

cloneForPaste(
    sourceSheetId: string,
    relativeCFs: Array<{
      rules: any[];
      rangeOffsets: Array<{
        startRowOffset: number;
        startColOffset: number;
        endRowOffset: number;
        endColOffset: number;
      }>;
    }>,
    origin: { row: number; col: number },
    isCut: boolean,
  ): Promise<void>;

Clone conditional formats from source to target with offset. Used by format painter and paste operations. @param sourceSheetId - Source sheet ID (for cut operation reference removal) @param relativeCFs - Relative CF formats with range offsets @param origin - Target paste origin (row, col) @param isCut - Whether this is a cut operation