数据验证
数据验证是一种在单元格中设置规则的功能,以确保输入的数据符合特定要求。它可以帮助用户避免输入错误,提高数据的准确性和一致性。
目前支持以下数据验证类型:
- 数字
- 整数
- 文本长度
- 日期
- 复选框
- 下拉列表(单选/多选)
- 自定义公式
预设模式
安装
pnpm add @univerjs/preset-sheets-data-validationnpm install @univerjs/preset-sheets-data-validationyarn add @univerjs/preset-sheets-data-validationbun add @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({ /** * 是否在下拉菜单中显示编辑按钮 * @default true */ showEditOnDropdown: true, /** * 是否在下拉菜单中显示搜索框 * @default true */ showSearchOnDropdown: true,})完整的配置项参考 IUniverSheetsDataValidationPresetConfig。
插件模式
安装
pnpm add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uinpm install @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uiyarn add @univerjs/data-validation @univerjs/sheets-data-validation @univerjs/sheets-data-validation-uibun add @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, { /** * 是否在下拉菜单中显示编辑按钮 * @default true */ showEditOnDropdown: true, /** * 是否在下拉菜单中显示搜索框 * @default true */ showSearchOnDropdown: true,})完整的配置项参考 IUniverSheetsDataValidationUIConfig。
Facade API
完整 Facade API 类型定义,请查看 FacadeAPI
引入
插件模式提示
仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包,无需额外导入。
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 上的一些成员方法:
| 方法 | 描述 |
|---|---|
| copy | 使用当前规则对象创建一个新的 FDataValidationBuilder 实例 |
| getCriteriaType | 获取数据验证规则的类型 |
| getCriteriaValues | 获取数据验证规则的条件值 |
| getHelpText | 获取帮助文本信息,用于为用户提供指导和支持 |
| getRanges | 获取数据验证规则的应用范围 |
| setCriteria | 设置数据验证规则的条件值 |
| setOptions | 设置数据验证规则的选项 |
| setRanges | 设置数据验证规则的应用范围 |
| delete | 从工作表中删除数据验证规则 |
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()更新/删除数据验证
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)获取验证错误
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:触发错误的规则 IDinputValue:触发错误的输入值rule:规则内容快照
查询校验状态
校验状态是 DataValidationStatus 的枚举值,包括:
valid:单元格值通过验证invalid:单元格值未通过验证validating:单元格正在验证中
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 来阻止对应的操作。
错误样式
errorStyle 选项控制输入无效数据时的行为。它是 DataValidationErrorStyle 的枚举值,包括:
STOP:阻止用户输入无效数据WARNING:允许用户输入无效数据,但显示警告INFO:允许用户输入无效数据,但显示信息提示
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)变更列表型验证的渲染模式
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,})你觉得这篇文档如何?