告别数据混乱：Univer自定义数据验证规则完全指南

2026-02-05 05:03:13作者：廉皓灿Ida

Univer is a set of enterprise document and data collaboration solutions, including spreadsheets, documents, and slides. The highly extensible design allows developers to customize personalized functions based on Univer.

项目地址：https://gitcode.com/GitHub_Trending/un/univer

你是否还在为表格中的错误数据头疼？销售报表里的电话号码格式错乱、库存表中的数量出现负数、客户信息表的邮箱格式五花八门——这些问题不仅浪费大量核对时间，更可能导致决策失误。Univer电子表格（Spreadsheets）的数据验证功能正是为解决这类问题而生，通过可视化配置即可实现数据校验规则，让错误数据无处遁形。本文将带你从零开始掌握自定义校验规则的创建方法，以及如何设置友好的错误提示，让你的数据管理效率提升300%。

数据验证基础：为什么它如此重要

在企业协作场景中，数据准确性直接影响业务决策质量。Univer的数据验证功能通过预设规则限制单元格输入范围，在数据录入阶段就拦截错误，避免后续繁琐的人工核对。其核心价值体现在三个方面：

实时校验：输入时即时反馈错误，无需等待提交后检查
规则复用：一次配置可应用于多个单元格区域
用户引导：通过自定义提示语指导正确输入格式

Univer的数据验证模块由@univerjs/sheets-data-validation提供核心能力，配合@univerjs/sheets-data-validation-ui实现可视化配置界面，形成完整的"规则定义-校验执行-错误展示"闭环。

图1：数据验证规则触发时的错误提示效果，红色边框与自定义消息帮助用户快速修正输入

开箱即用：基础验证规则速查表

Univer内置了六大类常用验证规则，覆盖90%的日常数据校验场景。通过简单配置即可实现对数值范围、文本长度、日期区间等常见约束的控制：

规则类型	应用场景	关键参数	示例配置
数值范围	库存数量、年龄限制	最小值/最大值、是否包含边界	1 ≤ 库存 ≤ 1000
日期区间	项目排期、生日录入	开始日期/结束日期	入职日期 ≥ 2023-01-01
文本长度	用户名、工号	最小长度/最大长度	密码长度 6-20 字符
列表选项	部门选择、状态标记	下拉选项列表	["市场部","研发部","销售部"]
邮箱格式	客户联系方式	-	自动校验标准邮箱格式
复选框	完成状态、是否确认	-	勾选表示"已审核"

这些规则可通过右键菜单"数据验证"快速配置，无需编写任何代码。例如创建"性别选择"下拉列表时，只需在规则类型中选择"列表"，输入"男,女,保密"即可生成带下拉选项的单元格。

进阶技巧：自定义校验规则开发

对于复杂业务场景，内置规则可能无法满足需求。Univer提供两种扩展方式实现自定义验证：通过JSON配置高级规则，或使用API编写自定义校验函数。

JSON配置高级规则

在初始化工作簿时，可通过配置文件定义复杂验证规则。以下示例创建一个"手机号格式验证"，仅允许11位数字且以13/15/18开头：

// 完整代码示例见[examples/src/sheets/main.ts](https://gitcode.com/GitHub_Trending/un/univer/blob/38b7063c6cdabc840559c6ec89e814f76048c56c/examples/src/sheets/main.ts?utm_source=gitcode_repo_files#L137)
const dataValidation = [
  {
    uid: "phone-validator",
    type: DataValidationType.CUSTOM,
    formula: 'AND(LEN(A1)=11, REGEXMATCH(A1, "^1[358]\\d{9}$"))',
    ranges: [{ startRow: 2, endRow: 100, startColumn: 1, endColumn: 1 }],
    error: {
      message: "请输入正确手机号（11位数字，以13/15/18开头）",
      style: "stop" // 阻止无效输入
    }
  }
];

API动态创建规则

通过AddSheetDataValidationCommand命令可在运行时动态添加规则，适合需要根据用户操作动态调整验证逻辑的场景：

// 核心API定义见packages/sheets-data-validation/src/commands/commands.ts
commandService.executeCommand(AddSheetDataValidationCommand.id, {
  unitId: "workbook-01",
  subUnitId: "sheet-1",
  rule: {
    uid: "dynamic-validator",
    type: DataValidationType.NUMBER,
    operator: "BETWEEN",
    value1: 0,
    value2: "=C1", // 引用C1单元格作为最大值
    ranges: [{ startRow: 5, endRow: 5, startColumn: 2, endColumn: 2 }]
  }
});