NocoBase 提交操作Submit完整指南表单数据保存、保存模式与工作流绑定【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase导读提交操作Submit是 NocoBase 界面构建体系中表单区块专属的操作类型负责把用户在表单中填写的数据校验后写入数据源并在此基础上支持与工作流联动实现数据自动化处理。本文以官方文档为主体结合packages/core/client与packages/core/database中的真实源码实现系统讲解提交操作的适用场景、全部配置项含保存模式、字段赋值、跳过校验、提交后行为、底层数据写入链路以及与工作流绑定的执行规则帮助你从“会用按钮”进阶到“理解其内部机制”在搭建业务系统时做出更准确的配置决策。提交操作简介提交操作用于保存表单数据它只出现在表单类区块中如“新增表单”“编辑表单”区块是表单区块配置操作按钮时最核心的入口。与普通按钮不同提交操作天然承担三件事收集表单值读取当前表单中所有字段的输入值写入数据源调用对应的数据资源Resource执行创建或更新触发后续流程数据保存成功后刷新数据块、关闭弹窗、跳转页面以及触发绑定的工作流。从源码看提交操作在前端是一个标准的 Schema 配置。在 CreateSubmitActionInitializer.tsx 中新增表单的提交按钮 schema 定义如下const schema { title: {{ t(Submit) }}, x-action: submit, x-component: Action, x-use-component-props: useCreateActionProps, x-toolbar: ActionSchemaToolbar, x-settings: actionSettings:createSubmit, x-component-props: { type: primary, htmlType: submit, }, };而编辑表单场景对应 UpdateSubmitActionInitializer.tsx区别仅在于x-use-component-props为useUpdateActionProps、x-settings为actionSettings:updateSubmit。可见x-action: submit标识这是一个提交操作htmlType: submit让按钮在原生表单语义下可被回车等触发x-use-component-props指向具体的提交逻辑 Hook创建或更新x-settings指向该操作可用的配置面板下文详述。操作配置项总览选中表单区块中的提交按钮通过右侧“配置”面板可以调整一系列行为。这些配置项并非写死而是由 SchemaSettings 动态注册的。在 createSubmitActionSettings.tsx 中新增表单提交按钮的配置项按顺序为配置项说明备注编辑按钮修改按钮标题、图标、按钮样式等对应 edit-button.md联动规则动态控制按钮的显示 / 隐藏 / 禁用状态对应 linkage-rule.md二次确认点击后弹出确认框防止误操作对应 double-check.md保存模式选择 insert / firstOrCreate / updateOrCreate 及判定字段公开表单区块不显示此项字段赋值提交时附加固定的字段值如当前用户、当前时间跳过必填校验提交时跳过表单必填字段的校验批量编辑表单中不显示提交成功后配置成功提示、关闭弹窗、跳转等公开表单区块不显示刷新数据块请求提交后刷新父级数据块的数据仅当表单位于弹窗中且有父记录时显示编辑更新场景的配置面板见 updateSubmitActionSettings.tsx其结构大致相同但“保存模式”不在其中更新提交天然走 update 语义并额外限制当表单属于“批量编辑”时字段赋值与跳过必填校验同样不可用。此外无论新增还是更新配置面板中都包含“绑定工作流”入口用于把提交动作与自动化流程关联详见下文专节。保存模式Insert / Insert if not exists / Insert or update这是新增表单提交按钮最具业务价值的配置。当表单并非以“主键存在与否”来决定创建还是更新时例如以手机号、编号等业务字段判定可通过“保存模式”控制数据写入方式。源码 createSubmitActionSettings.tsx 中定义了三种模式模式值界面文案行为create插入Insert始终新增一条记录不做存在性判断firstOrCreate不存在则插入Insert if not exists按指定字段查询存在则直接返回已有记录不存在则新增updateOrCreate不存在则插入否则更新Insert if not exists, or update按指定字段查询存在则更新该记录不存在则新增选择firstOrCreate或updateOrCreate后需要勾选“通过以下字段判断记录是否存在”filterKeys——可以是一个或多个字段含关联字段系统会按这些字段的值去数据源中匹配。底层实现原理前端把saveMode与filterKeys写入按钮的x-component-props。在 useCreateActionProps 中提交时按当前记录是否为新记录决定动作名并携带 filterKeys 调用数据资源const action record.isNew ? actionField.componentProps.saveMode || create : update; const filterKeys actionField.componentProps.filterKeys?.checked || []; // ... const data await resourceaction;即当record.isNew为 true 时才会使用配置的保存模式若该表单是编辑已有记录则直接走update。服务端侧动作分发到 create.ts 等资源动作处理器而firstOrCreate/updateOrCreate的真正实现在数据仓库层 repository.tsasync firstOrCreate(options: FirstOrCreateOptions) { const { filterKeys, values, transaction, context, ...rest } options; const filter Repository.valuesToFilter(values, filterKeys); const instance await this.findOne({ filter, transaction, context }); if (instance) return instance; return this.create({ values, transaction, context, ...rest }); } async updateOrCreate(options: FirstOrCreateOptions) { const { filterKeys, values, transaction, context, ...rest } options; const filter Repository.valuesToFilter(values, filterKeys); const instance await this.findOne({ filter, transaction, context }); if (instance) { return await this.update({ filterByTk: instance.get(this.collection.filterTargetKey || this.collection.model.primaryKeyAttribute), values, transaction, context, ...rest, }); } return this.create({ values, transaction, context, ...rest }); }两个方法的区别清晰可见firstOrCreate命中已有记录时原样返回updateOrCreate命中时则用表单值更新该记录。Repository.valuesToFilter会把表单值按 filterKeys 组装成查询条件因此 filterKeys 的字段必须有值且能唯一标识记录否则可能出现“每次都判定为不存在”的重复插入。这也是配置该项时需要重点检查的前提。表单校验与跳过必填校验提交操作默认会执行表单校验。在 useCreateActionProps 中const { onSuccess, skipValidator, triggerWorkflows } actionSchema?.[x-action-settings] ?? {}; // ... if (!skipValidator) { await form.submit(); } const values await collectValues();form.submit()来自 Formily会触发表单全部字段的规则校验必填、格式、自定义规则等校验不通过时抛出异常提交中断开启“跳过必填校验”后skipValidator为 true校验步骤被跳过直接收集值并写入collectValues负责把表单值与“字段赋值”中配置的固定值合并形成最终的写入数据。配置建议仅当业务上确实允许空值入库如后台批量导入、中间态草稿时才开启跳过校验常规面向用户的数据录入应保持校验开启避免脏数据。提交成功后行为“提交成功后”配置控制数据写入完成后的反馈与跳转其逻辑同样集中在useCreateActionProps/useUpdateActionProps中支持成功提示默认提示“保存成功”Saved successfully可自定义提示文案并可设置为手动关闭弹窗方式或自动关闭message 方式关闭弹窗默认提交成功后关闭所在弹窗actionAfterSuccess缺省时回到上一级跳转可配置跳转地址支持变量跳转目标为站内路由时使用前端路由跳转为外部 URL 时使用window.location.href跳转重置表单成功后调用resetFormCorrectly正确重置表单状态并同步setSubmitted、setFormValueChanged等上下文标志。相关 UI 组件定义于 Action.Designer.tsx 中的AfterSuccess第 382 行附近以及RefreshDataBlockRequest第 858 行附近。刷新数据块请求当提交表单位于弹窗/抽屉中且弹窗由列表页等父级数据块打开时配置面板会出现“刷新数据块请求”项。开启后提交成功会刷新父级数据块使列表、统计等立即反映新写入的数据无需手动刷新页面。源码中该项通过useVisible判断useParentPopupRecord()是否存在父级记录来决定是否展示见 createSubmitActionSettings.tsx 第 199-202 行与界面“只有弹窗场景才需要刷新父级”的直觉一致。绑定工作流数据提交成功后才触发提交操作可以与工作流绑定实现“保存数据后自动执行一系列自动化步骤”如发通知、调用外部接口、级联更新其他表。关键约束是只有在数据提交成功后才会触发绑定的工作流——这意味着工作流触发条件是“提交成功”这一确定事件不会因校验失败或写入失败而触发。支持绑定的工作流事件类型参见 bind-workflow.md操作按钮 \ 工作流类型操作前事件操作后事件审批事件自定义操作事件表单的“提交”、“保存”按钮✅✅✅❌一个提交按钮可以同时绑定多个工作流多个工作流的执行顺序规则为同一触发类型下同步工作流先于异步工作流执行同一触发类型的工作流按配置顺序执行不同触发类型之间操作前事件一定先于操作后与审批事件操作后与审批事件之间没有特定顺序业务不应依赖其配置顺序。前端提交逻辑中绑定的工作流通过x-action-settings.triggerWorkflows传递useCreateActionProps把工作流键与上下文拼成workflowKey!context的逗号分隔串随请求提交从而让服务端在写入成功后按事件分发执行见 block-provider/hooks/index.ts。这也解释了为何“提交成功后才触发”——工作流参数与数据写入在同一请求内完成服务端只在数据落库成功后推进事件。工作流的完整事件类型说明可继续查阅工作流插件文档在操作配置层面记住“绑定工作流 提交成功触发”这一对关系即可。与相关操作类型的边界提交操作属于表单数据写入类操作与以下操作容易混淆使用时注意区分编辑按钮属于按钮外观与行为的基础设置任何操作都可用提交操作只是其中一员二次确认给提交操作加一道确认拦截防止误提交属于提交操作的增强配置联动规则按表单字段值动态控制提交按钮的启用/隐藏状态例如“未填写手机号时禁止提交”更新数据操作Update record作用于数据行表格、列表等而非表单直接更新指定记录触发工作流操作Trigger workflow按钮仅用于触发“自定义操作事件”工作流不写入数据。从配置面板的注册顺序可以看出提交操作 “编辑按钮 联动规则 二次确认”三类通用设置再加上“保存模式 / 字段赋值 / 跳过校验 / 提交成功后 / 刷新数据块 / 绑定工作流”这些专属能力。理解这个层次配置时就能快速定位每一项的作用域。总结提交操作是表单区块保存数据的唯一入口由x-action: submit的 Schema 驱动新增与编辑场景分别使用useCreateActionProps与useUpdateActionProps执行写入配置面板的每一项都有明确的源码依据保存模式对应 Repository 的firstOrCreate/updateOrCreate实现跳过校验对应skipValidator分支提交后行为对应AfterSuccess逻辑保存模式中 filterKeys 的字段值必须能唯一判定记录否则会重复插入绑定工作流遵循“提交成功后才触发”的约定多工作流按同步优先、配置顺序、操作前优先于操作后的规则执行如需继续深入可阅读 createSubmitActionSettings.tsx、updateSubmitActionSettings.tsx、useCreateActionProps 及 repository.ts 的实现。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考