Univer 数据校验 Preset 使用指南基于 univerjs/preset-sheets-data-validation 快速集成数据验证能力【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univeruniverjs/preset-sheets-data-validation是 Univer 官方为 Sheets 数据校验Data Validation能力提供的开箱即用预设包。本文以该包的 README 为骨架结合仓库源码与真实示例系统讲解它的安装方式、在createUniver中的接入流程、可配置项及底层插件组成帮助你以最少的代码为 Univer 表格接入下拉选择、规则校验等数据验证功能。包概览一个 Preset 带来的完整能力集Preset预设是 Univer 提供的一种“按功能聚合插件”的分发方式。开发者无需手动逐个注册数据校验相关的插件只需引入UniverSheetsDataValidationPreset()工厂函数即可。按照 README 中的包信息表该包具备以下特征维度说明CSS需要引入样式文件见 package.json 的sideEffects: [*.css]Locales内置多语言中文、英文等通过./locales/*子路径导出Facade entry提供 Facade 入口即FUniver层的 API 扩展从源码看一个 Preset 本质上是一个IPreset对象其核心逻辑在 preset.ts 中它把三个底层插件打包在一起同时通过 index.ts 统一 re-export 了这些插件的全部导出并额外导入了univerjs/sheets-data-validation/facade使 Facade API 生效。安装与版本约束安装命令与 README 一致pnpm add univerjs/preset-sheets-data-validation # 或 npm install univerjs/preset-sheets-data-validationREADME 中特别强调了一条重要的版本约定保持所有univerjs/*包在同一版本。这在该包的 package.json 中也有体现——它通过workspace:*依赖了三个底层包peerDependencies 则要求react ^16.9.0 || ^17.0.0 || ^18.0.0 || ^19.0.0、rxjs 7.0.0说明该预设运行在 React 生态之上Univer 的 UI 层基于 React 实现使用前需确保项目满足这些依赖版本。快速接入一行 Preset 开启数据校验README 给出了最核心的用法——在createUniver的presets数组中传入UniverSheetsDataValidationPreset()import { UniverSheetsDataValidationPreset } from univerjs/preset-sheets-data-validation; // 与 createUniver 配合使用 createUniver({ presets: [UniverSheetsDataValidationPreset()] });仓库中的真实示例 examples/src/preset-sheets-core/main.ts 展示了更完整的接入形态——与其他 Sheets 预设并列注册并合并多语言资源import UniverPresetSheetsDataValidationZhCN from univerjs/preset-sheets-data-validation/locales/zh-CN; // ... const { univer, univerAPI } createUniver({ locale: LocaleType.ZH_CN, locales: { zhCN: mergeLocales( UniverPresetSheetsCoreZhCN, // ... UniverPresetSheetsDataValidationZhCN, // ... ), }, theme: defaultTheme, presets: [ UniverSheetsCorePreset(), // ... UniverSheetsDataValidationPreset(), // ... ], }); univerAPI.createWorkbook({ name: Test Sheet });这里有两个关键细节值得注意多语言资源需要手动合并Preset 本身不会自动注入 locale 文本你需要通过univerjs/preset-sheets-data-validation/locales/zh-CN之类的子路径导入再用mergeLocales合并到createUniver的locales配置中。这与 README 中“Locales: Yes”的表格说明相呼应。Preset 只负责“注册”工作簿仍需你创建UniverSheetsDataValidationPreset()只完成插件装配表格实例要另外通过univerAPI.createWorkbook(...)创建。配置项解析控制下拉面板的编辑与搜索入口UniverSheetsDataValidationPreset工厂函数接受一个可选配置对象其类型定义于 preset.tsexport interface IUniverSheetsDataValidationPresetConfig extends PickIUniverSheetsDataValidationUIConfig, showEditOnDropdown | showSearchOnDropdown { }也就是说该 Preset 对外暴露两个配置项均用于控制下拉选项面板的交互元素showEditOnDropdown是否在下拉面板中显示“编辑”入口。默认值为true依据 dropdown-manager.service.ts 中?? true的兜底逻辑。showSearchOnDropdown是否在下拉面板中显示“搜索”框用于在大量选项中快速过滤。默认值同样为true。这两个配置项最终会被透传给底层 UI 插件UniverSheetsDataValidationUIPlugin见 preset.ts并通过IConfigService存储为SHEETS_DATA_VALIDATION_UI_PLUGIN_CONFIG_KEY对应的配置在渲染下拉面板时被读取。如果你的场景希望隐藏这些入口例如面向终端用户的只读校验场景可以这样关闭UniverSheetsDataValidationPreset({ showEditOnDropdown: false, showSearchOnDropdown: false, })底层组成Preset 背后打包的三个插件从 preset.ts 的plugins数组可以看到该 Preset 实际聚合了三个插件它们分工明确、层层递进插件职责关键源码位置UniverDataValidationPlugin数据校验核心逻辑校验模型、校验器注册表、增删改命令data-validation/src/plugin.tsUniverSheetsDataValidationPluginSheets 场景适配将规则绑定到工作表/单元格范围packages/sheets-data-validation包UniverSheetsDataValidationUIPluginUI 层右键菜单、下拉面板、编辑对话框等交互packages/sheets-data-validation-ui包以核心插件UniverDataValidationPlugin为例从 plugin.ts 可以看到它的装配逻辑注册DataValidationModel规则数据模型、DataValidatorRegistryService校验器注册中心、DataValidationResourceController资源序列化/反序列化控制器并注册三条 Mutation 命令——AddDataValidationMutation、UpdateDataValidationMutation、RemoveDataValidationMutation对应数据校验规则的增、改、删。而UniverSheetsDataValidationUIPlugin则承载了前端交互其配置接口IUniverSheetsDataValidationUIConfig定义在 config.tsPreset 的showEditOnDropdown/showSearchOnDropdown正是从这里继承而来。Facade API用 FUniver 编程式操作校验规则README 的包信息表中标注了该 Preset 提供 Facade entry。这意味着一方面index.ts 直接export * from univerjs/data-validation等三个包的全部导出另一方面preset.ts 中执行了import univerjs/sheets-data-validation/facade将 Facade 扩展注册进FUniver。从源码结构看packages/sheets-data-validation/src/facade/目录下提供了一系列面向用户的 API 扩展包括f-range.ts在FRange上扩展数据校验相关方法如setDataValidator类方法f-worksheet.ts/f-workbook.ts在工作表、工作簿层级暴露规则管理入口f-data-validation.ts/f-data-validation-builder.ts规则对象与其构建器f-univer.ts/f-event.ts全局入口与校验事件订阅。因此接入 Preset 后你可以在univerAPI上以链式或声明式的方式创建校验规则、绑定到指定 Range实现“代码驱动”的数据校验而不必手动实例化底层插件。与 Web Worker 模式的兼容性Univer 支持将核心计算放到 Web Worker 中运行。仓库中 examples/src/preset-sheets-core-with-worker/main.ts 展示了在 Worker 模式下如何接入该 Presetpresets: [ UniverSheetsCorePreset({ workerURL: new Worker(new URL(./worker.js, import.meta.url), { type: module }), }), // ... UniverSheetsDataValidationPreset(), // ... ],可以看到UniverSheetsDataValidationPreset()的用法在 Worker 模式下与普通模式完全一致无需任何额外参数——数据校验规则会随工作簿资源一起在主线程与 Worker 之间同步资源序列化由DataValidationResourceController负责见 dv-resource.controller.ts。进阶探索指引如果你想深入数据校验的实现细节建议继续阅读以下仓库资源核心规则模型与变更命令data-validation-model.ts、data-validation.mutation.ts校验器注册与行为定义data-validator-registry.service.ts、validators 目录集成测试与行为测试data-validation.integration.spec.ts、data-validator.behavior.spec.tsFacade 层 API 测试f-range.spec.ts、f-data-validation-builder.spec.ts小结univerjs/preset-sheets-data-validation的价值在于把“数据校验”这一横跨核心、Sheets 适配、UI 交互三层的复杂能力收敛为一个函数调用。你只需记住三条要点即可完成集成通过 pnpm/npm 安装并保持univerjs/*版本一致在createUniver的presets中调用UniverSheetsDataValidationPreset()按需通过locales/*子路径合并多语言资源。之后无论是下拉校验、条件规则还是通过 Facade 编程式管理规则都由底层三个插件协同完成。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考