@univerjs/sheets-data-validation 0.5.4 → 0.5.5-experimental.20250122-3362a4a

package/lib/types/facade/f-data-validation-builder.d.ts

@@ -1,248 +1,353 @@
-import { IDataValidationRule, IDataValidationRuleOptions, DataValidationOperator, DataValidationType } from '@univerjs/core';
+import { IDataValidationRule, IDataValidationRuleOptions, DataValidationType } from '@univerjs/core';
 import { FRange } from '@univerjs/sheets/facade';
 import { FDataValidation } from './f-data-validation';
 /**
  * Builder for data validation rules.
- *
- *     Set the data validation for cell A1 to require a value from B1:B10.
- *     var rule = FUniver.newDataValidation().requireValueInRange(range).build();
- *     cell.setDataValidation(rule);
+ * @example
+ * ```typescript
+ * // Set the data validation for cell A1 to require a value from B1:B10
+ * const range = FRange.create('Sheet1', 'B1:B10');
+ * const rule = FUniver.newDataValidation().requireValueInRange(range).build();
+ * cell.setDataValidation(rule);
+ * ```
+ * @hideconstructor
  */
 export declare class FDataValidationBuilder {
     private _rule;
     constructor(rule?: IDataValidationRule);
     /**
      * 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(): FDataValidation;
     /**
      * 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(): FDataValidationBuilder;
     /**
      * 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(): boolean;
     /**
      * 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(): DataValidationType | string;
     /**
      * 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(): [string | undefined, string | undefined, string | undefined];
     /**
      * 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(): string | undefined;
     /**
      * 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(checkedValue?: string, uncheckedValue?: string): FDataValidationBuilder;
     /**
      * 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(date: Date): FDataValidationBuilder;
     /**
      * 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(date: Date): FDataValidationBuilder;
     /**
      * 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(start: Date, end: Date): FDataValidationBuilder;
     /**
      * 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(date: Date): FDataValidationBuilder;
     /**
      * 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(start: Date, end: Date): FDataValidationBuilder;
     /**
      * 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(date: Date): FDataValidationBuilder;
     /**
      * 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(date: Date): FDataValidationBuilder;
     /**
-     * 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(formula: string): FDataValidationBuilder;
     /**
-     * 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(start: number, end: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * 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(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * 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(num: number, isInteger?: boolean): 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.
-     * 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(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * 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(num: number, isInteger?: boolean): 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 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(num: number, isInteger?: boolean): 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 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(start: number, end: number, isInteger?: boolean): 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 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(num: number, isInteger?: boolean): 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 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(values: string[], multiple?: boolean, showDropdown?: boolean): 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 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(range: FRange, multiple?: boolean, showDropdown?: boolean): FDataValidationBuilder;
     /**
-     * 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(allowInvalidData: boolean): FDataValidationBuilder;
     /**
-     * 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(helpText: string): FDataValidationBuilder;
-    /**
-     * 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(type: DataValidationType | string, values: [DataValidationOperator, string, string]): this;
     setAllowBlank(allowBlank: boolean): FDataValidationBuilder;
     /**
-     * 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(options: Partial<IDataValidationRuleOptions>): this;
 }