数据验证

数据验证是一种在单元格中设置规则的功能,以确保输入的数据符合特定要求。它可以帮助用户避免输入错误,提高数据的准确性和一致性。

目前支持以下数据验证类型:

  • 数字
  • 整数
  • 文本长度
  • 日期
  • 复选框
  • 下拉列表(单选/多选)
  • 自定义公式

预设模式

安装

Shell
pnpm add @univerjs/preset-sheets-data-validation

使用

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation'import UniverPresetSheetsDataValidationZhCN from '@univerjs/preset-sheets-data-validation/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-data-validation/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDataValidationZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDataValidationPreset(),   ],})

预设与配置

TypeScript
UniverSheetsDataValidationPreset({  /**   * 是否在下拉菜单中显示编辑按钮   * @default true   */  showEditOnDropdown: true,  /**   * 是否在下拉菜单中显示搜索框   * @default true   */  showSearchOnDropdown: true,})

完整的配置项参考 IUniverSheetsDataValidationPresetConfig

插件模式

安装

Shell
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui

使用

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDataValidationPlugin } from '@univerjs/data-validation'import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation'import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui'import SheetsDataValidationZhCN from '@univerjs/sheets-data-validation-ui/locale/zh-CN'import '@univerjs/sheets-data-validation-ui/lib/index.css'import '@univerjs/sheets-data-validation/facade'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsDataValidationZhCN,     ),  },})univer.registerPlugin(UniverDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationPlugin)univer.registerPlugin(UniverSheetsDataValidationUIPlugin)

插件与配置

TypeScript
univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {  /**   * 是否在下拉菜单中显示编辑按钮   * @default true   */  showEditOnDropdown: true,  /**   * 是否在下拉菜单中显示搜索框   * @default true   */  showSearchOnDropdown: true,})

完整的配置项参考 IUniverSheetsDataValidationUIConfig

Facade API

完整 Facade API 类型定义,请查看 FacadeAPI

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包,无需额外导入。

TypeScript
import '@univerjs/sheets-data-validation/facade'

添加一个数据验证规则

univerAPI.newDataValidation() 可以创建一个新的数据验证构建器,返回一个 FDataValidationBuilder 实例,可以通过链式调用生成数据验证规则。

以下是 FDataValidationBuilder 上的一些成员方法:

方法描述
build构建数据验证规则
requireCheckbox设置数据验证规则,要求输入为布尔值;该值将呈现为复选框
requireDateAfter将数据验证类型设置为 DATE,并配置验证规则为在特定日期之后
requireDateBefore将数据验证类型设置为 DATE,并配置验证规则为在特定日期之前
requireDateBetween将数据验证类型设置为 DATE,并配置验证规则为在特定日期范围内
requireDateEqualTo将数据验证类型设置为 DATE,并配置验证规则为等于特定日期
requireDateNotBetween将数据验证类型设置为 DATE,并配置验证规则为不在特定日期范围内
requireDateOnOrAfter将数据验证类型设置为 DATE,并将验证规则配置为特定日期或之后
requireDateOnOrBefore将数据验证类型设置为 DATE,并将验证规则配置为特定日期或之前
requireFormulaSatisfied设置数据验证规则要求给定公式求值为 true
requireNumberBetween设置数据验证规则要求数字在两个指定数字之间,或者是其中之一
requireNumberEqualTo设置数据验证规则要求数字等于给定值
requireNumberGreaterThan设置数据验证规则要求数字大于给定值
requireNumberGreaterThanOrEqualTo设置数据验证规则要求数字大于或等于给定值
requireNumberLessThan设置数据验证规则要求数字小于给定值
requireNumberLessThanOrEqualTo设置数据验证规则要求数字小于或等于给定值
requireNumberNotBetween设置数据验证规则要求数字不在两个指定数字之间,也不是其中之一
requireNumberNotEqualTo设置数据验证规则要求数字不等于给定值
requireValueInList设置数据验证规则,要求用户从特定值列表中输入一个值。支持单选/多选,支持显示/隐藏下拉框
requireValueInRange设置数据验证规则,要求用户输入特定范围内的值。支持单选/多选,支持显示/隐藏下拉框
setOptions设置数据验证规则的选项
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 创建一个新的数据验证规则,要求 A1:B10 范围内的数字在 1 到 10 之间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)

清除 Range 的数据验证规则

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 清除 A1:B10 范围内的数据验证规则const fRange = fWorksheet.getRange('A1:B10')fRange.setDataValidation(null)

获取 Range/Worksheet 的数据验证规则

返回的数据验证规则对象是一个 FDataValidation 实例,可以通过该实例获取验证规则的条件、选项等。

以下是 FDataValidation 上的一些成员方法:

方法描述
copy使用当前规则对象创建一个新的 FDataValidationBuilder 实例
getCriteriaType获取数据验证规则的类型
getCriteriaValues获取数据验证规则的条件值
getHelpText获取帮助文本信息,用于为用户提供指导和支持
getRanges获取数据验证规则的应用范围
setCriteria设置数据验证规则的条件值
setOptions设置数据验证规则的选项
setRanges设置数据验证规则的应用范围
delete从工作表中删除数据验证规则
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 获取当前工作表的所有数据验证规则const rulesOfSheet = fWorksheet.getDataValidations()// 通过规则 ID 获取数据验证规则const ruleById = fWorksheet.getDataValidation(rulesOfSheet[0]?.rule?.uid)const fRange = fWorksheet.getRange('A1:B10')// 获取当前范围的第一个数据验证规则const ruleOfRange = fRange.getDataValidation()ruleOfRange?.getCriteriaValues()// 获取当前范围的所有数据验证规则const rulesOfRange = fRange.getDataValidations()

