API Reference

FDataValidation

Access

Access through:

Setup

Register @univerjs/sheets-data-validation or a preset that includes it. In plugin mode, import @univerjs/sheets-data-validation/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs/sheets-data-validation

FDataValidation.copy

Creates a new instance of FDataValidationBuilder using the current rule object

TypeScript
copy(): FDataValidationBuilder

Returns

A new FDataValidationBuilder instance with the same rule configuration

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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)

Types: FDataValidationBuilder

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.delete

Delete the data validation rule from the worksheet

TypeScript
delete(): boolean

Returns

true if the rule is deleted successfully, false otherwise

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange.setDataValidation(rule)// Delete the data validation rulefRange.getDataValidation().delete()

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getAllowInvalid

Gets whether invalid data is allowed based on the error style value

TypeScript
getAllowInvalid(): boolean

Returns

true if invalid data is allowed, false otherwise

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = fWorksheet.getDataValidations()rules.forEach((rule) => {  console.log(rule, rule.getAllowInvalid())})

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getApplied

Gets whether the data validation rule is applied to the worksheet

TypeScript
getApplied(): boolean

Returns

true if the rule is applied, false otherwise

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = fWorksheet.getDataValidations()rules.forEach((rule) => {  console.log(rule, rule.getApplied())})const fRange = fWorksheet.getRange('A1:B10')console.log(fRange.getDataValidation()?.getApplied())

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getCriteriaType

Gets the data validation type of the rule

TypeScript
getCriteriaType(): DataValidationType | string

Returns

The data validation type

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = fWorksheet.getDataValidations()rules.forEach((rule) => {  console.log(rule, rule.getCriteriaType())})

Types: DataValidationType

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getCriteriaValues

Gets the values used for criteria evaluation

TypeScript
getCriteriaValues(): [string | undefined, string | undefined, string | undefined]

Returns

An array containing the operator, formula1, and formula2 values

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = fWorksheet.getDataValidations()rules.forEach((rule) => {  console.log(rule)  const criteriaValues = rule.getCriteriaValues()  const [operator, formula1, formula2] = criteriaValues  console.log(operator, formula1, formula2)})

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getHelpText

Gets the help text information, which is used to provide users with guidance and support

TypeScript
getHelpText(): string | undefined

Returns

Returns the help text information. If there is no error message, it returns an undefined value

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')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'

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getRanges

Gets the ranges to which the data validation rule is applied

TypeScript
getRanges(): FRange[]

Returns

An array of FRange objects representing the ranges to which the data validation rule is applied

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const rules = fWorksheet.getDataValidations()rules.forEach((rule) => {  console.log(rule)  const ranges = rule.getRanges()  ranges.forEach((range) => {    console.log(range.getA1Notation())  })})

Types: FRange

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getSheetId

Gets the sheet ID of the worksheet

TypeScript
getSheetId(): string | undefined

Returns

The sheet ID of the worksheet

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B10')console.log(fRange.getDataValidation().getSheetId())

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.getUnitId

Gets the unit ID of the workbook

TypeScript
getUnitId(): string | undefined

Returns

The unit ID of the workbook

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1:B10')console.log(fRange.getDataValidation().getUnitId())

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.rule

The underlying validation rule data. Use the Facade setters to update a rule attached to a worksheet.

TypeScript
rule: IDataValidationRule

Types: IDataValidationRule

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.setCriteria

Set Criteria for the data validation rule

TypeScript
setCriteria(type: DataValidationType, values: [DataValidationOperator, string, string], allowBlank?: boolean): FDataValidation

Parameters

  • type — Required. The type of data validation criteria
  • values — Required. An array containing the operator, formula1, and formula2 values
  • allowBlank — Optional. Default: true. Whether to allow blank values

Returns

The current instance for method chaining

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange.setDataValidation(rule)// Change the rule criteria to require a number between 1 and 10fRange  .getDataValidation()  .setCriteria(univerAPI.Enum.DataValidationType.DECIMAL, [    univerAPI.Enum.DataValidationOperator.BETWEEN,    '1',    '10',  ])

Types: FDataValidation · DataValidationType · DataValidationOperator

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.setOptions

Set the options for the data validation rule

TypeScript
setOptions(options: Partial<IDataValidationRuleOptions>): FDataValidation

Parameters

  • options — Required. The options to set for the data validation rule

Returns

The current instance for method chaining

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange.setDataValidation(rule)// Supplement the rule with additional optionsfRange.getDataValidation().setOptions({  allowBlank: true,  showErrorMessage: true,  error: 'Please enter a valid value',})

Types: FDataValidation · Partial · IDataValidationRuleOptions

Package: @univerjs/sheets-data-validation · Type definitions

FDataValidation.setRanges

Set the ranges to the data validation rule

TypeScript
setRanges(ranges: FRange[]): FDataValidation

Parameters

  • ranges — Required. New ranges array

Returns

The current instance for method chaining

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a new data validation rule that requires a number equal to 20 for the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation().requireNumberEqualTo(20).build()fRange.setDataValidation(rule)// Change the range to C1:D10const newRuleRange = fWorksheet.getRange('C1:D10')fRange.getDataValidation().setRanges([newRuleRange])

Types: FDataValidation · FRange

Package: @univerjs/sheets-data-validation · Type definitions

How is this guide?

© 2026 DreamNum Co., Ltd.