Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat: supplement facade notes and example (#4756)

wpxp1234562699cb9b6aae
diff --git a/packages/sheets-conditional-formatting/src/facade/conditional-formatting-builder.ts b/packages/sheets-conditional-formatting/src/facade/conditional-formatting-builder.ts
deleted file mode 100644
index ef8b0f5490..0000000000
--- a/packages/sheets-conditional-formatting/src/facade/conditional-formatting-builder.ts
+++ /dev/null
@@ -1,972 +0,0 @@
-/**
- * Copyright 2023-present DreamNum Co., Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-/* eslint-disable ts/explicit-function-return-type */
-
-import type { IRange } from '@univerjs/core';
-import type { CFTimePeriodOperator, IAverageHighlightCell, IColorScale, IConditionalFormattingRuleConfig, IConditionFormattingRule, IDataBar, IDuplicateValuesHighlightCell, IFormulaHighlightCell, IIconSet, INumberHighlightCell, IRankHighlightCell, ITextHighlightCell, ITimePeriodHighlightCell, IUniqueValuesHighlightCell, IValueConfig } from '@univerjs/sheets-conditional-formatting';
-import { BooleanNumber, ColorKit, Tools } from '@univerjs/core';
-import { CFNumberOperator, CFRuleType, CFSubRuleType, CFTextOperator, CFValueType, createCfId, EMPTY_ICON_TYPE, iconMap } from '@univerjs/sheets-conditional-formatting';
-
-/**
- * @ignore
- * @hideconstructor
- */
-class ConditionalFormatRuleBaseBuilder {
- protected _rule: Partial<IConditionFormattingRule> = {};
-
- protected get _ruleConfig() {
- return this._rule.rule || null;
- }
-
- protected _getDefaultConfig(type: CFRuleType = CFRuleType.highlightCell): IConditionalFormattingRuleConfig {
- switch (type) {
- case CFRuleType.colorScale: {
- return {
- type,
- config: [
- { index: 0, color: new ColorKit('').toRgbString(), value: { type: CFValueType.min } },
- { index: 0, color: new ColorKit('green').toRgbString(), value: { type: CFValueType.max } }],
- } as IColorScale;
- }
- case CFRuleType.dataBar: {
- return {
- type, isShowValue: true,
- config: { min: { type: CFValueType.min }, max: { type: CFValueType.max }, positiveColor: new ColorKit('green').toRgbString(), nativeColor: new ColorKit('').toRgbString(), isGradient: false },
- } as IDataBar;
- }
- case CFRuleType.highlightCell: {
- return {
- type,
- subType: CFSubRuleType.text,
- operator: CFTextOperator.containsText,
- value: 'abc',
- style: {},
- } as ITextHighlightCell;
- }
- case CFRuleType.iconSet: {
- return {
- type,
- isShowValue: true,
- config: [{
- operator: CFNumberOperator.greaterThanOrEqual, value: { type: CFValueType.min },
- iconType: EMPTY_ICON_TYPE, iconId: '',
- },
- {
- operator: CFNumberOperator.greaterThanOrEqual, value: { type: CFValueType.percentile, value: 0.5 },
- iconType: EMPTY_ICON_TYPE, iconId: '',
- },
- {
- operator: CFNumberOperator.lessThanOrEqual, value: { type: CFValueType.max },
- iconType: EMPTY_ICON_TYPE, iconId: '',
- }],
- } as IIconSet;
- }
- }
- }
-
- constructor(initRule: Partial<IConditionFormattingRule> = {}) {
- this._rule = initRule;
- this._ensureAttr(this._rule, ['rule']);
- }
-
- // eslint-disable-next-line ts/no-explicit-any
- protected _ensureAttr(obj: Record<string, any>, keys: string[]) {
- keys.reduce((pre, cur) => {
- if (!pre[cur]) {
- pre[cur] = {};
- }
- return pre[cur];
- }, obj);
- return obj;
- }
-
- build(): IConditionFormattingRule {
- if (!this._rule.cfId) {
- this._rule.cfId = createCfId();
- }
- if (!this._rule.ranges) {
- this._rule.ranges = [];
- }
- if (this._rule.stopIfTrue === undefined) {
- this._rule.stopIfTrue = false;
- }
- if (!this._rule.rule?.type) {
- this._rule.rule!.type = CFRuleType.highlightCell;
- this._ensureAttr(this._rule, ['rule', 'style']);
- }
- const defaultConfig = this._getDefaultConfig(this._rule.rule!.type);
- const result = { ...this._rule, rule: { ...defaultConfig, ...this._rule.rule } } as IConditionFormattingRule;
- return result;
- }
-
- /**
- * Deep clone a current builder.
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- copy() {
- return new ConditionalFormatRuleBaseBuilder(Tools.deepClone(this._rule));
- }
-
- /**
- * Gets the scope of the current conditional format
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- getRanges() {
- return this._rule.ranges || [];
- }
-
- /**
- * Get the icon set mapping dictionary
- */
- getIconMap() {
- return iconMap;
- }
-
- /**
- * Create a conditional format ID.
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- createCfId() {
- return createCfId();
- }
-
- /**
- * Sets the scope for conditional formatting
- * @param {IRange[]} ranges
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setRanges(ranges: IRange[]) {
- this._rule.ranges = ranges;
- return this;
- }
-}
-
-/**
- * @hideconstructor
- */
-class ConditionalFormatHighlightRuleBuilder extends ConditionalFormatRuleBaseBuilder {
- constructor(initConfig: Partial<IConditionFormattingRule> = {}) {
- super(initConfig);
- this._ensureAttr(this._rule, ['rule', 'style']);
- }
-
- override copy(): ConditionalFormatHighlightRuleBuilder {
- return new ConditionalFormatHighlightRuleBuilder(Tools.deepClone(this._rule));
- }
-
- /**
- * Set average rule
- * @param {IAverageHighlightCell['operator']} operator
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setAverage(operator: IAverageHighlightCell['operator']) {
- const ruleConfig = this._ruleConfig as IAverageHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.average;
- ruleConfig.operator = operator;
- return this;
- }
-
- /**
- * Set uniqueValues rule
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setUniqueValues() {
- const ruleConfig = this._ruleConfig as IUniqueValuesHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.uniqueValues;
- return this;
- }
-
- /**
- * Set duplicateValues rule
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setDuplicateValues() {
- const ruleConfig = this._ruleConfig as IDuplicateValuesHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.duplicateValues;
- return this;
- }
-
- /**
- * Set rank rule
- * @param {{ isBottom: boolean, isPercent: boolean, value: number }} config
- * @param config.isBottom
- * @param config.isPercent
- * @param config.value
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setRank(config: { isBottom: boolean; isPercent: boolean; value: number }) {
- const ruleConfig = this._ruleConfig as IRankHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.rank;
- ruleConfig.isBottom = config.isBottom;
- ruleConfig.isPercent = config.isPercent;
- ruleConfig.value = config.value;
- return this;
- }
-
- /**
- * Sets the background color
- * @param {string} [color]
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setBackground(color?: string) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- if (color) {
- this._ensureAttr(this._ruleConfig, ['style', 'bg']);
- const colorKit = new ColorKit(color);
- this._ruleConfig.style!.bg!.rgb = colorKit.toRgbString();
- } else {
- delete this._ruleConfig.style.bg;
- }
- }
- return this;
- }
-
- /**
- * Set Bold
- * @param {boolean} isBold
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setBold(isBold: boolean) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- this._ensureAttr(this._ruleConfig, ['style']);
-
- this._ruleConfig.style.bl = isBold ? BooleanNumber.TRUE : BooleanNumber.FALSE;
- }
- return this;
- }
-
- /**
- * Sets the font color
- * @param {string} [color]
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setFontColor(color?: string) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- if (color) {
- const colorKit = new ColorKit(color);
- this._ensureAttr(this._ruleConfig, ['style', 'cl']);
- this._ruleConfig.style!.cl!.rgb = colorKit.toRgbString();
- } else {
- delete this._ruleConfig.style.cl;
- }
- }
- return this;
- }
-
- /**
- * Set the text to italic
- * @param {boolean} isItalic
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setItalic(isItalic: boolean) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- this._ensureAttr(this._ruleConfig, ['style']);
- this._ruleConfig.style.it = isItalic ? BooleanNumber.TRUE : BooleanNumber.FALSE;
- }
- return this;
- }
-
- /**
- * Set the strikethrough
- * @param {boolean} isStrikethrough
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setStrikethrough(isStrikethrough: boolean) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- this._ensureAttr(this._ruleConfig, ['style', 'st']);
- this._ruleConfig.style.st!.s = isStrikethrough ? BooleanNumber.TRUE : BooleanNumber.FALSE;
- }
- return this;
- }
-
- /**
- * Set the underscore
- * @param {boolean} isUnderline
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setUnderline(isUnderline: boolean) {
- if (this._ruleConfig?.type === CFRuleType.highlightCell) {
- this._ensureAttr(this._ruleConfig, ['style', 'ul']);
- this._ruleConfig.style.ul!.s = isUnderline ? BooleanNumber.TRUE : BooleanNumber.FALSE;
- }
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the cell is empty.
- */
- whenCellEmpty() {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = '';
- ruleConfig.operator = CFTextOperator.equal;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the cell is not empty
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- whenCellNotEmpty() {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = '';
- ruleConfig.operator = CFTextOperator.notEqual;
- return this;
- }
-
- /**
- * Highlight when the date is in a time period, custom time is not supported.
- * @param {CFTimePeriodOperator} date
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- whenDate(date: CFTimePeriodOperator) {
- const ruleConfig = this._ruleConfig as ITimePeriodHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.timePeriod;
- ruleConfig.operator = date;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when a given formula evaluates to true.
- * @param {string} formulaString formulaString start with' = '
- * @memberof ConditionalFormatRuleBuilder
- */
- whenFormulaSatisfied(formulaString: string) {
- const ruleConfig = this._ruleConfig as IFormulaHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.formula;
- ruleConfig.value = formulaString;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when a number is between two specified values or equal to one of them.
- * @param {number} start
- * @param {number} end
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberBetween(start: number, end: number) {
- const min = Math.min(start, end);
- const max = Math.max(start, end);
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = [min, max];
- ruleConfig.operator = CFNumberOperator.between;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the number equals the given value
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberEqualTo(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.equal;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the number is greater than the given value
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberGreaterThan(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.greaterThan;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when a number is greater than or equal to a given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberGreaterThanOrEqualTo(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.greaterThanOrEqual;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when the number is less than the given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberLessThan(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.lessThan;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the value is less than or equal to the given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberLessThanOrEqualTo(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.lessThanOrEqual;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when a number is not between two specified values and is not equal to them.
- * @param {number} start
- * @param {number} end
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberNotBetween(start: number, end: number) {
- const min = Math.min(start, end);
- const max = Math.max(start, end);
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = [min, max];
- ruleConfig.operator = CFNumberOperator.notBetween;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when a number does not equal a given value.
- * @param value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberNotEqualTo(value: number) {
- const ruleConfig = this._ruleConfig as INumberHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.number;
- ruleConfig.value = value;
- ruleConfig.operator = CFNumberOperator.notEqual;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input contains the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextContains(text: string) {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = text;
- ruleConfig.operator = CFTextOperator.containsText;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when the input does not contain the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextDoesNotContain(text: string) {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = text;
- ruleConfig.operator = CFTextOperator.notContainsText;
- return this;
- }
-
- /**
- * Sets a conditional formatting rule to fire when input ends with a specified value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextEndsWith(text: string) {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = text;
- ruleConfig.operator = CFTextOperator.endsWith;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input equals the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextEqualTo(text: string) {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = text;
- ruleConfig.operator = CFTextOperator.equal;
- return this;
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input value begins with the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextStartsWith(text: string) {
- const ruleConfig = this._ruleConfig as ITextHighlightCell;
- ruleConfig.type = CFRuleType.highlightCell;
- ruleConfig.subType = CFSubRuleType.text;
- ruleConfig.value = text;
- ruleConfig.operator = CFTextOperator.beginsWith;
- return this;
- }
-}
-class ConditionalFormatDataBarRuleBuilder extends ConditionalFormatRuleBaseBuilder {
- override copy(): ConditionalFormatDataBarRuleBuilder {
- return new ConditionalFormatDataBarRuleBuilder(Tools.deepClone(this._rule));
- }
-
- /**
- * Data bar settings
- * @param {{
- * min: IValueConfig;
- * max: IValueConfig;
- * isGradient?: boolean;
- * positiveColor: string;
- * nativeColor: string;
- * isShowValue?: boolean;
- * }} config
- * @param config.min
- * @param config.max
- * @param config.isGradient
- * @param config.positiveColor
- * @param config.nativeColor
- * @param config.isShowValue
- * @memberof ConditionalFormatRuleBuilder
- */
- setDataBar(config: {
- min: IValueConfig;
- max: IValueConfig;
- isGradient?: boolean;
- positiveColor: string;
- nativeColor: string;
- isShowValue?: boolean;
- }) {
- const ruleConfig = this._ruleConfig as IDataBar;
- ruleConfig.type = CFRuleType.dataBar;
- ruleConfig.isShowValue = !!config.isShowValue;
- ruleConfig.config = {
- min: config.min,
- max: config.max,
- positiveColor: config.positiveColor,
- nativeColor: config.nativeColor,
- isGradient: !!config.isGradient,
- };
- return this;
- }
-}
-
-class ConditionalFormatColorScaleRuleBuilder extends ConditionalFormatRuleBaseBuilder {
- override copy(): ConditionalFormatColorScaleRuleBuilder {
- return new ConditionalFormatColorScaleRuleBuilder(Tools.deepClone(this._rule));
- }
-
- /**
- * Color scale set
- * @param {{ index: number; color: string; value: IValueConfig }[]} config
- * @memberof ConditionalFormatRuleBuilder
- */
- setColorScale(config: IColorScale['config']) {
- const ruleConfig = this._ruleConfig as IColorScale;
- ruleConfig.type = CFRuleType.colorScale;
- ruleConfig.config = config;
- return this;
- }
-}
-
-class ConditionalFormatIconSetRuleBuilder extends ConditionalFormatRuleBaseBuilder {
- override copy(): ConditionalFormatIconSetRuleBuilder {
- return new ConditionalFormatIconSetRuleBuilder(Tools.deepClone(this._rule));
- }
-
- /**
- *
- * Icon Set
- * @param {{ iconConfigs: IIconSet['config'], isShowValue: boolean }} config
- * @param config.iconConfigs
- * @param config.isShowValue
- * @memberof ConditionalFormatRuleBuilder
- */
- setIconSet(config: { iconConfigs: IIconSet['config']; isShowValue: boolean }) {
- const ruleConfig = this._ruleConfig as IIconSet;
- ruleConfig.type = CFRuleType.iconSet;
- ruleConfig.config = config.iconConfigs;
- ruleConfig.isShowValue = config.isShowValue;
- return this;
- }
-}
-
-/**
- * @hideconstructor
- */
-export class FConditionalFormattingBuilder {
- constructor(private _initConfig: { ranges?: IRange[] } = {}) {
-
- }
-
- /**
- * Constructs a conditional format rule from the settings applied to the builder.
- * @returns {IConditionFormattingRule} The conditional format rule.
- * @example
- * ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorksheet = fWorkbook.getActiveSheet();
- * const rule = fWorksheet.newConditionalFormattingRule().build();
- * fWorksheet.setConditionalFormattingRules([rule]);
- * ```
- */
- build(): IConditionFormattingRule {
- return new ConditionalFormatRuleBaseBuilder(this._initConfig).build();
- }
-
- /**
- * Set average rule
- * @param {IAverageHighlightCell['operator']} operator
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setAverage(operator: IAverageHighlightCell['operator']) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setAverage(operator);
- }
-
- /**
- * Set uniqueValues rule
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setUniqueValues() {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setUniqueValues();
- }
-
- /**
- * Set duplicateValues rule
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setDuplicateValues() {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setDuplicateValues();
- }
-
- /**
- * Set rank rule
- * @param {{ isBottom: boolean, isPercent: boolean, value: number }} config
- * @param config.isBottom
- * @param config.isPercent
- * @param config.value
- * @memberof ConditionalFormatHighlightRuleBuilder
- */
- setRank(config: { isBottom: boolean; isPercent: boolean; value: number }) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setRank(config);
- }
-
- /**
- *
- * Set iconSet rule
- * @param {{ iconConfigs: IIconSet['config'], isShowValue: boolean }} config
- * @param config.iconConfigs
- * @param config.isShowValue
- * @memberof ConditionalFormatRuleBuilder
- */
- setIconSet(config: { iconConfigs: IIconSet['config']; isShowValue: boolean }) {
- return new ConditionalFormatIconSetRuleBuilder(this._initConfig).setIconSet(config);
- }
-
- /**
- * Set colorScale rule
- * @param {{ index: number; color: string; value: IValueConfig }[]} config
- * @memberof ConditionalFormatRuleBuilder
- */
- setColorScale(config: IColorScale['config']) {
- return new ConditionalFormatColorScaleRuleBuilder(this._initConfig).setColorScale(config);
- }
-
- /**
- * Set dataBar rule
- * @param {{
- * min: IValueConfig;
- * max: IValueConfig;
- * isGradient?: boolean;
- * positiveColor: string;
- * nativeColor: string;
- * isShowValue?: boolean;
- * }} config
- * @param config.min
- * @param config.max
- * @param config.isGradient
- * @param config.positiveColor
- * @param config.nativeColor
- * @param config.isShowValue
- * @memberof ConditionalFormatRuleBuilder
- */
- setDataBar(config: {
- min: IValueConfig;
- max: IValueConfig;
- isGradient?: boolean;
- positiveColor: string;
- nativeColor: string;
- isShowValue?: boolean;
- }) {
- return new ConditionalFormatDataBarRuleBuilder(this._initConfig).setDataBar(config);
- }
-
- /**
- * Sets the background color
- * @param {string} [color]
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setBackground(color?: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setBackground(color);
- }
-
- /**
- * Set Bold
- * @param {boolean} isBold
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setBold(isBold: boolean) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setBold(isBold);
- }
-
- /**
- * Sets the font color
- * @param {string} [color]
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setFontColor(color?: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setFontColor(color);
- }
-
- /**
- * Set the text to italic
- * @param {boolean} isItalic
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setItalic(isItalic: boolean) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setItalic(isItalic);
- }
-
- /**
- * Set the strikethrough
- * @param {boolean} isStrikethrough
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setStrikethrough(isStrikethrough: boolean) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setStrikethrough(isStrikethrough);
- }
-
- /**
- * Set the underscore
- * @param {boolean} isUnderline
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- setUnderline(isUnderline: boolean) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setUnderline(isUnderline);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the cell is empty.
- */
- whenCellEmpty() {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenCellEmpty();
- }
-
- /**
- * Sets the conditional formatting rule to fire when the cell is not empty
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- whenCellNotEmpty() {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenCellNotEmpty();
- }
-
- /**
- * Highlight when the date is in a time period, custom time is not supported.
- * @param {CFTimePeriodOperator} date
- * @returns {*}
- * @memberof ConditionalFormatRuleBuilder
- */
- whenDate(date: CFTimePeriodOperator) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenDate(date);
- }
-
- /**
- * Sets a conditional formatting rule to fire when a given formula evaluates to true.
- * @param {string} formulaString formulaString start with' = '
- * @memberof ConditionalFormatRuleBuilder
- */
- whenFormulaSatisfied(formulaString: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenFormulaSatisfied(formulaString);
- }
-
- /**
- * Sets the conditional formatting rule to fire when a number is between two specified values or equal to one of them.
- * @param {number} start
- * @param {number} end
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberBetween(start: number, end: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberBetween(start, end);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the number equals the given value
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberEqualTo(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberEqualTo(value);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the number is greater than the given value
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberGreaterThan(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberGreaterThan(value);
- }
-
- /**
- * Sets a conditional formatting rule to fire when a number is greater than or equal to a given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberGreaterThanOrEqualTo(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberGreaterThanOrEqualTo(value);
- }
-
- /**
- * Sets a conditional formatting rule to fire when the number is less than the given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberLessThan(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberLessThan(value);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the value is less than or equal to the given value.
- * @param {number} value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberLessThanOrEqualTo(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberLessThanOrEqualTo(value);
- }
-
- /**
- * Sets a conditional formatting rule to fire when a number is not between two specified values and is not equal to them.
- * @param {number} start
- * @param {number} end
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberNotBetween(start: number, end: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberNotBetween(start, end);
- }
-
- /**
- * Sets the conditional formatting rule to fire when a number does not equal a given value.
- * @param value
- * @memberof ConditionalFormatRuleBuilder
- */
- whenNumberNotEqualTo(value: number) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberNotEqualTo(value);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input contains the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextContains(text: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextContains(text);
- }
-
- /**
- * Sets a conditional formatting rule to fire when the input does not contain the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextDoesNotContain(text: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextDoesNotContain(text);
- }
-
- /**
- * Sets a conditional formatting rule to fire when input ends with a specified value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextEndsWith(text: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextEndsWith(text);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input equals the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextEqualTo(text: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextEqualTo(text);
- }
-
- /**
- * Sets the conditional formatting rule to fire when the input value begins with the given value.
- * @param {string} text
- * @memberof ConditionalFormatRuleBuilder
- */
- whenTextStartsWith(text: string) {
- return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextStartsWith(text);
- }
-}
diff --git a/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts b/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts
new file mode 100644
index 0000000000..d11763cc8f
--- /dev/null
+++ b/packages/sheets-conditional-formatting/src/facade/f-conditional-formatting-builder.ts
@@ -0,0 +1,2045 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* eslint-disable ts/explicit-function-return-type */
+
+import type { IRange } from '@univerjs/core';
+import type { CFTimePeriodOperator, IAverageHighlightCell, IColorScale, IConditionalFormattingRuleConfig, IConditionFormattingRule, IDataBar, IDuplicateValuesHighlightCell, IFormulaHighlightCell, IIconSet, INumberHighlightCell, IRankHighlightCell, ITextHighlightCell, ITimePeriodHighlightCell, IUniqueValuesHighlightCell, IValueConfig } from '@univerjs/sheets-conditional-formatting';
+import { BooleanNumber, ColorKit, Tools } from '@univerjs/core';
+import { CFNumberOperator, CFRuleType, CFSubRuleType, CFTextOperator, CFValueType, createCfId, EMPTY_ICON_TYPE, iconMap } from '@univerjs/sheets-conditional-formatting';
+
+/**
+ * @ignore
+ * @hideconstructor
+ */
+class ConditionalFormatRuleBaseBuilder {
+ protected _rule: Partial<IConditionFormattingRule> = {};
+
+ protected get _ruleConfig() {
+ return this._rule.rule || null;
+ }
+
+ protected _getDefaultConfig(type: CFRuleType = CFRuleType.highlightCell): IConditionalFormattingRuleConfig {
+ switch (type) {
+ case CFRuleType.colorScale: {
+ return {
+ type,
+ config: [
+ { index: 0, color: new ColorKit('').toRgbString(), value: { type: CFValueType.min } },
+ { index: 0, color: new ColorKit('green').toRgbString(), value: { type: CFValueType.max } }],
+ } as IColorScale;
+ }
+ case CFRuleType.dataBar: {
+ return {
+ type, isShowValue: true,
+ config: { min: { type: CFValueType.min }, max: { type: CFValueType.max }, positiveColor: new ColorKit('green').toRgbString(), nativeColor: new ColorKit('').toRgbString(), isGradient: false },
+ } as IDataBar;
+ }
+ case CFRuleType.highlightCell: {
+ return {
+ type,
+ subType: CFSubRuleType.text,
+ operator: CFTextOperator.containsText,
+ value: 'abc',
+ style: {},
+ } as ITextHighlightCell;
+ }
+ case CFRuleType.iconSet: {
+ return {
+ type,
+ isShowValue: true,
+ config: [{
+ operator: CFNumberOperator.greaterThanOrEqual, value: { type: CFValueType.min },
+ iconType: EMPTY_ICON_TYPE, iconId: '',
+ },
+ {
+ operator: CFNumberOperator.greaterThanOrEqual, value: { type: CFValueType.percentile, value: 0.5 },
+ iconType: EMPTY_ICON_TYPE, iconId: '',
+ },
+ {
+ operator: CFNumberOperator.lessThanOrEqual, value: { type: CFValueType.max },
+ iconType: EMPTY_ICON_TYPE, iconId: '',
+ }],
+ } as IIconSet;
+ }
+ }
+ }
+
+ constructor(initRule: Partial<IConditionFormattingRule> = {}) {
+ this._rule = initRule;
+ this._ensureAttr(this._rule, ['rule']);
+ }
+
+ // eslint-disable-next-line ts/no-explicit-any
+ protected _ensureAttr(obj: Record<string, any>, keys: string[]) {
+ keys.reduce((pre, cur) => {
+ if (!pre[cur]) {
+ pre[cur] = {};
+ }
+ return pre[cur];
+ }, obj);
+ return obj;
+ }
+
+ /**
+ * Constructs a conditional format rule from the settings applied to the builder.
+ * @returns {IConditionFormattingRule} The conditional format rule.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ build(): IConditionFormattingRule {
+ if (!this._rule.cfId) {
+ this._rule.cfId = createCfId();
+ }
+ if (!this._rule.ranges) {
+ this._rule.ranges = [];
+ }
+ if (this._rule.stopIfTrue === undefined) {
+ this._rule.stopIfTrue = false;
+ }
+ if (!this._rule.rule?.type) {
+ this._rule.rule!.type = CFRuleType.highlightCell;
+ this._ensureAttr(this._rule, ['rule', 'style']);
+ }
+ const defaultConfig = this._getDefaultConfig(this._rule.rule!.type);
+ const result = { ...this._rule, rule: { ...defaultConfig, ...this._rule.rule } } as IConditionFormattingRule;
+ return result;
+ }
+
+ /**
+ * Deep clone a current builder.
+ * @returns {ConditionalFormatRuleBaseBuilder} A new builder with the same settings as the original.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(builder.build());
+ *
+ * // Copy the rule and change the background color to green for the range A1:B2.
+ * const newRange = fWorksheet.getRange('A1:B2');
+ * const newBuilder = builder.copy()
+ * .setBackground('#00FF00')
+ * .setRanges([newRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(newBuilder.build());
+ * ```
+ */
+ copy(): ConditionalFormatRuleBaseBuilder {
+ const newRule = Tools.deepClone(this._rule);
+ if (newRule.cfId) {
+ newRule.cfId = createCfId();
+ }
+ return new ConditionalFormatRuleBaseBuilder(newRule);
+ }
+
+ /**
+ * Gets the scope of the current conditional format.
+ * @returns {IRange[]} The ranges to which the conditional format applies.
+ */
+ getRanges(): IRange[] {
+ return this._rule.ranges || [];
+ }
+
+ /**
+ * Get the icon set mapping dictionary.
+ * @returns {Record<string, string[]>} The icon set mapping dictionary.
+ */
+ getIconMap(): Record<string, string[]> {
+ return iconMap;
+ }
+
+ /**
+ * Create a conditional format ID.
+ * @returns {string} The conditional format ID.
+ */
+ createCfId(): string {
+ return createCfId();
+ }
+
+ /**
+ * Sets the scope for conditional formatting.
+ * @param {IRange[]} ranges - The ranges to which the conditional format applies.
+ * @returns {ConditionalFormatRuleBaseBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setRanges(ranges: IRange[]) {
+ this._rule.ranges = ranges;
+ return this;
+ }
+}
+
+/**
+ * @hideconstructor
+ */
+class ConditionalFormatHighlightRuleBuilder extends ConditionalFormatRuleBaseBuilder {
+ constructor(initConfig: Partial<IConditionFormattingRule> = {}) {
+ super(initConfig);
+ this._ensureAttr(this._rule, ['rule', 'style']);
+ }
+
+ /**
+ * Deep clone a current builder.
+ * @returns {ConditionalFormatHighlightRuleBuilder} A new builder with the same settings as the original.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(builder.build());
+ *
+ * // Copy the rule and change the background color to green for the range A1:B2.
+ * const newRange = fWorksheet.getRange('A1:B2');
+ * const newBuilder = builder.copy()
+ * .setBackground('#00FF00')
+ * .setRanges([newRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(newBuilder.build());
+ * ```
+ */
+ override copy(): ConditionalFormatHighlightRuleBuilder {
+ const newRule = Tools.deepClone(this._rule);
+ if (newRule.cfId) {
+ newRule.cfId = createCfId();
+ }
+ return new ConditionalFormatHighlightRuleBuilder(newRule);
+ }
+
+ /**
+ * Set average rule.
+ * @param {IAverageHighlightCell['operator']} operator - The operator to use for the average rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with greater than average values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setAverage(univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setAverage(operator: IAverageHighlightCell['operator']): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as IAverageHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.average;
+ ruleConfig.operator = operator;
+ return this;
+ }
+
+ /**
+ * Set unique values rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with unique values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setUniqueValues()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setUniqueValues(): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as IUniqueValuesHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.uniqueValues;
+ return this;
+ }
+
+ /**
+ * Set duplicate values rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with duplicate values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setDuplicateValues()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setDuplicateValues(): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as IDuplicateValuesHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.duplicateValues;
+ return this;
+ }
+
+ /**
+ * Set rank rule.
+ * @param {{ isBottom: boolean, isPercent: boolean, value: number }} config - The rank rule settings.
+ * @param {boolean} config.isBottom - Whether to highlight the bottom rank.
+ * @param {boolean} config.isPercent - Whether to use a percentage rank.
+ * @param {number} config.value - The rank value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights the bottom 10% of values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setRank({ isBottom: true, isPercent: true, value: 10 })
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setRank(config: { isBottom: boolean; isPercent: boolean; value: number }): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as IRankHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.rank;
+ ruleConfig.isBottom = config.isBottom;
+ ruleConfig.isPercent = config.isPercent;
+ ruleConfig.value = config.value;
+ return this;
+ }
+
+ /**
+ * Sets the background color for the conditional format rule's format.
+ * @param {string} [color] - The background color to set. If not provided, the background color is removed.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setBackground(color?: string): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ if (color) {
+ this._ensureAttr(this._ruleConfig, ['style', 'bg']);
+ const colorKit = new ColorKit(color);
+ this._ruleConfig.style!.bg!.rgb = colorKit.toRgbString();
+ } else {
+ delete this._ruleConfig.style.bg;
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Sets text bolding for the conditional format rule's format.
+ * @param {boolean} isBold - Whether to bold the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setBold(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setBold(isBold: boolean): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ this._ensureAttr(this._ruleConfig, ['style']);
+
+ this._ruleConfig.style.bl = isBold ? BooleanNumber.TRUE : BooleanNumber.FALSE;
+ }
+ return this;
+ }
+
+ /**
+ * Sets the font color for the conditional format rule's format.
+ * @param {string} [color] - The font color to set. If not provided, the font color is removed.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that changes the font color to red for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setFontColor('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setFontColor(color?: string): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ if (color) {
+ const colorKit = new ColorKit(color);
+ this._ensureAttr(this._ruleConfig, ['style', 'cl']);
+ this._ruleConfig.style!.cl!.rgb = colorKit.toRgbString();
+ } else {
+ delete this._ruleConfig.style.cl;
+ }
+ }
+ return this;
+ }
+
+ /**
+ * Sets text italics for the conditional format rule's format.
+ * @param {boolean} isItalic - Whether to italicize the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that italicizes the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setItalic(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setItalic(isItalic: boolean): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ this._ensureAttr(this._ruleConfig, ['style']);
+ this._ruleConfig.style.it = isItalic ? BooleanNumber.TRUE : BooleanNumber.FALSE;
+ }
+ return this;
+ }
+
+ /**
+ * Sets text strikethrough for the conditional format rule's format.
+ * @param {boolean} isStrikethrough - Whether is strikethrough the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that set text strikethrough for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setStrikethrough(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setStrikethrough(isStrikethrough: boolean): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ this._ensureAttr(this._ruleConfig, ['style', 'st']);
+ this._ruleConfig.style.st!.s = isStrikethrough ? BooleanNumber.TRUE : BooleanNumber.FALSE;
+ }
+ return this;
+ }
+
+ /**
+ * Sets text underlining for the conditional format rule's format.
+ * @param {boolean} isUnderline - Whether to underline the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that underlines the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setUnderline(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setUnderline(isUnderline: boolean): ConditionalFormatHighlightRuleBuilder {
+ if (this._ruleConfig?.type === CFRuleType.highlightCell) {
+ this._ensureAttr(this._ruleConfig, ['style', 'ul']);
+ this._ruleConfig.style.ul!.s = isUnderline ? BooleanNumber.TRUE : BooleanNumber.FALSE;
+ }
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when the cell is empty.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenCellEmpty(): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = '';
+ ruleConfig.operator = CFTextOperator.equal;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when the cell is not empty.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that changes the font color to red for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setFontColor('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenCellNotEmpty(): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = '';
+ ruleConfig.operator = CFTextOperator.notEqual;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a time period is met.
+ * @param {CFTimePeriodOperator} date - The time period to check for.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with dates in the last 7 days in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenDate(univerAPI.Enum.ConditionFormatTimePeriodOperatorEnum.last7Days)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenDate(date: CFTimePeriodOperator): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITimePeriodHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.timePeriod;
+ ruleConfig.operator = date;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the given formula evaluates to `true`.
+ * @param {string} formulaString - A custom formula that evaluates to true if the input is valid. formulaString start with '='.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenFormulaSatisfied('=A1>10')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenFormulaSatisfied(formulaString: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as IFormulaHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.formula;
+ ruleConfig.value = formulaString;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number falls between, or is either of, two specified values.
+ * @param {number} start - The lowest acceptable value.
+ * @param {number} end - The highest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values between 10 and 20 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberBetween(10, 20)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberBetween(start: number, end: number): ConditionalFormatHighlightRuleBuilder {
+ const min = Math.min(start, end);
+ const max = Math.max(start, end);
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = [min, max];
+ ruleConfig.operator = CFNumberOperator.between;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is equal to the given value.
+ * @param {number} value - The sole acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.equal;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is greater than the given value.
+ * @param {number} value - The highest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberGreaterThan(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberGreaterThan(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.greaterThan;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is greater than or equal to the given value.
+ * @param {number} value - The lowest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than or equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberGreaterThanOrEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberGreaterThanOrEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.greaterThanOrEqual;
+ return this;
+ }
+
+ /**
+ * Sets the conditional conditional format rule to trigger when a number less than the given value.
+ * @param {number} value - The lowest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values less than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberLessThan(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberLessThan(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.lessThan;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number less than or equal to the given value.
+ * @param {number} value - The highest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values less than or equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberLessThanOrEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberLessThanOrEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.lessThanOrEqual;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number does not fall between, and is neither of, two specified values.
+ * @param {number} start - The lowest unacceptable value.
+ * @param {number} end - The highest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values not between 10 and 20 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberNotBetween(10, 20)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberNotBetween(start: number, end: number): ConditionalFormatHighlightRuleBuilder {
+ const min = Math.min(start, end);
+ const max = Math.max(start, end);
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = [min, max];
+ ruleConfig.operator = CFNumberOperator.notBetween;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is not equal to the given value.
+ * @param {number} value - The sole unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values not equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberNotEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberNotEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as INumberHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.number;
+ ruleConfig.value = value;
+ ruleConfig.operator = CFNumberOperator.notEqual;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input contains the given value.
+ * @param {string} text - The value that the input must contain.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text containing 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextContains('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextContains(text: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = text;
+ ruleConfig.operator = CFTextOperator.containsText;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input does not contain the given value.
+ * @param {string} text - The value that the input must not contain.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text not containing 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextDoesNotContain('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextDoesNotContain(text: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = text;
+ ruleConfig.operator = CFTextOperator.notContainsText;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input ends with the given value.
+ * @param {string} text - Text to compare against the end of the string.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text ending with '.ai' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextEndsWith('.ai')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextEndsWith(text: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = text;
+ ruleConfig.operator = CFTextOperator.endsWith;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input is equal to the given value.
+ * @param {string} text - The sole acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text equal to 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextEqualTo('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextEqualTo(text: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = text;
+ ruleConfig.operator = CFTextOperator.equal;
+ return this;
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input starts with the given value.
+ * @param {string} text - Text to compare against the beginning of the string.
+ * @returns {ConditionalFormatHighlightRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text starting with 'https://' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextStartsWith('https://')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextStartsWith(text: string): ConditionalFormatHighlightRuleBuilder {
+ const ruleConfig = this._ruleConfig as ITextHighlightCell;
+ ruleConfig.type = CFRuleType.highlightCell;
+ ruleConfig.subType = CFSubRuleType.text;
+ ruleConfig.value = text;
+ ruleConfig.operator = CFTextOperator.beginsWith;
+ return this;
+ }
+}
+
+class ConditionalFormatDataBarRuleBuilder extends ConditionalFormatRuleBaseBuilder {
+ /**
+ * Deep clone a current builder.
+ * @returns {ConditionalFormatDataBarRuleBuilder} A new instance of the builder with the same settings as the original.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a data bar to cells with values between -100 and 100 in the range A1:D10.
+ * // positive values are green and negative values are red.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule()
+ * .setDataBar({
+ * min: { type: 'num', value: -100 },
+ * max: { type: 'num', value: 100 },
+ * positiveColor: '#00FF00',
+ * nativeColor: '#FF0000',
+ * isShowValue: true
+ * })
+ * .setRanges([fRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(builder.build());
+ *
+ * // Copy the rule and apply it to a new range.
+ * const newRange = fWorksheet.getRange('F1:F10');
+ * const newBuilder = builder.copy()
+ * .setRanges([newRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(newBuilder.build());
+ * ```
+ */
+ override copy(): ConditionalFormatDataBarRuleBuilder {
+ const newRule = Tools.deepClone(this._rule);
+ if (newRule.cfId) {
+ newRule.cfId = createCfId();
+ }
+ return new ConditionalFormatDataBarRuleBuilder(newRule);
+ }
+
+ /**
+ * Set data bar rule.
+ * @param {{
+ * min: IValueConfig;
+ * max: IValueConfig;
+ * isGradient?: boolean;
+ * positiveColor: string;
+ * nativeColor: string;
+ * isShowValue?: boolean;
+ * }} config - The data bar rule settings.
+ * @param {IValueConfig} config.min - The minimum value for the data bar.
+ * @param {IValueConfig} config.max - The maximum value for the data bar.
+ * @param {boolean} [config.isGradient] - Whether the data bar is gradient.
+ * @param {string} config.positiveColor - The color for positive values.
+ * @param {string} config.nativeColor - The color for negative values.
+ * @param {boolean} [config.isShowValue] - Whether to show the value in the cell.
+ * @returns {ConditionalFormatDataBarRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a data bar to cells with values between -100 and 100 in the range A1:D10.
+ * // positive values are green and negative values are red.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setDataBar({
+ * min: { type: 'num', value: -100 },
+ * max: { type: 'num', value: 100 },
+ * positiveColor: '#00FF00',
+ * nativeColor: '#FF0000',
+ * isShowValue: true
+ * })
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setDataBar(config: {
+ min: IValueConfig;
+ max: IValueConfig;
+ isGradient?: boolean;
+ positiveColor: string;
+ nativeColor: string;
+ isShowValue?: boolean;
+ }): ConditionalFormatDataBarRuleBuilder {
+ const ruleConfig = this._ruleConfig as IDataBar;
+ ruleConfig.type = CFRuleType.dataBar;
+ ruleConfig.isShowValue = !!config.isShowValue;
+ ruleConfig.config = {
+ min: config.min,
+ max: config.max,
+ positiveColor: config.positiveColor,
+ nativeColor: config.nativeColor,
+ isGradient: !!config.isGradient,
+ };
+ return this;
+ }
+}
+
+class ConditionalFormatColorScaleRuleBuilder extends ConditionalFormatRuleBaseBuilder {
+ /**
+ * Deep clone a current builder.
+ * @returns {ConditionalFormatColorScaleRuleBuilder} A new instance of the builder with the same settings as the original.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a color scale to cells with values between 0 and 100 in the range A1:D10.
+ * // The color scale is green for 0, yellow for 50, and red for 100.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule()
+ * .setColorScale([
+ * { index: 0, color: '#00FF00', value: { type: 'num', value: 0 } },
+ * { index: 1, color: '#FFFF00', value: { type: 'num', value: 50 } },
+ * { index: 2, color: '#FF0000', value: { type: 'num', value: 100 } }
+ * ])
+ * .setRanges([fRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(builder.build());
+ *
+ * // Copy the rule and apply it to a new range.
+ * const newRange = fWorksheet.getRange('F1:F10');
+ * const newBuilder = builder.copy()
+ * .setRanges([newRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(newBuilder.build());
+ * ```
+ */
+ override copy(): ConditionalFormatColorScaleRuleBuilder {
+ const newRule = Tools.deepClone(this._rule);
+ if (newRule.cfId) {
+ newRule.cfId = createCfId();
+ }
+ return new ConditionalFormatColorScaleRuleBuilder(newRule);
+ }
+
+ /**
+ * Set color scale rule.
+ * @param {{ index: number; color: string; value: IValueConfig }[]} config - The color scale rule settings.
+ * @param {number} config.index - The index of the color scale configuration.
+ * @param {string} config.color - The color corresponding to the index of the color scale configuration.
+ * @param {IValueConfig} config.value - The condition value corresponding to the index of the color scale configuration.
+ * @returns {ConditionalFormatColorScaleRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a color scale to cells with values between 0 and 100 in the range A1:D10.
+ * // The color scale is green for 0, yellow for 50, and red for 100.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setColorScale([
+ * { index: 0, color: '#00FF00', value: { type: 'num', value: 0 } },
+ * { index: 1, color: '#FFFF00', value: { type: 'num', value: 50 } },
+ * { index: 2, color: '#FF0000', value: { type: 'num', value: 100 } }
+ * ])
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setColorScale(config: IColorScale['config']): ConditionalFormatColorScaleRuleBuilder {
+ const ruleConfig = this._ruleConfig as IColorScale;
+ ruleConfig.type = CFRuleType.colorScale;
+ ruleConfig.config = config;
+ return this;
+ }
+}
+
+class ConditionalFormatIconSetRuleBuilder extends ConditionalFormatRuleBaseBuilder {
+ /**
+ * Deep clone a current builder.
+ * @returns {ConditionalFormatIconSetRuleBuilder} A new instance of the builder with the same settings as the original.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a 3-arrow icon set conditional formatting rule in the range A1:D10.
+ * // The first arrow is green for values greater than 20.
+ * // The second arrow is yellow for values greater than 10.
+ * // The third arrow is red for values less than or equal to 10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule()
+ * .setIconSet({
+ * iconConfigs: [
+ * { iconType: '3Arrows', iconId: '0', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 20 } },
+ * { iconType: '3Arrows', iconId: '1', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 10 } },
+ * { iconType: '3Arrows', iconId: '2', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.lessThanOrEqual, value: { type: 'num', value: 10 } }
+ * ],
+ * isShowValue: true,
+ * })
+ * .setRanges([fRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(builder.build());
+ *
+ * // Copy the rule and apply it to a new range.
+ * const newRange = fWorksheet.getRange('F1:F10');
+ * const newBuilder = builder.copy()
+ * .setRanges([newRange.getRange()]);
+ * fWorksheet.addConditionalFormattingRule(newBuilder.build());
+ * ```
+ */
+ override copy(): ConditionalFormatIconSetRuleBuilder {
+ const newRule = Tools.deepClone(this._rule);
+ if (newRule.cfId) {
+ newRule.cfId = createCfId();
+ }
+ return new ConditionalFormatIconSetRuleBuilder(newRule);
+ }
+
+ /**
+ * Set up icon set conditional formatting rule.
+ * @param {{ iconConfigs: IIconSet['config'], isShowValue: boolean }} config - The icon set conditional formatting rule settings.
+ * @param {IIconSet['config']} config.iconConfigs - The icon configurations. iconId property is a string indexing of a group icons.
+ * @param {boolean} config.isShowValue - Whether to show the value in the cell.
+ * @returns {ConditionalFormatIconSetRuleBuilder} This builder for chaining.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a 3-arrow icon set conditional formatting rule in the range A1:D10.
+ * // The first arrow is green for values greater than 20.
+ * // The second arrow is yellow for values greater than 10.
+ * // The third arrow is red for values less than or equal to 10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule();
+ * console.log(builder.getIconMap()); // icons key-value map
+ * const rule = builder.setIconSet({
+ * iconConfigs: [
+ * { iconType: '3Arrows', iconId: '0', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 20 } },
+ * { iconType: '3Arrows', iconId: '1', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 10 } },
+ * { iconType: '3Arrows', iconId: '2', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.lessThanOrEqual, value: { type: 'num', value: 10 } }
+ * ],
+ * isShowValue: true,
+ * })
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setIconSet(config: { iconConfigs: IIconSet['config']; isShowValue: boolean }): ConditionalFormatIconSetRuleBuilder {
+ const ruleConfig = this._ruleConfig as IIconSet;
+ ruleConfig.type = CFRuleType.iconSet;
+ ruleConfig.config = config.iconConfigs;
+ ruleConfig.isShowValue = config.isShowValue;
+ return this;
+ }
+}
+
+/**
+ * @hideconstructor
+ */
+export class FConditionalFormattingBuilder {
+ constructor(private _initConfig: { ranges?: IRange[] } = {}) {
+
+ }
+
+ /**
+ * Constructs a conditional format rule from the settings applied to the builder.
+ * @returns {IConditionFormattingRule} The conditional format rule.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberGreaterThan(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ build(): IConditionFormattingRule {
+ return new ConditionalFormatRuleBaseBuilder(this._initConfig).build();
+ }
+
+ /**
+ * Set average rule.
+ * @param {IAverageHighlightCell['operator']} operator - The operator to use for the average rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with greater than average values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setAverage(univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setAverage(operator: IAverageHighlightCell['operator']): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setAverage(operator);
+ }
+
+ /**
+ * Set unique values rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with unique values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setUniqueValues()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setUniqueValues(): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setUniqueValues();
+ }
+
+ /**
+ * Set duplicate values rule.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with duplicate values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setDuplicateValues()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setDuplicateValues(): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setDuplicateValues();
+ }
+
+ /**
+ * Set rank rule.
+ * @param {{ isBottom: boolean, isPercent: boolean, value: number }} config - The rank rule settings.
+ * @param {boolean} config.isBottom - Whether to highlight the bottom rank.
+ * @param {boolean} config.isPercent - Whether to use a percentage rank.
+ * @param {number} config.value - The rank value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights the bottom 10% of values in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setRank({ isBottom: true, isPercent: true, value: 10 })
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setRank(config: { isBottom: boolean; isPercent: boolean; value: number }): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setRank(config);
+ }
+
+ /**
+ * Get the icon set mapping dictionary.
+ * @returns {Record<string, string[]>} The icon set mapping dictionary.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * console.log(fWorksheet.newConditionalFormattingRule().getIconMap()); // icons key-value map
+ * ```
+ */
+ getIconMap(): Record<string, string[]> {
+ return iconMap;
+ }
+
+ /**
+ * Set up icon set conditional formatting rule.
+ * @param {{ iconConfigs: IIconSet['config'], isShowValue: boolean }} config - The icon set conditional formatting rule settings.
+ * @param {IIconSet['config']} config.iconConfigs - The icon configurations. iconId property is a string indexing of a group icons.
+ * @param {boolean} config.isShowValue - Whether to show the value in the cell.
+ * @returns {ConditionalFormatIconSetRuleBuilder} The conditional format icon set rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a 3-arrow icon set conditional formatting rule in the range A1:D10.
+ * // The first arrow is green for values greater than 20.
+ * // The second arrow is yellow for values greater than 10.
+ * // The third arrow is red for values less than or equal to 10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const builder = fWorksheet.newConditionalFormattingRule();
+ * console.log(builder.getIconMap()); // icons key-value map
+ * const rule = builder.setIconSet({
+ * iconConfigs: [
+ * { iconType: '3Arrows', iconId: '0', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 20 } },
+ * { iconType: '3Arrows', iconId: '1', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.greaterThan, value: { type: 'num', value: 10 } },
+ * { iconType: '3Arrows', iconId: '2', operator: univerAPI.Enum.ConditionFormatNumberOperatorEnum.lessThanOrEqual, value: { type: 'num', value: 10 } }
+ * ],
+ * isShowValue: true,
+ * })
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setIconSet(config: { iconConfigs: IIconSet['config']; isShowValue: boolean }): ConditionalFormatIconSetRuleBuilder {
+ return new ConditionalFormatIconSetRuleBuilder(this._initConfig).setIconSet(config);
+ }
+
+ /**
+ * Set color scale rule.
+ * @param {{ index: number; color: string; value: IValueConfig }[]} config - The color scale rule settings.
+ * @param {number} config.index - The index of the color scale.
+ * @param {string} config.color - The color for the color scale.
+ * @param {IValueConfig} config.value - The value for the color scale.
+ * @returns {ConditionalFormatColorScaleRuleBuilder} The conditional format color scale rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a color scale to cells with values between 0 and 100 in the range A1:D10.
+ * // The color scale is green for 0, yellow for 50, and red for 100.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setColorScale([
+ * { index: 0, color: '#00FF00', value: { type: 'num', value: 0 } },
+ * { index: 1, color: '#FFFF00', value: { type: 'num', value: 50 } },
+ * { index: 2, color: '#FF0000', value: { type: 'num', value: 100 } }
+ * ])
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setColorScale(config: IColorScale['config']): ConditionalFormatColorScaleRuleBuilder {
+ return new ConditionalFormatColorScaleRuleBuilder(this._initConfig).setColorScale(config);
+ }
+
+ /**
+ * Set data bar rule.
+ * @param {{
+ * min: IValueConfig;
+ * max: IValueConfig;
+ * isGradient?: boolean;
+ * positiveColor: string;
+ * nativeColor: string;
+ * isShowValue?: boolean;
+ * }} config - The data bar rule settings.
+ * @param {IValueConfig} config.min - The minimum value for the data bar.
+ * @param {IValueConfig} config.max - The maximum value for the data bar.
+ * @param {boolean} [config.isGradient] - Whether the data bar is gradient.
+ * @param {string} config.positiveColor - The color for positive values.
+ * @param {string} config.nativeColor - The color for negative values.
+ * @param {boolean} [config.isShowValue] - Whether to show the value in the cell.
+ * @returns {ConditionalFormatDataBarRuleBuilder} The conditional format data bar rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that adds a data bar to cells with values between -100 and 100 in the range A1:D10.
+ * // positive values are green and negative values are red.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .setDataBar({
+ * min: { type: 'num', value: -100 },
+ * max: { type: 'num', value: 100 },
+ * positiveColor: '#00FF00',
+ * nativeColor: '#FF0000',
+ * isShowValue: true
+ * })
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setDataBar(config: {
+ min: IValueConfig;
+ max: IValueConfig;
+ isGradient?: boolean;
+ positiveColor: string;
+ nativeColor: string;
+ isShowValue?: boolean;
+ }): ConditionalFormatDataBarRuleBuilder {
+ return new ConditionalFormatDataBarRuleBuilder(this._initConfig).setDataBar(config);
+ }
+
+ /**
+ * Sets the background color for the conditional format rule's format.
+ * @param {string} [color] - The background color to set. If not provided, the background color is removed.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setBackground(color?: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setBackground(color);
+ }
+
+ /**
+ * Sets text bolding for the conditional format rule's format.
+ * @param {boolean} isBold - Whether to bold the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setBold(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setBold(isBold: boolean): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setBold(isBold);
+ }
+
+ /**
+ * Sets the font color for the conditional format rule's format.
+ * @param {string} [color] - The font color to set. If not provided, the font color is removed.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that changes the font color to red for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setFontColor('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setFontColor(color?: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setFontColor(color);
+ }
+
+ /**
+ * Sets text italics for the conditional format rule's format.
+ * @param {boolean} isItalic - Whether to italicize the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that italicizes the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setItalic(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setItalic(isItalic: boolean): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setItalic(isItalic);
+ }
+
+ /**
+ * Sets text strikethrough for the conditional format rule's format.
+ * @param {boolean} isStrikethrough - Whether is strikethrough the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that set text strikethrough for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setStrikethrough(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setStrikethrough(isStrikethrough: boolean): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setStrikethrough(isStrikethrough);
+ }
+
+ /**
+ * Sets text underlining for the conditional format rule's format.
+ * @param {boolean} isUnderline - Whether to underline the text.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that underlines the text for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setUnderline(true)
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ setUnderline(isUnderline: boolean): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).setUnderline(isUnderline);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when the cell is empty.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with no content in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellEmpty()
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenCellEmpty(): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenCellEmpty();
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when the cell is not empty.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that changes the font color to red for cells with not empty content in the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenCellNotEmpty()
+ * .setFontColor('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenCellNotEmpty(): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenCellNotEmpty();
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a time period is met.
+ * @param {CFTimePeriodOperator} date - The time period to check for.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with dates in the last 7 days in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenDate(univerAPI.Enum.ConditionFormatTimePeriodOperatorEnum.last7Days)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenDate(date: CFTimePeriodOperator): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenDate(date);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the given formula evaluates to `true`.
+ * @param {string} formulaString - A custom formula that evaluates to true if the input is valid. formulaString start with '='.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenFormulaSatisfied('=A1>10')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenFormulaSatisfied(formulaString: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenFormulaSatisfied(formulaString);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number falls between, or is either of, two specified values.
+ * @param {number} start - The lowest acceptable value.
+ * @param {number} end - The highest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values between 10 and 20 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberBetween(10, 20)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberBetween(start: number, end: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberBetween(start, end);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is equal to the given value.
+ * @param {number} value - The sole acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberEqualTo(value);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is greater than the given value.
+ * @param {number} value - The highest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberGreaterThan(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberGreaterThan(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberGreaterThan(value);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is greater than or equal to the given value.
+ * @param {number} value - The lowest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values greater than or equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberGreaterThanOrEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberGreaterThanOrEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberGreaterThanOrEqualTo(value);
+ }
+
+ /**
+ * Sets the conditional conditional format rule to trigger when a number less than the given value.
+ * @param {number} value - The lowest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values less than 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberLessThan(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberLessThan(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberLessThan(value);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number less than or equal to the given value.
+ * @param {number} value - The highest acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values less than or equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberLessThanOrEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberLessThanOrEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberLessThanOrEqualTo(value);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number does not fall between, and is neither of, two specified values.
+ * @param {number} start - The lowest unacceptable value.
+ * @param {number} end - The highest unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values not between 10 and 20 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberNotBetween(10, 20)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberNotBetween(start: number, end: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberNotBetween(start, end);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when a number is not equal to the given value.
+ * @param {number} value - The sole unacceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with values not equal to 10 in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenNumberNotEqualTo(10)
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenNumberNotEqualTo(value: number): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenNumberNotEqualTo(value);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input contains the given value.
+ * @param {string} text - The value that the input must contain.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text containing 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextContains('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextContains(text: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextContains(text);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input does not contain the given value.
+ * @param {string} text - The value that the input must not contain.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text not containing 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextDoesNotContain('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextDoesNotContain(text: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextDoesNotContain(text);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input ends with the given value.
+ * @param {string} text - Text to compare against the end of the string.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text ending with '.ai' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextEndsWith('.ai')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextEndsWith(text: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextEndsWith(text);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input is equal to the given value.
+ * @param {string} text - The sole acceptable value.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text equal to 'apple' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextEqualTo('apple')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextEqualTo(text: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextEqualTo(text);
+ }
+
+ /**
+ * Sets the conditional format rule to trigger when that the input starts with the given value.
+ * @param {string} text - Text to compare against the beginning of the string.
+ * @returns {ConditionalFormatHighlightRuleBuilder} The conditional format highlight rule builder.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that highlights cells with text starting with 'https://' in red for the range A1:D10.
+ * const fRange = fWorksheet.getRange('A1:D10');
+ * const rule = fWorksheet.newConditionalFormattingRule()
+ * .whenTextStartsWith('https://')
+ * .setBackground('#FF0000')
+ * .setRanges([fRange.getRange()])
+ * .build();
+ * fWorksheet.addConditionalFormattingRule(rule);
+ * ```
+ */
+ whenTextStartsWith(text: string): ConditionalFormatHighlightRuleBuilder {
+ return new ConditionalFormatHighlightRuleBuilder(this._initConfig).whenTextStartsWith(text);
+ }
+}
diff --git a/packages/sheets-conditional-formatting/src/facade/f-enum.ts b/packages/sheets-conditional-formatting/src/facade/f-enum.ts
new file mode 100644
index 0000000000..1780fe3063
--- /dev/null
+++ b/packages/sheets-conditional-formatting/src/facade/f-enum.ts
@@ -0,0 +1,50 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { FEnum } from '@univerjs/core/facade';
+import { CFNumberOperator, CFTimePeriodOperator } from '@univerjs/sheets-conditional-formatting';
+
+/**
+ * @ignore
+ */
+export interface IFSheetsConditionalFormattingEnum {
+ /**
+ * Conditional formatting number operator
+ */
+ ConditionFormatNumberOperatorEnum: typeof CFNumberOperator;
+
+ /**
+ * Conditional formatting time period operator
+ */
+ ConditionFormatTimePeriodOperatorEnum: typeof CFTimePeriodOperator;
+}
+
+export class FSheetsConditionalFormattingEnum implements IFSheetsConditionalFormattingEnum {
+ get ConditionFormatNumberOperatorEnum(): typeof CFNumberOperator {
+ return CFNumberOperator;
+ }
+
+ get ConditionFormatTimePeriodOperatorEnum(): typeof CFTimePeriodOperator {
+ return CFTimePeriodOperator;
+ }
+}
+
+FEnum.extend(FSheetsConditionalFormattingEnum);
+declare module '@univerjs/core/facade' {
+ // eslint-disable-next-line ts/naming-convention
+ export interface FEnum extends IFSheetsConditionalFormattingEnum {
+ }
+}
diff --git a/packages/sheets-conditional-formatting/src/facade/f-range.ts b/packages/sheets-conditional-formatting/src/facade/f-range.ts
index 113c25ec3e..d1d0905a5e 100644
--- a/packages/sheets-conditional-formatting/src/facade/f-range.ts
+++ b/packages/sheets-conditional-formatting/src/facade/f-range.ts
@@ -25,28 +25,30 @@ import type {
} from '@univerjs/sheets-conditional-formatting';
import { Rectangle } from '@univerjs/core';
import {
- AddConditionalRuleMutation,
+ AddCfCommand,
ClearRangeCfCommand,
ConditionalFormattingRuleModel,
- DeleteConditionalRuleMutation,
- MoveConditionalRuleMutation,
- SetConditionalRuleMutation,
+ DeleteCfCommand,
+ MoveCfCommand,
+ SetCfCommand,
} from '@univerjs/sheets-conditional-formatting';
import { FRange } from '@univerjs/sheets/facade';
-import { FConditionalFormattingBuilder } from './conditional-formatting-builder';
+import { FConditionalFormattingBuilder } from './f-conditional-formatting-builder';
/**
* @ignore
*/
export interface IFRangeConditionalFormattingMixin {
/**
- * Gets all the conditional formatting for the current range
- * @returns {IConditionFormattingRule[]} conditional formatting rules for the current range
+ * Gets all the conditional formatting for the current range.
+ * @returns {IConditionFormattingRule[]} conditional formatting rules for the current range.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100.
* const fRange = fWorksheet.getRange('A1:T100');
* const rule = fWorksheet.newConditionalFormattingRule()
* .whenCellNotEmpty()
@@ -57,6 +59,7 @@ export interface IFRangeConditionalFormattingMixin {
* .build();
* fWorksheet.addConditionalFormattingRule(rule);
*
+ * // Get all the conditional formatting rules for the range F6:H8.
* const targetRange = fWorksheet.getRange('F6:H8');
* const rules = targetRange.getConditionalFormattingRules();
* console.log(rules);
@@ -71,6 +74,8 @@ export interface IFRangeConditionalFormattingMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100.
* const fRange = fWorksheet.getRange('A1:T100');
* const rule = fRange.createConditionalFormattingRule()
* .whenCellNotEmpty()
@@ -86,6 +91,7 @@ export interface IFRangeConditionalFormattingMixin {
/**
* Add a new conditional format
+ * @deprecated use same API in FWorkSheet.
* @param {IConditionFormattingRule} rule
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
@@ -94,52 +100,31 @@ export interface IFRangeConditionalFormattingMixin {
/**
* Delete conditional format according to `cfId`
+ * @deprecated use same API in FWorkSheet.
* @param {string} cfId
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
- * @example
- * ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook?.getActiveSheet();
- * const rules = worksheet?.getConditionalFormattingRules();
- * worksheet?.deleteConditionalFormattingRule(rules![0].cfId);
- * ```
*/
deleteConditionalFormattingRule(cfId: string): FRange;
/**
* Modify the priority of the conditional format
+ * @deprecated use same API in FWorkSheet.
* @param {string} cfId Rules that need to be moved
* @param {string} toCfId Target rule
* @param {IAnchor['type']} [type] After the default move to the destination rule, if type = before moves to the front, the default value is after
* @returns {FRange} Returns the current range instance for method chaining
* @memberof FRangeConditionalFormattingMixin
- * @example
- * ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook?.getActiveSheet();
- * const rules = worksheet?.getConditionalFormattingRules()!;
- * const rule = rules[2];
- * const targetRule = rules[0];
- * worksheet?.moveConditionalFormattingRule(rule.cfId, targetRule.cfId, 'before');
- * ```
*/
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): FRange;
/**
* Set the conditional format according to `cfId`
+ * @deprecated use same API in FWorkSheet.
* @param {string} cfId
* @param {IConditionFormattingRule} rule
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
- * @example
- * ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook?.getActiveSheet();
- * const rules = worksheet?.getConditionalFormattingRules()!;
- * const rule = rules[0];
- * worksheet?.setConditionalFormattingRule(rule.cfId, { ...rule, ranges: [] });
- * ```
*/
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FRange;
@@ -147,6 +132,16 @@ export interface IFRangeConditionalFormattingMixin {
* Clear the conditional rules for the range.
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:T100');
+ *
+ * // Clear all conditional format rules for the range
+ * fRange.clearConditionalFormatRules();
+ * console.log(fRange.getConditionalFormattingRules()); // []
+ * ```
*/
clearConditionalFormatRules(): FRange;
}
@@ -167,37 +162,43 @@ export class FRangeConditionalFormattingMixin extends FRange implements IFRangeC
override addConditionalFormattingRule(rule: IConditionFormattingRule): FRange {
const params: IAddConditionalRuleMutationParams = {
- rule, unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
+ unitId: this._workbook.getUnitId(),
+ subUnitId: this._worksheet.getSheetId(),
+ rule,
};
- this._commandService.syncExecuteCommand(AddConditionalRuleMutation.id, params);
+ this._commandService.syncExecuteCommand(AddCfCommand.id, params);
return this;
}
override deleteConditionalFormattingRule(cfId: string): FRange {
const params: IDeleteConditionalRuleMutationParams = {
- unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
+ unitId: this._workbook.getUnitId(),
+ subUnitId: this._worksheet.getSheetId(),
cfId,
};
- this._commandService.syncExecuteCommand(DeleteConditionalRuleMutation.id, params);
+ this._commandService.syncExecuteCommand(DeleteCfCommand.id, params);
return this;
}
override moveConditionalFormattingRule(cfId: string, toCfId: string, type: IAnchor['type'] = 'after'): FRange {
const params: IMoveConditionalRuleMutationParams = {
- unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
- start: { id: cfId, type: 'self' }, end: { id: toCfId, type },
+ unitId: this._workbook.getUnitId(),
+ subUnitId: this._worksheet.getSheetId(),
+ start: { id: cfId, type: 'self' },
+ end: { id: toCfId, type },
};
- this._commandService.syncExecuteCommand(MoveConditionalRuleMutation.id, params);
+ this._commandService.syncExecuteCommand(MoveCfCommand.id, params);
return this;
}
override setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FRange {
const params: ISetConditionalRuleMutationParams = {
- unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
+ unitId: this._workbook.getUnitId(),
+ subUnitId: this._worksheet.getSheetId(),
rule,
cfId,
};
- this._commandService.syncExecuteCommand(SetConditionalRuleMutation.id, params);
+ this._commandService.syncExecuteCommand(SetCfCommand.id, params);
return this;
}
diff --git a/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts b/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts
index b12c7d6f70..a091e1c6e6 100644
--- a/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts
+++ b/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts
@@ -32,7 +32,7 @@ import {
SetCfCommand,
} from '@univerjs/sheets-conditional-formatting';
import { FWorksheet } from '@univerjs/sheets/facade';
-import { FConditionalFormattingBuilder } from './conditional-formatting-builder';
+import { FConditionalFormattingBuilder } from './f-conditional-formatting-builder';
/**
* @ignore
@@ -57,20 +57,6 @@ export interface IFWorksheetConditionalFormattingMixin {
* Creates a constructor for conditional formatting
* @returns {FConditionalFormattingBuilder} The conditional formatting builder
* @memberof IFWorksheetConditionalFormattingMixin
- * @example
- * ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorksheet = fWorkbook.getActiveSheet();
- * const fRange = fWorksheet.getRange('A1:T100');
- * const rule = fWorksheet.createConditionalFormattingRule()
- * .whenCellNotEmpty()
- * .setRanges([fRange.getRange()])
- * .setItalic(true)
- * .setBackground('red')
- * .setFontColor('green')
- * .build();
- * fWorksheet.addConditionalFormattingRule(rule);
- * ```
*/
createConditionalFormattingRule(): FConditionalFormattingBuilder;
@@ -82,6 +68,8 @@ export interface IFWorksheetConditionalFormattingMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100.
* const fRange = fWorksheet.getRange('A1:T100');
* const rule = fWorksheet.newConditionalFormattingRule()
* .whenCellNotEmpty()
@@ -104,6 +92,8 @@ export interface IFWorksheetConditionalFormattingMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100.
* const fRange = fWorksheet.getRange('A1:T100');
* const rule = fWorksheet.newConditionalFormattingRule()
* .whenCellNotEmpty()
@@ -127,6 +117,8 @@ export interface IFWorksheetConditionalFormattingMixin {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const rules = fWorksheet.getConditionalFormattingRules();
+ *
+ * // Delete the first rule
* fWorksheet.deleteConditionalFormattingRule(rules[0]?.cfId);
* ```
*/
@@ -144,6 +136,8 @@ export interface IFWorksheetConditionalFormattingMixin {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const rules = fWorksheet.getConditionalFormattingRules();
+ *
+ * // Move the third rule before the first rule
* const rule = rules[2];
* const targetRule = rules[0];
* fWorksheet.moveConditionalFormattingRule(rule?.cfId, targetRule?.cfId, 'before');
@@ -171,6 +165,7 @@ export interface IFWorksheetConditionalFormattingMixin {
* .build();
* fWorksheet.addConditionalFormattingRule(rule);
*
+ * // Modify the first rule to apply to a new range
* const rules = fWorksheet.getConditionalFormattingRules();
* const newRuleRange = fWorksheet.getRange('A1:D10');
* fWorksheet.setConditionalFormattingRule(rules[0]?.cfId, { ...rules[0], ranges: [newRuleRange.getRange()] });
@@ -187,7 +182,7 @@ export interface IFWorksheetConditionalFormattingMixin {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* fWorksheet.clearConditionalFormatRules();
- * console.log(fWorksheet.getConditionalFormattingRules());
+ * console.log(fWorksheet.getConditionalFormattingRules()); // []
* ```
*/
clearConditionalFormatRules(): FWorksheet;
diff --git a/packages/sheets-conditional-formatting/src/facade/index.ts b/packages/sheets-conditional-formatting/src/facade/index.ts
index 3fe45cadc2..eef8772b79 100644
--- a/packages/sheets-conditional-formatting/src/facade/index.ts
+++ b/packages/sheets-conditional-formatting/src/facade/index.ts
@@ -17,8 +17,9 @@
import './f-range';
import './f-workbook';
import './f-worksheet';
+import './f-enum';
-export { FConditionalFormattingBuilder } from './conditional-formatting-builder';
+export { FConditionalFormattingBuilder } from './f-conditional-formatting-builder';
export type { IFRangeConditionalFormattingMixin } from './f-range';
export type { FWorkbookConditionalFormattingMixin } from './f-workbook';
diff --git a/packages/sheets-data-validation/src/facade/f-data-validation-builder.ts b/packages/sheets-data-validation/src/facade/f-data-validation-builder.ts
index 0ac9adf22a..95010e5715 100644
--- a/packages/sheets-data-validation/src/facade/f-data-validation-builder.ts
+++ b/packages/sheets-data-validation/src/facade/f-data-validation-builder.ts
@@ -64,6 +64,8 @@ export class FDataValidationBuilder {
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberBetween(1, 10)
@@ -85,9 +87,24 @@ export class FDataValidationBuilder {
* @returns {FDataValidationBuilder} A new instance of the DataValidationBuilder class
* @example
* ```typescript
- * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
+ * const fRange = fWorksheet.getRange('A1:B10');
+ * const builder = univerAPI.newDataValidation()
+ * .requireNumberBetween(1, 10)
+ * .setOptions({
+ * allowBlank: true,
+ * showErrorMessage: true,
+ * error: 'Please enter a number between 1 and 10'
+ * });
+ * fRange.setDataValidation(builder.build());
+ *
+ * // Copy the builder applied to the new range F1:G10
+ * const newRange = fWorksheet.getRange('F1:G10');
* const copyBuilder = builder.copy();
- * console.log(copyBuilder);
+ * newRange.setDataValidation(copyBuilder.build());
* ```
*/
copy(): FDataValidationBuilder {
@@ -116,13 +133,13 @@ export class FDataValidationBuilder {
* @example
* ```typescript
* const builder = univerAPI.newDataValidation();
- * console.log(builder.getCriteriaType());
+ * console.log(builder.getCriteriaType()); // custom
*
* builder.requireNumberBetween(1, 10);
- * console.log(builder.getCriteriaType());
+ * console.log(builder.getCriteriaType()); // decimal
*
* builder.requireValueInList(['Yes', 'No']);
- * console.log(builder.getCriteriaType());
+ * console.log(builder.getCriteriaType()); // list
* ```
*/
getCriteriaType(): DataValidationType | string {
@@ -136,10 +153,10 @@ export class FDataValidationBuilder {
* ```typescript
* const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
* const [operator, formula1, formula2] = builder.getCriteriaValues();
- * console.log(operator, formula1, formula2);
+ * console.log(operator, formula1, formula2); // between 1 10
*
* builder.requireValueInList(['Yes', 'No']);
- * console.log(builder.getCriteriaValues());
+ * console.log(builder.getCriteriaValues()); // undefined Yes,No undefined
* ```
*/
getCriteriaValues(): [string | undefined, string | undefined, string | undefined] {
@@ -163,10 +180,10 @@ export class FDataValidationBuilder {
}
/**
- * Sets the data validation type to CHECKBOX and sets the checked and unchecked values
- * @param {string} [checkedValue] - The value when the checkbox is checked
- * @param {string} [uncheckedValue] - The value when the checkbox is unchecked
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require that the input is a boolean value; this value is rendered as a checkbox.
+ * @param {string} [checkedValue] - The value assigned to a checked box.
+ * @param {string} [uncheckedValue] - The value assigned to an unchecked box.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -196,23 +213,28 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be after a specific date
- * @param {Date} date - The date to compare against
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be after a specific date.
+ * @param {Date} date - The latest unacceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date after 2025-01-01
* const rule = univerAPI.newDataValidation()
* .requireDateAfter(new Date('2025-01-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['invalid', 'invalid', 'invalid', 'valid']]
* ```
@@ -226,23 +248,28 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be before a specific date
- * @param {Date} date - The date to compare against
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be before a specific date.
+ * @param {Date} date - The earliest unacceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date before 2025-01-01
* const rule = univerAPI.newDataValidation()
* .requireDateBefore(new Date('2025-01-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
* ```
@@ -257,24 +284,29 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be within a specific date range
- * @param {Date} start - The starting date of the range
- * @param {Date} end - The ending date of the range
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be within a specific date range.
+ * @param {Date} start - The earliest acceptable date.
+ * @param {Date} end - The latest acceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date between 2024-06-01 and 2025-06-01
* const rule = univerAPI.newDataValidation()
* .requireDateBetween(new Date('2024-06-01'), new Date('2025-06-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['invalid', 'valid', 'valid', 'invalid']]
* ```
@@ -289,26 +321,32 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be equal to a specific date
- * @param {Date} date - The date to compare against
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be equal to a specific date.
+ * @param {Date} date - The sole acceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date equal to 2025-01-01
* const rule = univerAPI.newDataValidation()
* .requireDateEqualTo(new Date('2025-01-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the cell A2
* const status = await fWorksheet.getRange('A2').getValidatorStatus();
* console.log(status?.[0]?.[0]); // 'valid'
*
+ * // Get the validation status of the cell B2
* const status2 = await fWorksheet.getRange('B2').getValidatorStatus();
* console.log(status2?.[0]?.[0]); // 'invalid'
* ```
@@ -323,24 +361,29 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be not within a specific date range
- * @param {Date} start - The starting date of the date range
- * @param {Date} end - The ending date of the date range
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be not within a specific date range.
+ * @param {Date} start - The earliest unacceptable date.
+ * @param {Date} end - The latest unacceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date not between 2024-06-01 and 2025-06-01
* const rule = univerAPI.newDataValidation()
* .requireDateNotBetween(new Date('2024-06-01'), new Date('2025-06-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['valid', 'invalid', 'invalid', 'valid']]
* ```
@@ -355,23 +398,28 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be on or after a specific date
- * @param {Date} date - The date to compare against
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be on or after a specific date.
+ * @param {Date} date - The earliest acceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date on or after 2025-01-01
* const rule = univerAPI.newDataValidation()
* .requireDateOnOrAfter(new Date('2025-01-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['invalid', 'invalid', 'valid', 'valid']]
* ```
@@ -386,23 +434,28 @@ export class FDataValidationBuilder {
}
/**
- * Set the data validation type to DATE and configure the validation rules to be on or before a specific date
- * @param {Date} date - The date to compare against
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Set the data validation type to DATE and configure the validation rules to be on or before a specific date.
+ * @param {Date} date - The latest acceptable date.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some date values in the range A1:B2
* const fRange = fWorksheet.getRange('A1:B2');
* fRange.setValues([
* ['2024-01-01', '2024-12-31'],
* ['2025-01-01', '2025-12-31']
* ]);
+ *
+ * // Create a data validation rule that requires a date on or before 2025-01-01
* const rule = univerAPI.newDataValidation()
* .requireDateOnOrBefore(new Date('2025-01-01'))
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['valid', 'valid', 'valid', 'invalid']]
* ```
@@ -417,13 +470,15 @@ export class FDataValidationBuilder {
}
/**
- * Requires that a custom formula be satisfied
- * @param {string} formula - The formula string that needs to be satisfied, formula result should be TRUE or FALSE, and references range will relative offset
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require that the given formula evaluates to `true`.
+ * @param {string} formula - The formula string that needs to be satisfied, formula result should be TRUE or FALSE, and references range will relative offset.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some values in the range A1:B2 and C1:D2
* const cell = fWorksheet.getRange('A1:B2');
* cell.setValues([
* [4, 3],
@@ -434,6 +489,8 @@ export class FDataValidationBuilder {
* [1, 2],
* [3, 4]
* ]);
+ *
+ * // Create a data validation rule that requires the formula '=A1>2' to be satisfied
* const rule = univerAPI.newDataValidation()
* .requireFormulaSatisfied('=A1>2')
* .setOptions({
@@ -443,6 +500,7 @@ export class FDataValidationBuilder {
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validation status of the range
* const status = await fRange.getValidatorStatus();
* console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
* ```
@@ -455,15 +513,17 @@ export class FDataValidationBuilder {
}
/**
- * Requires the user to enter a number within a specific range, which can be integer or decimal
- * @param {number} start - The starting value of the number range
- * @param {number} end - The ending value of the number range
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number that falls between, or is either of, two specified numbers.
+ * @param {number} start - The lowest acceptable value.
+ * @param {number} end - The highest acceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberBetween(1, 10)
@@ -486,14 +546,16 @@ export class FDataValidationBuilder {
}
/**
- * Requires the user to enter a number that is equal to a specific value, which can be an integer or a decimal
- * @param {number} num - The number to which the entered number should be equal
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number equal to the given value.
+ * @param {number} num - The sole acceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number equal to 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(10)
@@ -515,14 +577,16 @@ export class FDataValidationBuilder {
}
/**
- * Requires the user to enter a number that is greater than a specific value, which can be an integer or a decimal
- * @param {number} num - The number to which the entered number should be greater
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number greater than the given value.
+ * @param {number} num - The highest unacceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number greater than 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberGreaterThan(10)
@@ -544,14 +608,16 @@ export class FDataValidationBuilder {
}
/**
- * Requires the user to enter a number that is greater than or equal to a specific value, which can be an integer or a decimal
- * @param {number} num - The number to which the entered number should be greater than or equal
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number greater than or equal to the given value.
+ * @param {number} num - The lowest acceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number greater than 10 or equal to 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberGreaterThanOrEqualTo(10)
@@ -573,14 +639,16 @@ export class FDataValidationBuilder {
}
/**
- * Requires the user to enter a number that is less than a specific value, which can be an integer or a decimal
- * @param {number} num - The number to which the entered number should be less
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number less than the given value.
+ * @param {number} num - The lowest unacceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number less than 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberLessThan(10)
@@ -602,15 +670,16 @@ export class FDataValidationBuilder {
}
/**
- * Sets the data validation rule to require a number less than or equal to a specified value
- * The specified value can be an integer or a decimal
- * @param {number} num - The number to which the entered number should be less than or equal
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number less than or equal to the given value.
+ * @param {number} num - The highest acceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number less than 10 or equal to 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberLessThanOrEqualTo(10)
@@ -632,16 +701,17 @@ export class FDataValidationBuilder {
}
/**
- * Sets a data validation rule that requires the user to enter a number outside a specified range
- * The specified range includes all integers and decimals
- * @param {number} start - The starting point of the specified range
- * @param {number} end - The end point of the specified range
- * @param {boolean} [isInteger] - Optional parameter, indicating whether the number to be verified is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number that does not fall between, and is neither of, two specified numbers.
+ * @param {number} start - The lowest unacceptable value.
+ * @param {number} end - The highest unacceptable value.
+ * @param {boolean} [isInteger] - Optional parameter, indicating whether the number to be verified is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number not between 1 and 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberNotBetween(1, 10)
@@ -664,15 +734,16 @@ export class FDataValidationBuilder {
}
/**
- * Creates a data validation rule that requires the user to enter a number that is not equal to a specific value
- * The specific value can be an integer or a decimal
- * @param {number} num - The number to which the entered number should not be equal
- * @param {boolean} [isInteger] - Indicates whether the required number is an integer
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the data validation rule to require a number not equal to the given value.
+ * @param {number} num - The sole unacceptable value.
+ * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number not equal to 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberNotEqualTo(10)
@@ -694,16 +765,18 @@ export class FDataValidationBuilder {
}
/**
- * Sets a data validation rule that requires the user to enter a value from a list of specific values
- * The list can be displayed in a dropdown, and the user can choose multiple values according to the settings
- * @param {string[]} values - An array containing the specific values that the user can enter
- * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values
- * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets a data validation rule that requires the user to enter a value from a list of specific values.
+ * The list can be displayed in a dropdown, and the user can choose multiple values according to the settings.
+ * @param {string[]} values - An array of acceptable values.
+ * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values.
+ * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires the user to enter a value from the list ['Yes', 'No'] for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireValueInList(['Yes', 'No'])
@@ -726,22 +799,25 @@ export class FDataValidationBuilder {
}
/**
- * Sets a data validation rule that requires the user to enter a value within a specific range
- * The range is defined by an FRange object, which contains the unit ID, sheet name, and cell range
- * @param {FRange} range - An FRange object representing the range of values that the user can enter
- * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values
- * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets a data validation rule that requires the user to enter a value within a specific range.
+ * The range is defined by an FRange object, which contains the unit ID, sheet name, and cell range.
+ * @param {FRange} range - An FRange object representing the range of values that the user can enter.
+ * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values.
+ * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set the values in the range B1:B2
* const fRange = fWorksheet.getRange('B1:B2');
* fRange.setValues([
* ['Yes'],
* ['No']
* ]);
*
+ * // Create a new data validation rule that requires the user to enter a value from the range B1:B2 for the range A1:A10
* const rule = univerAPI.newDataValidation()
* .requireValueInRange(fRange)
* .setOptions({
@@ -768,11 +844,11 @@ export class FDataValidationBuilder {
}
/**
- * Sets whether to allow invalid data and configures the error style
- * If invalid data is not allowed, the error style will be set to STOP, indicating that data entry must stop upon encountering an error
- * If invalid data is allowed, the error style will be set to WARNING, indicating that a warning will be displayed when invalid data is entered, but data entry can continue
- * @param {boolean} allowInvalidData - Whether to allow invalid data
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets whether to allow invalid data and configures the error style.
+ * If invalid data is not allowed, the error style will be set to STOP, indicating that data entry must stop upon encountering an error.
+ * If invalid data is allowed, the error style will be set to WARNING, indicating that a warning will be displayed when invalid data is entered, but data entry can continue.
+ * @param {boolean} allowInvalidData - Whether to allow invalid data.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -801,9 +877,9 @@ export class FDataValidationBuilder {
}
/**
- * Sets whether to allow blank values
- * @param {boolean} allowBlank - Whether to allow blank values
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets whether to allow blank values.
+ * @param {boolean} allowBlank - Whether to allow blank values.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* // Assume current sheet is empty data
@@ -833,13 +909,15 @@ export class FDataValidationBuilder {
}
/**
- * Sets the options for the data validation rule
- * @param {Partial<IDataValidationRuleOptions>} options - The options to set for the data validation rule
- * @returns {FDataValidationBuilder} The current instance for method chaining
+ * Sets the options for the data validation rule.
+ * @param {Partial<IDataValidationRuleOptions>} options - The options to set for the data validation rule.
+ * @returns {FDataValidationBuilder} The current instance for method chaining.
* @example
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires the user to enter a value from the list ['Yes', 'No'] for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireValueInList(['Yes', 'No'])
diff --git a/packages/sheets-data-validation/src/facade/f-data-validation.ts b/packages/sheets-data-validation/src/facade/f-data-validation.ts
index 77c5e90726..a437d864bb 100644
--- a/packages/sheets-data-validation/src/facade/f-data-validation.ts
+++ b/packages/sheets-data-validation/src/facade/f-data-validation.ts
@@ -242,12 +242,15 @@ export class FDataValidation {
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
* .build();
* fRange.setDataValidation(rule);
*
+ * // Change the rule criteria to require a number between 1 and 10
* fRange.getDataValidation().setCriteria(
* univerAPI.Enum.DataValidationType.DECIMAL,
* [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10']
@@ -292,12 +295,15 @@ export class FDataValidation {
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
* .build();
* fRange.setDataValidation(rule);
*
+ * // Supplement the rule with additional options
* fRange.getDataValidation().setOptions({
* allowBlank: true,
* showErrorMessage: true,
@@ -335,12 +341,15 @@ export class FDataValidation {
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
* .build();
* fRange.setDataValidation(rule);
*
+ * // Change the range to C1:D10
* const newRuleRange = fWorksheet.getRange('C1:D10');
* fRange.getDataValidation().setRanges([newRuleRange]);
* ```
@@ -371,12 +380,15 @@ export class FDataValidation {
* ```typescript
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
* .build();
* fRange.setDataValidation(rule);
*
+ * // Delete the data validation rule
* fRange.getDataValidation().delete();
* ```
*/
diff --git a/packages/sheets-data-validation/src/facade/f-range.ts b/packages/sheets-data-validation/src/facade/f-range.ts
index 65aba519da..19eb7d15b8 100644
--- a/packages/sheets-data-validation/src/facade/f-range.ts
+++ b/packages/sheets-data-validation/src/facade/f-range.ts
@@ -32,6 +32,8 @@ export interface IFRangeDataValidationMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a data validation rule that requires a number between 1 and 10 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberBetween(1, 10)
@@ -53,6 +55,8 @@ export interface IFRangeDataValidationMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* const rule = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
@@ -60,10 +64,13 @@ export interface IFRangeDataValidationMixin {
* fRange.setDataValidation(rule);
* console.log(fRange.getDataValidation().getCriteriaValues());
*
+ * // Change the rule criteria to require a number between 1 and 10
* fRange.getDataValidation().setCriteria(
* univerAPI.Enum.DataValidationType.DECIMAL,
* [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10']
* );
+ *
+ * // Print the new rule criteria values
* console.log(fRange.getDataValidation().getCriteriaValues());
* ```
*/
@@ -76,18 +83,22 @@ export interface IFRangeDataValidationMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a data validation rule that requires a number equal to 20 for the range A1:B10
* const fRange1 = fWorksheet.getRange('A1:B10');
* const rule1 = univerAPI.newDataValidation()
* .requireNumberEqualTo(20)
* .build();
* fRange1.setDataValidation(rule1);
*
+ * // Create a data validation rule that requires a number between 1 and 10 for the range C1:D10
* const fRange2 = fWorksheet.getRange('C1:D10');
* const rule2 = univerAPI.newDataValidation()
* .requireNumberBetween(1, 10)
* .build();
* fRange2.setDataValidation(rule2);
*
+ * // Get all data validation rules in the range A1:D10
* const range = fWorksheet.getRange('A1:D10');
* const rules = range.getDataValidations();
* console.log(rules.length); // 2
@@ -102,6 +113,8 @@ export interface IFRangeDataValidationMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Set some values in the range A1:B10
* const fRange = fWorksheet.getRange('A1:B10');
* fRange.setValues([
* [1, 2],
@@ -115,14 +128,18 @@ export interface IFRangeDataValidationMixin {
* [17, 18],
* [19, 20]
* ]);
+ *
+ * // Create a data validation rule that requires a number between 1 and 10 for the range A1:B10
* const rule = univerAPI.newDataValidation()
* .requireNumberBetween(1, 10)
* .build();
* fRange.setDataValidation(rule);
*
+ * // Get the validator status for the cell B2
* const status = await fWorksheet.getRange('B2').getValidatorStatus();
* console.log(status?.[0]?.[0]); // 'valid'
*
+ * // Get the validator status for the cell B10
* const status2 = await fWorksheet.getRange('B10').getValidatorStatus();
* console.log(status2?.[0]?.[0]); // 'invalid'
* ```
diff --git a/packages/sheets-data-validation/src/facade/f-univer.ts b/packages/sheets-data-validation/src/facade/f-univer.ts
index 06afd8bad9..d954c8566a 100644
--- a/packages/sheets-data-validation/src/facade/f-univer.ts
+++ b/packages/sheets-data-validation/src/facade/f-univer.ts
@@ -54,8 +54,20 @@ export interface IFUnvierDataValidationMixin {
* @returns {FDataValidationBuilder} A new instance of the FDataValidationBuilder class
* @example
* ```ts
- * const rule = FUnvier.newDataValidation();
- * cell.setDataValidation(rule.requireValueInRange(range));
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Create a new data validation rule that requires a number between 1 and 10 fot the range A1:B10
+ * const fRange = fWorksheet.getRange('A1:B10');
+ * const rule = univerAPI.newDataValidation()
+ * .requireNumberBetween(1, 10)
+ * .setOptions({
+ * allowBlank: true,
+ * showErrorMessage: true,
+ * error: 'Please enter a number between 1 and 10'
+ * })
+ * .build();
+ * fRange.setDataValidation(rule);
* ```
*/
newDataValidation(): FDataValidationBuilder;
diff --git a/packages/sheets-drawing-ui/src/facade/f-over-grid-image.ts b/packages/sheets-drawing-ui/src/facade/f-over-grid-image.ts
index b25d34258a..1188bc38dd 100644
--- a/packages/sheets-drawing-ui/src/facade/f-over-grid-image.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-over-grid-image.ts
@@ -243,7 +243,7 @@ export class FOverGridImageBuilder {
/**
* Set the horizontal position of the image
- * @param {number} column - The column index of the image start position
+ * @param {number} column - The column index of the image start position, start at 0
* @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining
* @example
* ```ts
@@ -266,7 +266,7 @@ export class FOverGridImageBuilder {
/**
* Set the vertical position of the image
- * @param {number} row - The row index of the image start position
+ * @param {number} row - The row index of the image start position, start at 0
* @returns {FOverGridImageBuilder} The `FOverGridImageBuilder` for chaining
* @example
* ```ts
@@ -884,7 +884,7 @@ export class FOverGridImage extends FBase {
/**
* Move the image layer backward by one level
- * @returns success or not
+ * @returns {boolean} true if the image is moved backward successfully, otherwise false
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -905,7 +905,7 @@ export class FOverGridImage extends FBase {
/**
* Move the image layer to the bottom layer
- * @returns success or not
+ * @returns {boolean} true if the image is moved to the bottom layer successfully, otherwise false
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -926,7 +926,7 @@ export class FOverGridImage extends FBase {
/**
* Move the image layer to the top layer
- * @returns success or not
+ * @returns {boolean} true if the image is moved to the top layer successfully, otherwise false
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets-drawing-ui/src/facade/f-range.ts b/packages/sheets-drawing-ui/src/facade/f-range.ts
index f1673f2d81..79429473e2 100644
--- a/packages/sheets-drawing-ui/src/facade/f-range.ts
+++ b/packages/sheets-drawing-ui/src/facade/f-range.ts
@@ -30,8 +30,10 @@ export interface IFRangeSheetDrawingMixin {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ *
+ * // Insert an image into the cell A10
* const fRange = fWorksheet.getRange('A10');
- * const result = fRange.insertCellImageAsync('https://avatars.githubusercontent.com/u/61444807?s=48&v=4');
+ * const result = await fRange.insertCellImageAsync('https://avatars.githubusercontent.com/u/61444807?s=48&v=4');
* console.log(result);
* ```
*/
diff --git a/packages/sheets-formula-ui/src/facade/f-univer.ts b/packages/sheets-formula-ui/src/facade/f-univer.ts
index 9c63072e34..3f48faef20 100644
--- a/packages/sheets-formula-ui/src/facade/f-univer.ts
+++ b/packages/sheets-formula-ui/src/facade/f-univer.ts
@@ -27,16 +27,25 @@ export interface ISheetsFormulaUIMixin {
* @returns {Promise<IUnitRangeName[]>} The selected ranges.
* @example
* ```typescript
- * this.univer.showRangeSelectorDialog({
- * unitId: 'unit1',
- * subUnitId: 'subUnit1',
- * initialValue: [{ sheetName: 'Sheet1', range: 'A1:B2' }],
- * maxRangeCount: 2,
- * supportAcrossSheet: true,
- * callback: (ranges, isCancel) => {
- * // Handle the selected ranges
- * }
- * })
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const unitId = fWorkbook.getId();
+ *
+ * await univerAPI.showRangeSelectorDialog({
+ * unitId,
+ * subUnitId: fWorksheet.getSheetId(),
+ * initialValue: [{
+ * unitId,
+ * sheetName: fWorksheet.getSheetName(),
+ * range: 'A1:B2'
+ * }],
+ * maxRangeCount: 2,
+ * supportAcrossSheet: true,
+ * callback: (ranges, isCancel) => {
+ * // Handle the selected ranges
+ * console.log(ranges, isCancel);
+ * }
+ * });
* ```
*/
showRangeSelectorDialog(opts: IShowRangeSelectorDialogOptions): Promise<IUnitRangeName[]>;
diff --git a/packages/sheets-numfmt/src/facade/f-workbook.ts b/packages/sheets-numfmt/src/facade/f-workbook.ts
index cf22c74852..cf2735f0da 100644
--- a/packages/sheets-numfmt/src/facade/f-workbook.ts
+++ b/packages/sheets-numfmt/src/facade/f-workbook.ts
@@ -33,11 +33,11 @@ export interface IFWorkbookNumfmtMixin {
*
* // Set the locale en_US for number formatting.
* fWorkbook.setNumfmtLocal('en_US');
- * console.log(fRange.getValue()); // 1,234.57
+ * console.log(fRange.getDisplayValue()); // 1,234.57
*
* // Set the locale de_DE for number formatting.
* fWorkbook.setNumfmtLocal('de_DE');
- * console.log(fRange.getValue()); // 1.234,57
+ * console.log(fRange.getDisplayValue()); // 1.234,57
* ```
*/
setNumfmtLocal(local: INumfmtLocalTag): FWorkbook;