更新/删除数据验证

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 创建一个新的数据验证规则,要求 A1:B10 范围内的数字等于 20const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI.newDataValidation()  .requireNumberEqualTo(20)  .build()fRange.setDataValidation(rule)const newRuleRange = fWorksheet.getRange('C1:D10')// 3 秒后更新规则setTimeout(() => {  fRange.getDataValidation()    // 更改新的范围 C1:D10    .setRanges([newRuleRange])    // 更改新的条件,要求数字在 1 到 10 之间    .setCriteria(      univerAPI.Enum.DataValidationType.DECIMAL,      [univerAPI.Enum.DataValidationOperator.BETWEEN, '1', '10'],    )    // 更改验证选项,当输入不符合条件时停止输入并显示错误消息    .setOptions({      allowBlank: true,      showErrorMessage: true,      error: 'Please enter a valid value',      errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,    })}, 3000)// 6 秒后删除该规则setTimeout(() => {  newRuleRange.getDataValidation().delete()}, 6000)

获取验证错误

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 获取当前工作簿的所有数据验证错误const workbookErrors = await fWorkbook.getAllDataValidationErrorAsync()console.log('workbookErrors:', workbookErrors)// 获取当前工作表的所有数据验证错误const worksheetErrors = await fWorksheet.getAllDataValidationErrorAsync()console.log('worksheetErrors:', worksheetErrors)// 获取当前范围的数据验证错误const fRange = fWorksheet.getRange('A1:B10')const rangeErrors = await fRange.getDataValidationErrorAsync()console.log('rangeErrors:', rangeErrors)

每个错误对象包含以下字段:

  • sheetName:发生错误的工作表名称
  • row:触发错误的单元格行索引
  • column:触发错误的单元格列索引
  • ruleId:触发错误的规则 ID
  • inputValue:触发错误的输入值
  • rule:规则内容快照

查询校验状态

校验状态是 DataValidationStatus 的枚举值,包括:

  • valid:单元格值通过验证
  • invalid:单元格值未通过验证
  • validating:单元格正在验证中
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 获取当前工作簿的数据验证校验状态fWorkbook.getValidatorStatus().then((status) => {})// 获取当前工作表的数据验证校验状态fWorksheet.getValidatorStatusAsync().then((status) => {})// 获取当前范围的数据验证校验状态const fRange = fWorksheet.getRange('A1:B10')fRange.getValidatorStatus().then((status) => {})

事件监听

完整事件类型定义,请查看 Events

数据验证模块提供了一系列事件用于监听验证规则的添加、更新、删除和验证状态变更。所有事件都可以通过 univerAPI.addEvent() 进行监听。

验证规则变更事件

univerAPI.Event.SheetDataValidationChanged: 验证规则变更后触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {  const { origin, worksheet, workbook, changeType, oldRule, rule } = params})// 移除事件监听器,使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationAdd: 添加验证规则前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {  const { worksheet, workbook, rule } = params  // 取消添加验证规则操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDelete: 删除验证规则前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {  const { worksheet, workbook, ruleId, rule } = params  // 取消删除验证规则操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationDeleteAll: 删除所有验证规则前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {  const { worksheet, workbook, rules } = params  // 取消删除所有验证规则操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

验证规则更新事件

univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate: 更新验证规则条件前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newCriteria } = params  // 取消更新验证规则条件操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationRangeUpdate: 更新验证规则范围前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newRanges } = params  // 取消更新验证规则范围操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetDataValidationOptionsUpdate: 更新验证规则选项前触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {  const { worksheet, workbook, ruleId, rule, newOptions } = params  // 取消更新验证规则选项操作  params.cancel = true})// 移除事件监听器,使用 `disposable.dispose()`

验证状态事件

univerAPI.Event.SheetDataValidatorStatusChanged: 单元格验证状态变更时触发

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => {  const { worksheet, workbook, row, column, status, rule } = params})// 移除事件监听器,使用 `disposable.dispose()`

每个事件都包含以下通用参数:

  • workbook: 当前工作簿实例
  • worksheet: 当前工作表实例

特殊参数:

  • rule: 相关的验证规则对象
  • ruleId: 验证规则的唯一标识符
  • status: 验证状态(仅在 SheetDataValidatorStatusChanged 事件中)
  • newCriteria: 新的验证条件(仅在 BeforeSheetDataValidationCriteriaUpdate 事件中)
  • newRanges: 新的验证范围(仅在 BeforeSheetDataValidationRangeUpdate 事件中)
  • newOptions: 新的验证选项(仅在 BeforeSheetDataValidationOptionsUpdate 事件中)

所有 Before 前缀的事件回调函数都可以使用 params.cancel = true 来阻止对应的操作。

错误样式

errorStyle 选项控制输入无效数据时的行为。它是 DataValidationErrorStyle 的枚举值,包括:

  • STOP:阻止用户输入无效数据
  • WARNING:允许用户输入无效数据,但显示警告
  • INFO:允许用户输入无效数据,但显示信息提示
TypeScript
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: '请输入 1 到 10 之间的数字',    errorStyle: univerAPI.Enum.DataValidationErrorStyle.STOP,  })  .build()fRange.setDataValidation(rule)

变更列表型验证的渲染模式

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B10')fRange.getDataValidation()?.setOptions({  // support TEXT, ARROW, CUSTOM  // default is `CUSTOM`  renderMode: univerAPI.Enum.DataValidationRenderMode.TEXT,})

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.