@univerjs/sheets-data-validation 0.6.0 → 0.6.1

package/lib/es/facade.js

@@ -22,8 +22,18 @@ class E {
    * @returns {FDataValidation} A new instance of the FDataValidation class
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const validation = builder.requireNumberBetween(1, 10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * 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);
    * ```
    */
   build() {
@@ -34,8 +44,9 @@ class E {
    * @returns {FDataValidationBuilder} A new instance of the DataValidationBuilder class
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const copy = builder.requireNumberBetween(1, 10).copy();
+   * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
+   * const copyBuilder = builder.copy();
+   * console.log(copyBuilder);
    * ```
    */
   copy() {
@@ -49,8 +60,8 @@ class E {
    * @returns {boolean} True if invalid data is allowed, False otherwise
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const allowsInvalid = builder.getAllowInvalid();
+   * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
+   * console.log(builder.getAllowInvalid());
    * ```
    */
   getAllowInvalid() {
@@ -62,7 +73,13 @@ class E {
    * @example
    * ```typescript
    * const builder = univerAPI.newDataValidation();
-   * const type = builder.getCriteriaType();
+   * console.log(builder.getCriteriaType());
+   *
+   * builder.requireNumberBetween(1, 10);
+   * console.log(builder.getCriteriaType());
+   *
+   * builder.requireValueInList(['Yes', 'No']);
+   * console.log(builder.getCriteriaType());
    * ```
    */
   getCriteriaType() {
@@ -73,8 +90,12 @@ class E {
    * @returns {[string | undefined, string | undefined, string | undefined]} An array containing the operator, formula1, and formula2 values
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
+   * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
    * const [operator, formula1, formula2] = builder.getCriteriaValues();
+   * console.log(operator, formula1, formula2);
+   *
+   * builder.requireValueInList(['Yes', 'No']);
+   * console.log(builder.getCriteriaValues());
    * ```
    */
   getCriteriaValues() {
@@ -85,8 +106,11 @@ class E {
    * @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();
+   * const builder = univerAPI.newDataValidation().setOptions({
+   *   showErrorMessage: true,
+   *   error: 'Please enter a valid value'
+   * });
+   * console.log(builder.getHelpText()); // 'Please enter a valid value'
    * ```
    */
   getHelpText() {
@@ -99,8 +123,22 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireCheckbox('Yes', 'No').build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   *
+   * // Set the data validation for cell A1:A10 to require a checkbox with default 1 and 0 values
+   * const fRange = fWorksheet.getRange('A1:A10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireCheckbox()
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * // Set the data validation for cell B1:B10 to require a checkbox with 'Yes' and 'No' values
+   * const fRange2 = fWorksheet.getRange('B1:B10');
+   * const rule2 = univerAPI.newDataValidation()
+   *   .requireCheckbox('Yes', 'No')
+   *   .build();
+   * fRange2.setDataValidation(rule2);
    * ```
    */
   requireCheckbox(e, t) {
@@ -112,8 +150,20 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireDateAfter(new Date('2024-01-01')).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateAfter(new Date('2025-01-01'))
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['invalid', 'invalid', 'invalid', 'valid']]
    * ```
    */
   requireDateAfter(e) {
@@ -125,8 +175,20 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireDateBefore(new Date('2024-12-31')).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateBefore(new Date('2025-01-01'))
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
    * ```
    */
   requireDateBefore(e) {
@@ -139,10 +201,20 @@ class E {
    * @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'))
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateBetween(new Date('2024-06-01'), new Date('2025-06-01'))
    *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['invalid', 'valid', 'valid', 'invalid']]
    * ```
    */
   requireDateBetween(e, t) {
@@ -154,8 +226,23 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireDateEqualTo(new Date('2024-01-01')).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateEqualTo(new Date('2025-01-01'))
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fWorksheet.getRange('A2').getValidatorStatus();
+   * console.log(status?.[0]?.[0]); // 'valid'
+   *
+   * const status2 = await fWorksheet.getRange('B2').getValidatorStatus();
+   * console.log(status2?.[0]?.[0]); // 'invalid'
    * ```
    */
   requireDateEqualTo(e) {
@@ -168,10 +255,20 @@ class E {
    * @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'))
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateNotBetween(new Date('2024-06-01'), new Date('2025-06-01'))
    *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['valid', 'invalid', 'invalid', 'valid']]
    * ```
    */
   requireDateNotBetween(e, t) {
@@ -183,8 +280,20 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireDateOnOrAfter(new Date('2024-01-01')).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateOnOrAfter(new Date('2025-01-01'))
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['invalid', 'invalid', 'valid', 'valid']]
    * ```
    */
   requireDateOnOrAfter(e) {
@@ -196,8 +305,20 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireDateOnOrBefore(new Date('2024-12-31')).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * fRange.setValues([
+   *   ['2024-01-01', '2024-12-31'],
+   *   ['2025-01-01', '2025-12-31']
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireDateOnOrBefore(new Date('2025-01-01'))
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['valid', 'valid', 'valid', 'invalid']]
    * ```
    */
   requireDateOnOrBefore(e) {
@@ -205,12 +326,33 @@ class E {
   }
   /**
    * Requires that a custom formula be satisfied
-   * @param {string} formula - The formula string that needs to 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
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireFormulaSatisfied('=A1>0').build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const cell = fWorksheet.getRange('A1:B2');
+   * cell.setValues([
+   *   [4, 3],
+   *   [2, 1]
+   * ]);
+   * const fRange = fWorksheet.getRange('C1:D2');
+   * fRange.setValues([
+   *   [1, 2],
+   *   [3, 4]
+   * ]);
+   * const rule = univerAPI.newDataValidation()
+   *   .requireFormulaSatisfied('=A1>2')
+   *   .setOptions({
+   *     showErrorMessage: true,
+   *     error: 'Please enter a value equal to A1'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const status = await fRange.getValidatorStatus();
+   * console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
    * ```
    */
   requireFormulaSatisfied(e) {
@@ -224,8 +366,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberBetween(1, 10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberBetween(1, 10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number between 1 and 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberBetween(e, t, i) {
@@ -238,8 +390,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberEqualTo(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberEqualTo(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number equal to 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberEqualTo(e, t) {
@@ -252,8 +414,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberGreaterThan(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberGreaterThan(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number greater than 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberGreaterThan(e, t) {
@@ -266,8 +438,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberGreaterThanOrEqualTo(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberGreaterThanOrEqualTo(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number greater than 10 or equal to 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberGreaterThanOrEqualTo(e, t) {
@@ -280,8 +462,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberLessThan(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberLessThan(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number less than 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberLessThan(e, t) {
@@ -295,8 +487,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberLessThanOrEqualTo(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberLessThanOrEqualTo(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number less than 10 or equal to 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberLessThanOrEqualTo(e, t) {
@@ -311,8 +513,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberNotBetween(1, 10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberNotBetween(1, 10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number not between 1 and 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberNotBetween(e, t, i) {
@@ -326,8 +538,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireNumberNotEqualTo(10).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberNotEqualTo(10)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a number not equal to 10'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireNumberNotEqualTo(e, t) {
@@ -342,8 +564,18 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.requireValueInList(['Yes', 'No']).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setOptions({
+   *     allowBlank: true,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a value from the list'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   requireValueInList(e, t, i) {
@@ -358,9 +590,24 @@ class E {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('B1:B2');
+   * fRange.setValues([
+   *   ['Yes'],
+   *   ['No']
+   * ]);
+   *
+   * const rule = univerAPI.newDataValidation()
+   *   .requireValueInRange(fRange)
+   *   .setOptions({
+   *     allowBlank: false,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a value from the list'
+   *   })
+   *   .build();
+   * const cell = fWorksheet.getRange('A1');
+   * cell.setDataValidation(rule);
    * ```
    */
   requireValueInRange(e, t, i) {
@@ -378,8 +625,24 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.setAllowInvalid(true).build();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   *
+   * // Set the data validation for cell A1:B2 to allow invalid data, so A1:B2 will display a warning when invalid data is entered
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setAllowInvalid(true)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * // Set the data validation for cell C1:D2 to not allow invalid data, so C1:D2 will stop data entry when invalid data is entered
+   * const fRange2 = fWorksheet.getRange('C1:D2');
+   * const rule2 = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setAllowInvalid(false)
+   *   .build();
+   * fRange2.setDataValidation(rule2);
    * ```
    */
   setAllowInvalid(e) {
@@ -391,8 +654,25 @@ class E {
    * @returns {FDataValidationBuilder} The current instance for method chaining
    * @example
    * ```typescript
-   * const builder = univerAPI.newDataValidation();
-   * const rule = builder.setAllowBlank(true).build();
+   * // Assume current sheet is empty data
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   *
+   * // Set the data validation for cell A1:B2 to allow blank values
+   * const fRange = fWorksheet.getRange('A1:B2');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setAllowBlank(true)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * // Set the data validation for cell C1:D2 to not allow blank values
+   * const fRange2 = fWorksheet.getRange('C1:D2');
+   * const rule2 = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setAllowBlank(false)
+   *   .build();
+   * fRange2.setDataValidation(rule2);
    * ```
    */
   setAllowBlank(e) {
@@ -404,12 +684,18 @@ class E {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireValueInList(['Yes', 'No'])
+   *   .setOptions({
+   *     allowBlank: true,
+   *     showErrorMessage: true,
+   *     error: 'Please enter a value from the list'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(rule);
    * ```
    */
   setOptions(e) {
@@ -428,12 +714,12 @@ class _ {
    * @returns {boolean} true if invalid data is allowed, false otherwise
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const allowsInvalid = dataValidation.getAllowInvalid();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const rules = fWorksheet.getDataValidations();
+   * rules.forEach((rule) => {
+   *   console.log(rule, rule.getAllowInvalid());
+   * });
    * ```
    */
   getAllowInvalid() {
@@ -444,12 +730,12 @@ class _ {
    * @returns {DataValidationType | string} The data validation type
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const type = dataValidation.getCriteriaType();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const rules = fWorksheet.getDataValidations();
+   * rules.forEach((rule) => {
+   *   console.log(rule, rule.getCriteriaType());
+   * });
    * ```
    */
   getCriteriaType() {
@@ -460,12 +746,15 @@ class _ {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const rules = fWorksheet.getDataValidations();
+   * rules.forEach((rule) => {
+   *   console.log(rule);
+   *   const criteriaValues = rule.getCriteriaValues();
+   *   const [operator, formula1, formula2] = criteriaValues;
+   *   console.log(operator, formula1, formula2);
+   * });
    * ```
    */
   getCriteriaValues() {
@@ -476,12 +765,19 @@ class _ {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * 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);
+   * console.log(fRange.getDataValidation().getHelpText()); // 'Please enter a number between 1 and 10'
    * ```
    */
   getHelpText() {
@@ -492,13 +788,27 @@ class _ {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * 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);
+   *
+   * const builder = fRange.getDataValidation().copy();
+   * const newRule = builder
+   *   .requireNumberBetween(1, 5)
+   *   .setOptions({
+   *     error: 'Please enter a number between 1 and 5'
+   *   })
+   *   .build();
+   * fRange.setDataValidation(newRule);
    * ```
    */
   copy() {
@@ -509,12 +819,15 @@ class _ {
    * @returns {boolean} true if the rule is applied, false otherwise
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const isApplied = dataValidation.getApplied();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const rules = fWorksheet.getDataValidations();
+   * rules.forEach((rule) => {
+   *   console.log(rule, rule.getApplied());
+   * });
+   *
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * console.log(fRange.getDataValidation()?.getApplied());
    * ```
    */
   getApplied() {
@@ -528,12 +841,16 @@ class _ {
    * @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();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const rules = fWorksheet.getDataValidations();
+   * rules.forEach((rule) => {
+   *   console.log(rule);
+   *   const ranges = rule.getRanges();
+   *   ranges.forEach((range) => {
+   *     console.log(range.getA1Notation());
+   *   });
+   * });
    * ```
    */
   getRanges() {
@@ -547,12 +864,10 @@ class _ {
    * @returns {string | undefined} The unit ID of the worksheet
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const unitId = dataValidation.getUnitId();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * console.log(fRange.getDataValidation().getUnitId());
    * ```
    */
   getUnitId() {
@@ -564,12 +879,10 @@ class _ {
    * @returns {string | undefined} The sheet ID of the worksheet
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const sheetId = dataValidation.getSheetId();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * console.log(fRange.getDataValidation().getSheetId());
    * ```
    */
   getSheetId() {
@@ -584,15 +897,17 @@ class _ {
    * @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
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberEqualTo(20)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * fRange.getDataValidation().setCriteria(
+   *   univerAPI.Enum.DataValidationType.DECIMAL,
+   *   [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10']
    * );
    * ```
    */
@@ -618,12 +933,15 @@ class _ {
    * @returns {FDataValidation} The current instance for method chaining
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * dataValidation.setOptions({
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberEqualTo(20)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * fRange.getDataValidation().setOptions({
    *   allowBlank: true,
    *   showErrorMessage: true,
    *   error: 'Please enter a valid value'
@@ -649,13 +967,16 @@ class _ {
    * @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]);
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberEqualTo(20)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * const newRuleRange = fWorksheet.getRange('C1:D10');
+   * fRange.getDataValidation().setRanges([newRuleRange]);
    * ```
    */
   setRanges(e) {
@@ -673,12 +994,15 @@ class _ {
    * @returns {boolean} true if the rule is deleted successfully, false otherwise
    * @example
    * ```typescript
-   * const dataValidation = univerAPI
-   *   .getActiveWorkbook()
-   *   .getActiveWorksheet()
-   *   .getActiveRange()
-   *   .getDataValidation();
-   * const isDeleted = dataValidation.delete();
+   * const fWorkbook = univerAPI.getActiveWorkbook();
+   * const fWorksheet = fWorkbook.getActiveSheet();
+   * const fRange = fWorksheet.getRange('A1:B10');
+   * const rule = univerAPI.newDataValidation()
+   *   .requireNumberEqualTo(20)
+   *   .build();
+   * fRange.setDataValidation(rule);
+   *
+   * fRange.getDataValidation().delete();
    * ```
    */
   delete() {