@univerjs/sheets-data-validation 0.5.4 → 0.5.5-nightly.202501201336

package/lib/es/facade.js

@@ -2,8 +2,8 @@ var j = Object.defineProperty;
 var q = (c, e, t) => e in c ? j(c, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : c[e] = t;
 var f = (c, e, t) => q(c, typeof e != "symbol" ? e + "" : e, t);
 import { UpdateSheetDataValidationSettingCommand as U, UpdateSheetDataValidationOptionsCommand as v, UpdateSheetDataValidationRangeCommand as C, RemoveSheetDataValidationCommand as T, ClearRangeDataValidationCommand as W, AddSheetDataValidationCommand as A, SheetsDataValidationValidatorService as S, SheetDataValidationModel as V, RemoveSheetAllDataValidationCommand as O } from "@univerjs/sheets-data-validation";
-import { FRange as y, FWorkbook as M, FWorksheet as x } from "@univerjs/sheets/facade";
-import { generateRandomId as B, DataValidationType as o, DataValidationErrorStyle as w, DataValidationOperator as d, IUniverInstanceService as H, ICommandService as p, FUniver as N, CanceledError as _, toDisposable as g, FEventName as $ } from "@univerjs/core";
+import { FRange as y, FWorkbook as M, FWorksheet as N } from "@univerjs/sheets/facade";
+import { generateRandomId as B, DataValidationType as o, DataValidationErrorStyle as w, DataValidationOperator as h, IUniverInstanceService as H, ICommandService as p, FUniver as x, CanceledError as _, toDisposable as g, FEventName as $ } from "@univerjs/core";
 import { DataValidationModel as b, getRuleOptions as F } from "@univerjs/data-validation";
 import { serializeRangeToRefString as P } from "@univerjs/engine-formula";
 import { filter as R } from "rxjs";
@@ -18,16 +18,24 @@ class D {
   }
   /**
    * Builds an FDataValidation instance based on the _rule property of the current class
-   *
    * @returns {FDataValidation} A new instance of the FDataValidation class
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const validation = builder.requireNumberBetween(1, 10).build();
+   * ```
    */
   build() {
     return new m(this._rule);
   }
   /**
    * Creates a duplicate of the current DataValidationBuilder object
-   *
-   * @return {FDataValidationBuilder} A new instance of the DataValidationBuilder class
+   * @returns {FDataValidationBuilder} A new instance of the DataValidationBuilder class
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const copy = builder.requireNumberBetween(1, 10).copy();
+   * ```
    */
   copy() {
     return new D({
@@ -37,231 +45,322 @@ class D {
   }
   /**
    * Determines whether invalid data is allowed
-   *
    * @returns {boolean} True if invalid data is allowed, False otherwise
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const allowsInvalid = builder.getAllowInvalid();
+   * ```
    */
   getAllowInvalid() {
     return this._rule.errorStyle !== w.STOP;
   }
   /**
    * Gets the data validation type of the rule
-   *
-   * @returns {DataValidationType} The data validation type
+   * @returns {DataValidationType | string} The data validation type
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const type = builder.getCriteriaType();
+   * ```
    */
   getCriteriaType() {
     return this._rule.type;
   }
   /**
    * Gets the values used for criteria evaluation
-   *
-   * @returns {[string, string, string]} An array containing the operator, formula1, and formula2 values
+   * @returns {[string | undefined, string | undefined, string | undefined]} An array containing the operator, formula1, and formula2 values
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const [operator, formula1, formula2] = builder.getCriteriaValues();
+   * ```
    */
   getCriteriaValues() {
     return [this._rule.operator, this._rule.formula1, this._rule.formula2];
   }
   /**
    * Gets the help text information, which is used to provide users with guidance and support
-   *
-   * @returns {string | undefined} Returns the help text information. If there is no error message, it returns an undefined value.
+   * @returns {string | undefined} Returns the help text information. If there is no error message, it returns an undefined value
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const helpText = builder.getHelpText();
+   * ```
    */
   getHelpText() {
     return this._rule.error;
   }
   /**
    * Sets the data validation type to CHECKBOX and sets the checked and unchecked values
-   *
-   * @param checkedValue The value when the checkbox is checked (Optional)
-   * @param uncheckedValue The value when the checkbox is unchecked (Optional)
-   * @returns The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireCheckbox('Yes', 'No').build();
+   * ```
    */
   requireCheckbox(e, t) {
     return this._rule.type = o.CHECKBOX, this._rule.formula1 = e, this._rule.formula2 = t, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be after a specific date
-   *
-   * @param date The date to compare against. The formatted date string will be set as formula1
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @param {Date} date - The date to compare against
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireDateAfter(new Date('2024-01-01')).build();
+   * ```
    */
   requireDateAfter(e) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.operator = d.GREATER_THAN, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.operator = h.GREATER_THAN, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be before a specific date
-   *
-   * @param date The date to compare against. The formatted date string will be set as formula1
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @param {Date} date - The date to compare against
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireDateBefore(new Date('2024-12-31')).build();
+   * ```
    */
   requireDateBefore(e) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = d.LESS_THAN, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = h.LESS_THAN, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be within a specific date range
-   *
-   * @param start The starting date of the range. The formatted date string will be set as formula1
-   * @param end The ending date of the range. The formatted date string will be set as formula2
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder
+   *   .requireDateBetween(new Date('2024-01-01'), new Date('2024-12-31'))
+   *   .build();
+   * ```
    */
   requireDateBetween(e, t) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = t.toLocaleDateString(), this._rule.operator = d.BETWEEN, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = t.toLocaleDateString(), this._rule.operator = h.BETWEEN, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be equal to a specific date
-   *
-   * @param date The date to compare against. The formatted date string will be set as formula1
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @param {Date} date - The date to compare against
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireDateEqualTo(new Date('2024-01-01')).build();
+   * ```
    */
   requireDateEqualTo(e) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = d.EQUAL, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = h.EQUAL, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be not within a specific date range
-   *
-   * @param start The starting date of the date range
-   * @param end The ending date of the date range
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder
+   *   .requireDateNotBetween(new Date('2024-01-01'), new Date('2024-12-31'))
+   *   .build();
+   * ```
    */
   requireDateNotBetween(e, t) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = t.toLocaleDateString(), this._rule.operator = d.NOT_BETWEEN, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = t.toLocaleDateString(), this._rule.operator = h.NOT_BETWEEN, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be on or after a specific date
-   *
-   * @param date The date to compare against. The formatted date string will be set as formula1
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @param {Date} date - The date to compare against
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireDateOnOrAfter(new Date('2024-01-01')).build();
+   * ```
    */
   requireDateOnOrAfter(e) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = d.GREATER_THAN_OR_EQUAL, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = h.GREATER_THAN_OR_EQUAL, this;
   }
   /**
    * Set the data validation type to DATE and configure the validation rules to be on or before a specific date
-   *
-   * @param date The date to compare against. The formatted date string will be set as formula1
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @param {Date} date - The date to compare against
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireDateOnOrBefore(new Date('2024-12-31')).build();
+   * ```
    */
   requireDateOnOrBefore(e) {
-    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = d.LESS_THAN_OR_EQUAL, this;
+    return this._rule.type = o.DATE, this._rule.formula1 = e.toLocaleDateString(), this._rule.formula2 = void 0, this._rule.operator = h.LESS_THAN_OR_EQUAL, this;
   }
   /**
-   * Requires that a custom formula be satisfied.
-   * Sets the data validation type to CUSTOM and configures the validation rule based on the provided formula string.
-   *
-   * @param formula The formula string that needs to be satisfied.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * Requires that a custom formula be satisfied
+   * @param {string} formula - The formula string that needs to be satisfied
+   * @returns {FDataValidationBuilder} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireFormulaSatisfied('=A1>0').build();
+   * ```
    */
   requireFormulaSatisfied(e) {
     return this._rule.type = o.CUSTOM, this._rule.formula1 = e, this._rule.formula2 = void 0, this;
   }
   /**
-   * Requires the user to enter a number within a specific range, which can be integer or decimal.
-   * Sets the data validation type based on the isInteger parameter and configures the validation rules for the specified number range.
-   *
-   * @param start The starting value of the number range.
-   * @param end The ending value of the number range.
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or decimal.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberBetween(1, 10).build();
+   * ```
    */
   requireNumberBetween(e, t, r) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = `${t}`, this._rule.operator = d.BETWEEN, this._rule.type = r ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = `${t}`, this._rule.operator = h.BETWEEN, this._rule.type = r ? o.WHOLE : o.DECIMAL, this;
   }
   /**
-   * Requires the user to enter a number that is equal to a specific value, which can be an integer or a decimal.
-   * Sets the data validation type based on the isInteger parameter and configures the validation rules for the specified number.
-   *
-   * @param num The number to which the entered number should be equal.
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or a decimal.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberEqualTo(10).build();
+   * ```
    */
   requireNumberEqualTo(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
-   * Requires the user to enter a number that is greater than a specific value, which can be an integer or a decimal.
-   * Sets the data validation type based on the isInteger parameter and configures the validation rules for the specified number.
-   *
-   * @param num The number to which the entered number should be greater.
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or a decimal.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberGreaterThan(10).build();
+   * ```
    */
   requireNumberGreaterThan(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.GREATER_THAN, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.GREATER_THAN, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
-   * 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.
-   * Sets the data validation type based on the isInteger parameter and configures the validation rules for the specified number.
-   *
-   * @param num The number to which the entered number should be greater than or equal.
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or a decimal.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberGreaterThanOrEqualTo(10).build();
+   * ```
    */
   requireNumberGreaterThanOrEqualTo(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.GREATER_THAN_OR_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.GREATER_THAN_OR_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
-   * Requires the user to enter a number that is less than a specific value, which can be an integer or a decimal.
-   * Sets the data validation type based on the isInteger parameter and configures the validation rules for the specified number.
-   *
-   * @param num The number to which the entered number should be less.
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or a decimal.
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining.
+   * 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberLessThan(10).build();
+   * ```
    */
   requireNumberLessThan(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.LESS_THAN, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.LESS_THAN, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
    * 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 num The number to which the entered number should be less than or equal
-   * @param isInteger Indicates whether the required number is an integer
-   * @return The current instance of the DataValidationBuilder class, allowing for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberLessThanOrEqualTo(10).build();
+   * ```
    */
   requireNumberLessThanOrEqualTo(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.LESS_THAN_OR_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.LESS_THAN_OR_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
    * 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 start The starting point of the specified range
-   * @param end The end point of the specified range
-   * @param isInteger Optional parameter, indicating whether the number to be verified is an integer. Default value is false
-   * @return An instance of the FDataValidationBuilder class, allowing for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberNotBetween(1, 10).build();
+   * ```
    */
   requireNumberNotBetween(e, t, r) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = `${t}`, this._rule.operator = d.NOT_BETWEEN, this._rule.type = r ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = `${t}`, this._rule.operator = h.NOT_BETWEEN, this._rule.type = r ? o.WHOLE : o.DECIMAL, this;
   }
   /**
    * 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 num The number to which the entered number should not be equal
-   * @param isInteger Indicates whether the required number is an integer. Default is undefined, meaning it can be an integer or a decimal
-   * @return The current instance of the FDataValidationBuilder class to allow for method chaining
+   * @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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireNumberNotEqualTo(10).build();
+   * ```
    */
   requireNumberNotEqualTo(e, t) {
-    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = d.NOT_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
+    return this._rule.formula1 = `${e}`, this._rule.formula2 = void 0, this._rule.operator = h.NOT_EQUAL, this._rule.type = t ? o.WHOLE : o.DECIMAL, this;
   }
   /**
-   * 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 values An array containing the specific values that the user can enter.
-   * @param multiple Optional parameter indicating whether the user can select multiple values. Default is false, meaning only one value can be selected.
-   * @param showDropdown Optional parameter indicating whether to display the list in a dropdown. Default is true, meaning the list will be displayed as a dropdown.
-   * @return An instance of the FDataValidationBuilder class, allowing 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 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
+   * @example
+   * ```typescript
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.requireValueInList(['Yes', 'No']).build();
+   * ```
    */
   requireValueInList(e, t, r) {
     return this._rule.type = t ? o.LIST_MULTIPLE : o.LIST, this._rule.formula1 = e.join(","), this._rule.formula2 = void 0, this._rule.showDropDown = r != null ? r : !0, this;
   }
   /**
-   * 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 range An FRange object representing the range of values that the user can enter.
-   * @param multiple Optional parameter indicating whether the user can select multiple values. Default is false, meaning only one value can be selected.
-   * @param showDropdown Optional parameter indicating whether to display the list in a dropdown. Default is true, meaning the list will be displayed as a dropdown.
-   * @return The current instance of the FDataValidationBuilder class to allow 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 builder = univerAPI.newDataValidation();
+   * const range = FRange.create('Sheet1', 'B1:B10');
+   * const rule = builder.requireValueInRange(range).build();
+   * ```
    */
   requireValueInRange(e, t, r) {
     return this._rule.type = t ? o.LIST_MULTIPLE : o.LIST, this._rule.formula1 = `=${P({
@@ -271,48 +370,46 @@ class D {
     })}`, this._rule.formula2 = void 0, this._rule.showDropDown = r != null ? r : !0, this;
   }
   /**
-   * Sets whether to allow invalid data and configures the error style for data validation.
-   * 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 allowInvalidData A boolean value indicating whether to allow invalid data.
-   * @return The current instance of the FDataValidationBuilder class to allow 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 builder = univerAPI.newDataValidation();
+   * const rule = builder.setAllowInvalid(true).build();
+   * ```
    */
   setAllowInvalid(e) {
     return this._rule.errorStyle = e ? w.WARNING : w.STOP, this;
   }
   /**
-   * Sets the help text and enables the display of error messages for data validation.
-   * This method allows you to set a custom help text that will be displayed when the user enters invalid data.
-   *
-   * @param helpText The text to display as help information.
-   * @return The current instance of the FDataValidationBuilder class to allow 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
+   * const builder = univerAPI.newDataValidation();
+   * const rule = builder.setAllowBlank(true).build();
+   * ```
    */
-  setHelpText(e) {
-    return this._rule.error = e, this._rule.showErrorMessage = !0, this;
-  }
-  /**
-   * Sets the criteria values for data validation.
-   * This method is used to configure the validation rules based on specific criteria values.
-   *
-   * @param type The type of data validation.
-   * @param values An array containing the criteria values.
-   * The array should have three elements: [operator, formula1, formula2].
-   * operator is a DataValidationOperator enum value, formula1 is the first formula, and formula2 is the second formula.
-   * @return The current instance of the FDataValidationBuilder class, allowing for method chaining.
-   */
-  withCriteriaValues(e, t) {
-    return this._rule.type = e, this._rule.operator = t[0], this._rule.formula1 = t[1], this._rule.formula2 = t[2], this;
-  }
   setAllowBlank(e) {
     return this._rule.allowBlank = e, this;
   }
   /**
-   * Sets the options for the data validation rule.
-   * For details of options, please refer to https://univer.ai/typedoc/@univerjs/core/interfaces/IDataValidationRuleOptions
-   *
-   * @param options The options to set for the data validation rule.
-   * @returns The current instance of the FDataValidationBuilder class to allow 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 builder = univerAPI.newDataValidation();
+   * const rule = builder.setOptions({
+   *   allowBlank: true,
+   *   showErrorMessage: true,
+   *   error: 'Please enter a valid value'
+   * }).build();
+   * ```
    */
   setOptions(e) {
     return Object.assign(this._rule, e), this;
@@ -326,50 +423,98 @@ class m {
     this._injector = r, this.rule = e, this._worksheet = t;
   }
   /**
-   * Gets whether invalid data is allowed based on the error style value.
-   *
-   * @return true if invalid data is allowed, false otherwise.
+   * Gets whether invalid data is allowed based on the error style value
+   * @returns {boolean} true if invalid data is allowed, false otherwise
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const allowsInvalid = dataValidation.getAllowInvalid();
+   * ```
    */
   getAllowInvalid() {
     return this.rule.errorStyle !== w.STOP;
   }
   /**
    * Gets the data validation type of the rule
-   *
-   * @returns The data validation type
+   * @returns {DataValidationType | string} The data validation type
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const type = dataValidation.getCriteriaType();
+   * ```
    */
   getCriteriaType() {
     return this.rule.type;
   }
   /**
    * Gets the values used for criteria evaluation
-   *
-   * @returns An array containing the operator, formula1, and formula2 values
+   * @returns {[string | undefined, string | undefined, string | undefined]} An array containing the operator, formula1, and formula2 values
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const [operator, formula1, formula2] = dataValidation.getCriteriaValues();
+   * ```
    */
   getCriteriaValues() {
     return [this.rule.operator, this.rule.formula1, this.rule.formula2];
   }
   /**
    * Gets the help text information, which is used to provide users with guidance and support
-   *
-   * @returns Returns the help text information. If there is no error message, it returns an undefined value.
+   * @returns {string | undefined} Returns the help text information. If there is no error message, it returns an undefined value
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const helpText = dataValidation.getHelpText();
+   * ```
    */
   getHelpText() {
     return this.rule.error;
   }
   /**
-   * Creates a new instance of FDataValidationBuilder using the current rule object.
-   * This method is useful for copying an existing data validation rule configuration.
-   *
-   * @return A new FDataValidationBuilder instance with the same rule configuration.
+   * Creates a new instance of FDataValidationBuilder using the current rule object
+   * @returns {FDataValidationBuilder} A new FDataValidationBuilder instance with the same rule configuration
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const builder = dataValidation.copy();
+   * const newRule = builder.setAllowInvalid(true).build();
+   * ```
    */
   copy() {
     return new D(this.rule);
   }
   /**
-   * Gets whether the data validation rule is applied to the worksheet.
-   *
-   * @returns true if the rule is applied, false otherwise.
+   * Gets whether the data validation rule is applied to the worksheet
+   * @returns {boolean} true if the rule is applied, false otherwise
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const isApplied = dataValidation.getApplied();
+   * ```
    */
   getApplied() {
     if (!this._worksheet)
@@ -378,9 +523,17 @@ class m {
     return !!(t && t.ranges.length);
   }
   /**
-   * Gets the ranges to which the data validation rule is applied.
-   *
-   * @returns An array of IRange objects representing the ranges to which the data validation rule is applied.
+   * Gets the ranges to which the data validation rule is applied
+   * @returns {FRange[]} An array of FRange objects representing the ranges to which the data validation rule is applied
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const ranges = dataValidation.getRanges();
+   * ```
    */
   getRanges() {
     if (!this.getApplied())
@@ -389,28 +542,58 @@ class m {
     return this.rule.ranges.map((t) => this._injector.createInstance(y, e, this._worksheet, t));
   }
   /**
-   * Gets the title of the error message dialog box.
-   *
-   * @returns The title of the error message dialog box.
+   * Gets the unit ID of the worksheet
+   * @returns {string | undefined} The unit ID of the worksheet
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const unitId = dataValidation.getUnitId();
+   * ```
    */
   getUnitId() {
     var e;
     return (e = this._worksheet) == null ? void 0 : e.getUnitId();
   }
   /**
-   * Gets the sheetId of the worksheet.
-   *
-   * @returns The sheetId of the worksheet.
+   * Gets the sheet ID of the worksheet
+   * @returns {string | undefined} The sheet ID of the worksheet
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const sheetId = dataValidation.getSheetId();
+   * ```
    */
   getSheetId() {
     var e;
     return (e = this._worksheet) == null ? void 0 : e.getSheetId();
   }
   /**
-   * Set Criteria for the data validation rule.
-   * @param type The type of data validation criteria.
-   * @param values An array containing the operator, formula1, and formula2 values.
-   * @returns true if the criteria is set successfully, false otherwise.
+   * Set Criteria for the data validation rule
+   * @param {DataValidationType} type - The type of data validation criteria
+   * @param {[DataValidationOperator, string, string]} values - An array containing the operator, formula1, and formula2 values
+   * @param {boolean} [allowBlank] - Whether to allow blank values
+   * @returns {FDataValidation} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * dataValidation.setCriteria(
+   *   DataValidationType.DECIMAL,
+   *   [DataValidationOperator.BETWEEN, '1', '10'],
+   *   true
+   * );
+   * ```
    */
   setCriteria(e, t, r = !0) {
     if (this.getApplied() && !this._injector.get(p).syncExecuteCommand(U.id, {
@@ -429,10 +612,22 @@ class m {
     return this.rule.operator = t[0], this.rule.formula1 = t[1], this.rule.formula2 = t[2], this.rule.type = e, this.rule.allowBlank = r, this;
   }
   /**
-   * Set the options for the data validation rule.
-   * For details of options, please refer to https://univer.ai/typedoc/@univerjs/core/interfaces/IDataValidationRuleOptions
-   * @param options An object containing the options to set. `IDataValidationRuleOptions`
-   * @returns true if the options are set successfully, false otherwise.
+   * Set the options for the data validation rule
+   * @param {Partial<IDataValidationRuleOptions>} options - The options to set for the data validation rule
+   * @returns {FDataValidation} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * dataValidation.setOptions({
+   *   allowBlank: true,
+   *   showErrorMessage: true,
+   *   error: 'Please enter a valid value'
+   * });
+   * ```
    */
   setOptions(e) {
     if (this.getApplied() && !this._injector.get(p).syncExecuteCommand(v.id, {
@@ -448,9 +643,19 @@ class m {
     return Object.assign(this.rule, e), this;
   }
   /**
-   * Set the ranges to the data validation rule.
-   * @param ranges new ranges array.
-   * @returns true if the ranges are set successfully, false otherwise.
+   * Set the ranges to the data validation rule
+   * @param {FRange[]} ranges - New ranges array
+   * @returns {FDataValidation} The current instance for method chaining
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const range = FRange.create('Sheet1', 'A1:B10');
+   * dataValidation.setRanges([range]);
+   * ```
    */
   setRanges(e) {
     if (this.getApplied() && !this._injector.get(p).syncExecuteCommand(C.id, {
@@ -463,8 +668,17 @@ class m {
     return this.rule.ranges = e.map((t) => t.getRange()), this;
   }
   /**
-   * Delete the data validation rule from the worksheet.
-   * @returns true if the rule is deleted successfully, false otherwise.
+   * Delete the data validation rule from the worksheet
+   * @returns {boolean} true if the rule is deleted successfully, false otherwise
+   * @example
+   * ```typescript
+   * const dataValidation = univerAPI
+   *  .getActiveWorkbook()
+   *  .getActiveWorksheet()
+   *  .getActiveRange()
+   *  .getDataValidation();
+   * const isDeleted = dataValidation.delete();
+   * ```
    */
   delete() {
     return this.getApplied() ? this._injector.get(p).syncExecuteCommand(T.id, {
@@ -516,14 +730,24 @@ class G extends y {
   }
 }
 y.extend(G);
-class Q extends N {
+class Q extends x {
+  // eslint-disable-next-line jsdoc/require-returns
   /**
   /**
-   * @deparecated use `univerAPI.newDataValidation()` as instead.
+   * @deprecated use `univerAPI.newDataValidation()` as instead.
    */
   static newDataValidation() {
     return new D();
   }
+  /**
+   * Creates a new instance of FDataValidationBuilder
+   * @returns {FDataValidationBuilder} A new instance of the FDataValidationBuilder class
+   * @example
+   * ```ts
+   * const rule = FUnvier.newDataValidation();
+   * cell.setDataValidation(rule.requireValueInRange(range));
+   * ```
+   */
   newDataValidation() {
     return new D();
   }
@@ -532,10 +756,10 @@ class Q extends N {
     if (!e.has(V)) return;
     const t = e.get(V), r = e.get(p);
     this.disposeWithMe(t.ruleChange$.subscribe((a) => {
-      const { unitId: i, subUnitId: n, rule: h, oldRule: u, type: s } = a, l = this.getSheetTarget(i, n);
+      const { unitId: i, subUnitId: n, rule: d, oldRule: u, type: s } = a, l = this.getSheetTarget(i, n);
       if (!l)
         return;
-      const { workbook: I, worksheet: k } = l, E = new m(h, k.getSheet(), this._injector);
+      const { workbook: I, worksheet: k } = l, E = new m(d, k.getSheet(), this._injector);
       this.fireEvent(this.Event.SheetDataValidationChanged, {
         origin: a,
         worksheet: k,
@@ -545,10 +769,10 @@ class Q extends N {
         rule: E
       });
     })), this.disposeWithMe(t.validStatusChange$.subscribe((a) => {
-      const { unitId: i, subUnitId: n, ruleId: h, status: u, row: s, col: l } = a, I = this.getSheetTarget(i, n);
+      const { unitId: i, subUnitId: n, ruleId: d, status: u, row: s, col: l } = a, I = this.getSheetTarget(i, n);
       if (!I)
         return;
-      const { workbook: k, worksheet: E } = I, L = E.getDataValidation(h);
+      const { workbook: k, worksheet: E } = I, L = E.getDataValidation(d);
       L && this.fireEvent(this.Event.SheetDataValidatorStatusChanged, {
         workbook: k,
         worksheet: E,
@@ -563,9 +787,9 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = {
+          const { workbook: d, worksheet: u } = n, s = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rule: i.rule
           };
           if (this.fireEvent(this.Event.BeforeSheetDataValidationAdd, s), s.cancel)
@@ -576,12 +800,12 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
+          const { workbook: d, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
           if (!s)
             return;
           const l = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rule: s,
             ruleId: i.ruleId,
             newCriteria: i.setting
@@ -594,12 +818,12 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
+          const { workbook: d, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
           if (!s)
             return;
           const l = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rule: s,
             ruleId: i.ruleId,
             newRanges: i.ranges
@@ -612,12 +836,12 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
+          const { workbook: d, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
           if (!s)
             return;
           const l = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rule: s,
             ruleId: i.ruleId,
             newOptions: i.options
@@ -630,12 +854,12 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
+          const { workbook: d, worksheet: u } = n, s = u.getDataValidation(i.ruleId);
           if (!s)
             return;
           const l = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rule: s,
             ruleId: i.ruleId
           };
@@ -647,9 +871,9 @@ class Q extends N {
           const i = a.params, n = this.getSheetTarget(i.unitId, i.subUnitId);
           if (!n)
             return;
-          const { workbook: h, worksheet: u } = n, s = {
+          const { workbook: d, worksheet: u } = n, s = {
             worksheet: u,
-            workbook: h,
+            workbook: d,
             rules: u.getDataValidations()
           };
           if (this.fireEvent(this.Event.BeforeSheetDataValidationDeleteAll, s), s.cancel)
@@ -660,7 +884,7 @@ class Q extends N {
     }));
   }
 }
-N.extend(Q);
+x.extend(Q);
 class z extends M {
   _initialize() {
     Object.defineProperty(this, "_dataValidationModel", {
@@ -747,7 +971,7 @@ class z extends M {
   }
 }
 M.extend(z);
-class K extends x {
+class K extends N {
   getDataValidations() {
     return this._injector.get(b).getRules(this._workbook.getUnitId(), this._worksheet.getSheetId()).map((t) => new m(t, this._worksheet, this._injector));
   }
@@ -757,12 +981,15 @@ class K extends x {
       this._worksheet.getSheetId()
     );
   }
+  getValidatorStatusAsync() {
+    return this.getValidatorStatus();
+  }
   getDataValidation(e) {
     const r = this._injector.get(b).getRuleById(this._workbook.getUnitId(), this._worksheet.getSheetId(), e);
     return r ? new m(r, this._worksheet, this._injector) : null;
   }
 }
-x.extend(K);
+N.extend(K);
 class X {
   get SheetDataValidationChanged() {
     return "SheetDataValidationChanged";