数据验证

预设模式插件模式

预设信息

@univerjs/preset-sheets-data-validation

需要服务端支持

否

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

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

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

预设模式

安装

npm install @univerjs/preset-sheets-data-validation

使用

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(), 
  ],
})

预设与配置

UniverSheetsDataValidationPreset({
  // 是否在下拉菜单中显示编辑按钮
  showEditOnDropdown: true,
})

完整的配置项参考 IUniverSheetsDataValidationPresetConfig。

插件模式

安装

npm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-ui

使用

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)

插件与配置

univer.registerPlugin(UniverSheetsDataValidationUIPlugin, {
  // 是否在下拉菜单中显示编辑按钮
  showEditOnDropdown: true,
})

完整的配置项参考 IUniverSheetsDataValidationUIConfig。

Facade API

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

引入

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	设置数据验证规则的选项

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 的数据验证规则

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

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

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

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

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

方法	描述
getCriteriaType	获取数据验证规则的类型
getCriteriaValues	获取数据验证规则的条件值
getHelpText	获取帮助文本信息，用于为用户提供指导和支持
getRanges	获取数据验证规则的应用范围
setCriteria	设置数据验证规则的条件值
setOptions	设置数据验证规则的选项
setRanges	设置数据验证规则的应用范围
delete	从工作表中删除数据验证规则

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 获取当前工作表的所有数据验证规则
const rulesOfSheet = fWorksheet.getDataValidations()

const fRange = fWorksheet.getRange('A1:B10')

// 获取当前范围的第一个数据验证规则
const ruleOfRange = fRange.getDataValidation()
ruleOfRange?.getCriteriaValues()

// 获取当前范围的所有数据验证规则
const rulesOfRange = fRange.getDataValidations()

更新/删除数据验证

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个新的数据验证规则，要求 A1:B10 范围内的数字等于 20
const 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)

查询校验状态

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: 验证规则变更后触发

const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => {
  const { origin, worksheet, workbook, changeType, oldRule, rule } = params
})

// 移除事件监听器，使用 `disposable.dispose()`

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => {
  const { worksheet, workbook, rule } = params

  // 取消添加验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => {
  const { worksheet, workbook, ruleId, rule } = params

  // 取消删除验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => {
  const { worksheet, workbook, rules } = params

  // 取消删除所有验证规则操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

验证规则更新事件

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newCriteria } = params

  // 取消更新验证规则条件操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newRanges } = params

  // 取消更新验证规则范围操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

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

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => {
  const { worksheet, workbook, ruleId, rule, newOptions } = params

  // 取消更新验证规则选项操作
  params.cancel = true
})

// 移除事件监听器，使用 `disposable.dispose()`

验证状态事件

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

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 来阻止对应的操作。

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

dataValidation.setOptions({
  // support TEXT, ARROW, CUSTOM
  // default is `CUSTOM`
  renderMode: univerAPI.Enum.DataValidationRenderMode.TEXT,
})

目录